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