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