1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997, 2002 Peter Mattis, Red Hat, Inc.
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
16 */
17
18 #include "config.h"
19
20 #include <stdarg.h>
21 #include <stdlib.h>
22 #include <stdio.h>
23
24 #include "gprintf.h"
25 #include "gprintfint.h"
26
27
28 /**
29 * g_printf:
30 * @format: a standard printf() format string, but notice
31 * [string precision pitfalls][string-precision]
32 * @...: the arguments to insert in the output.
33 *
34 * An implementation of the standard printf() function which supports
35 * positional parameters, as specified in the Single Unix Specification.
36 *
37 * As with the standard printf(), this does not automatically append a trailing
38 * new-line character to the message, so typically @format should end with its
39 * own new-line character.
40 *
41 * `glib/gprintf.h` must be explicitly included in order to use this function.
42 *
43 * Returns: the number of bytes printed.
44 *
45 * Since: 2.2
46 **/
47 gint
g_printf(gchar const * format,...)48 g_printf (gchar const *format,
49 ...)
50 {
51 va_list args;
52 gint retval;
53
54 va_start (args, format);
55 retval = g_vprintf (format, args);
56 va_end (args);
57
58 return retval;
59 }
60
61 /**
62 * g_fprintf:
63 * @file: (not nullable): the stream to write to.
64 * @format: a standard printf() format string, but notice
65 * [string precision pitfalls][string-precision]
66 * @...: the arguments to insert in the output.
67 *
68 * An implementation of the standard fprintf() function which supports
69 * positional parameters, as specified in the Single Unix Specification.
70 *
71 * `glib/gprintf.h` must be explicitly included in order to use this function.
72 *
73 * Returns: the number of bytes printed.
74 *
75 * Since: 2.2
76 **/
77 gint
g_fprintf(FILE * file,gchar const * format,...)78 g_fprintf (FILE *file,
79 gchar const *format,
80 ...)
81 {
82 va_list args;
83 gint retval;
84
85 va_start (args, format);
86 retval = g_vfprintf (file, format, args);
87 va_end (args);
88
89 return retval;
90 }
91
92 /**
93 * g_sprintf:
94 * @string: A pointer to a memory buffer to contain the resulting string. It
95 * is up to the caller to ensure that the allocated buffer is large
96 * enough to hold the formatted result
97 * @format: a standard printf() format string, but notice
98 * [string precision pitfalls][string-precision]
99 * @...: the arguments to insert in the output.
100 *
101 * An implementation of the standard sprintf() function which supports
102 * positional parameters, as specified in the Single Unix Specification.
103 *
104 * Note that it is usually better to use g_snprintf(), to avoid the
105 * risk of buffer overflow.
106 *
107 * `glib/gprintf.h` must be explicitly included in order to use this function.
108 *
109 * See also g_strdup_printf().
110 *
111 * Returns: the number of bytes printed.
112 *
113 * Since: 2.2
114 **/
115 gint
g_sprintf(gchar * string,gchar const * format,...)116 g_sprintf (gchar *string,
117 gchar const *format,
118 ...)
119 {
120 va_list args;
121 gint retval;
122
123 va_start (args, format);
124 retval = g_vsprintf (string, format, args);
125 va_end (args);
126
127 return retval;
128 }
129
130 /**
131 * g_snprintf:
132 * @string: the buffer to hold the output.
133 * @n: the maximum number of bytes to produce (including the
134 * terminating nul character).
135 * @format: a standard printf() format string, but notice
136 * [string precision pitfalls][string-precision]
137 * @...: the arguments to insert in the output.
138 *
139 * A safer form of the standard sprintf() function. The output is guaranteed
140 * to not exceed @n characters (including the terminating nul character), so
141 * it is easy to ensure that a buffer overflow cannot occur.
142 *
143 * See also g_strdup_printf().
144 *
145 * In versions of GLib prior to 1.2.3, this function may return -1 if the
146 * output was truncated, and the truncated string may not be nul-terminated.
147 * In versions prior to 1.3.12, this function returns the length of the output
148 * string.
149 *
150 * The return value of g_snprintf() conforms to the snprintf()
151 * function as standardized in ISO C99. Note that this is different from
152 * traditional snprintf(), which returns the length of the output string.
153 *
154 * The format string may contain positional parameters, as specified in
155 * the Single Unix Specification.
156 *
157 * Returns: the number of bytes which would be produced if the buffer
158 * was large enough.
159 **/
160 gint
g_snprintf(gchar * string,gulong n,gchar const * format,...)161 g_snprintf (gchar *string,
162 gulong n,
163 gchar const *format,
164 ...)
165 {
166 va_list args;
167 gint retval;
168
169 va_start (args, format);
170 retval = g_vsnprintf (string, n, format, args);
171 va_end (args);
172
173 return retval;
174 }
175
176 /**
177 * g_vprintf:
178 * @format: a standard printf() format string, but notice
179 * [string precision pitfalls][string-precision]
180 * @args: the list of arguments to insert in the output.
181 *
182 * An implementation of the standard vprintf() function which supports
183 * positional parameters, as specified in the Single Unix Specification.
184 *
185 * `glib/gprintf.h` must be explicitly included in order to use this function.
186 *
187 * Returns: the number of bytes printed.
188 *
189 * Since: 2.2
190 **/
191 gint
g_vprintf(gchar const * format,va_list args)192 g_vprintf (gchar const *format,
193 va_list args)
194 {
195 g_return_val_if_fail (format != NULL, -1);
196
197 return _g_vprintf (format, args);
198 }
199
200 /**
201 * g_vfprintf:
202 * @file: (not nullable): the stream to write to.
203 * @format: a standard printf() format string, but notice
204 * [string precision pitfalls][string-precision]
205 * @args: the list of arguments to insert in the output.
206 *
207 * An implementation of the standard fprintf() function which supports
208 * positional parameters, as specified in the Single Unix Specification.
209 *
210 * `glib/gprintf.h` must be explicitly included in order to use this function.
211 *
212 * Returns: the number of bytes printed.
213 *
214 * Since: 2.2
215 **/
216 gint
g_vfprintf(FILE * file,gchar const * format,va_list args)217 g_vfprintf (FILE *file,
218 gchar const *format,
219 va_list args)
220 {
221 g_return_val_if_fail (format != NULL, -1);
222
223 return _g_vfprintf (file, format, args);
224 }
225
226 /**
227 * g_vsprintf:
228 * @string: the buffer to hold the output.
229 * @format: a standard printf() format string, but notice
230 * [string precision pitfalls][string-precision]
231 * @args: the list of arguments to insert in the output.
232 *
233 * An implementation of the standard vsprintf() function which supports
234 * positional parameters, as specified in the Single Unix Specification.
235 *
236 * `glib/gprintf.h` must be explicitly included in order to use this function.
237 *
238 * Returns: the number of bytes printed.
239 *
240 * Since: 2.2
241 **/
242 gint
g_vsprintf(gchar * string,gchar const * format,va_list args)243 g_vsprintf (gchar *string,
244 gchar const *format,
245 va_list args)
246 {
247 g_return_val_if_fail (string != NULL, -1);
248 g_return_val_if_fail (format != NULL, -1);
249
250 return _g_vsprintf (string, format, args);
251 }
252
253 /**
254 * g_vsnprintf:
255 * @string: the buffer to hold the output.
256 * @n: the maximum number of bytes to produce (including the
257 * terminating nul character).
258 * @format: a standard printf() format string, but notice
259 * string precision pitfalls][string-precision]
260 * @args: the list of arguments to insert in the output.
261 *
262 * A safer form of the standard vsprintf() function. The output is guaranteed
263 * to not exceed @n characters (including the terminating nul character), so
264 * it is easy to ensure that a buffer overflow cannot occur.
265 *
266 * See also g_strdup_vprintf().
267 *
268 * In versions of GLib prior to 1.2.3, this function may return -1 if the
269 * output was truncated, and the truncated string may not be nul-terminated.
270 * In versions prior to 1.3.12, this function returns the length of the output
271 * string.
272 *
273 * The return value of g_vsnprintf() conforms to the vsnprintf() function
274 * as standardized in ISO C99. Note that this is different from traditional
275 * vsnprintf(), which returns the length of the output string.
276 *
277 * The format string may contain positional parameters, as specified in
278 * the Single Unix Specification.
279 *
280 * Returns: the number of bytes which would be produced if the buffer
281 * was large enough.
282 */
283 gint
g_vsnprintf(gchar * string,gulong n,gchar const * format,va_list args)284 g_vsnprintf (gchar *string,
285 gulong n,
286 gchar const *format,
287 va_list args)
288 {
289 g_return_val_if_fail (n == 0 || string != NULL, -1);
290 g_return_val_if_fail (format != NULL, -1);
291
292 return _g_vsnprintf (string, n, format, args);
293 }
294
295 /**
296 * g_vasprintf:
297 * @string: the return location for the newly-allocated string.
298 * @format: a standard printf() format string, but notice
299 * [string precision pitfalls][string-precision]
300 * @args: the list of arguments to insert in the output.
301 *
302 * An implementation of the GNU vasprintf() function which supports
303 * positional parameters, as specified in the Single Unix Specification.
304 * This function is similar to g_vsprintf(), except that it allocates a
305 * string to hold the output, instead of putting the output in a buffer
306 * you allocate in advance.
307 *
308 * `glib/gprintf.h` must be explicitly included in order to use this function.
309 *
310 * Returns: the number of bytes printed.
311 *
312 * Since: 2.4
313 **/
314 gint
g_vasprintf(gchar ** string,gchar const * format,va_list args)315 g_vasprintf (gchar **string,
316 gchar const *format,
317 va_list args)
318 {
319 gint len;
320 g_return_val_if_fail (string != NULL, -1);
321
322 #if !defined(USE_SYSTEM_PRINTF)
323
324 len = _g_gnulib_vasprintf (string, format, args);
325 if (len < 0)
326 *string = NULL;
327
328 #elif defined (HAVE_VASPRINTF)
329
330 len = vasprintf (string, format, args);
331 if (len < 0)
332 *string = NULL;
333
334 #else
335
336 {
337 va_list args2;
338
339 G_VA_COPY (args2, args);
340
341 *string = g_new (gchar, g_printf_string_upper_bound (format, args));
342
343 len = _g_vsprintf (*string, format, args2);
344 va_end (args2);
345 }
346 #endif
347
348 return len;
349 }
350