Branch data Line data Source code
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 : 12 : g_printf (gchar const *format,
52 : : ...)
53 : : {
54 : : va_list args;
55 : : gint retval;
56 : :
57 : 12 : va_start (args, format);
58 : 12 : retval = g_vprintf (format, args);
59 : 12 : va_end (args);
60 : :
61 : 12 : 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 : 80816 : g_fprintf (FILE *file,
82 : : gchar const *format,
83 : : ...)
84 : : {
85 : : va_list args;
86 : : gint retval;
87 : :
88 : 80816 : va_start (args, format);
89 : 80816 : retval = g_vfprintf (file, format, args);
90 : 80816 : va_end (args);
91 : :
92 : 80816 : 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 [func@GLib.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 [func@GLib.strdup_printf].
113 : : *
114 : : * Returns: the number of bytes printed
115 : : *
116 : : * Since: 2.2
117 : : **/
118 : : gint
119 : 3 : g_sprintf (gchar *string,
120 : : gchar const *format,
121 : : ...)
122 : : {
123 : : va_list args;
124 : : gint retval;
125 : :
126 : 3 : va_start (args, format);
127 : 3 : retval = g_vsprintf (string, format, args);
128 : 3 : va_end (args);
129 : :
130 : 3 : 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 [func@GLib.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 : 2583 : g_snprintf (gchar *string,
165 : : gulong n,
166 : : gchar const *format,
167 : : ...)
168 : : {
169 : : va_list args;
170 : : gint retval;
171 : :
172 : 2583 : va_start (args, format);
173 : 2583 : retval = g_vsnprintf (string, n, format, args);
174 : 2583 : va_end (args);
175 : :
176 : 2583 : 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 : 12 : g_vprintf (gchar const *format,
196 : : va_list args)
197 : : {
198 : 12 : g_return_val_if_fail (format != NULL, -1);
199 : :
200 : 12 : 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 : 80816 : g_vfprintf (FILE *file,
221 : : gchar const *format,
222 : : va_list args)
223 : : {
224 : 80816 : g_return_val_if_fail (format != NULL, -1);
225 : :
226 : 80816 : 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 : 3 : g_vsprintf (gchar *string,
247 : : gchar const *format,
248 : : va_list args)
249 : : {
250 : 3 : g_return_val_if_fail (string != NULL, -1);
251 : 3 : g_return_val_if_fail (format != NULL, -1);
252 : :
253 : 3 : 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 [func@GLib.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 : 2583 : g_vsnprintf (gchar *string,
288 : : gulong n,
289 : : gchar const *format,
290 : : va_list args)
291 : : {
292 : 2583 : g_return_val_if_fail (n == 0 || string != NULL, -1);
293 : 2583 : g_return_val_if_fail (format != NULL, -1);
294 : :
295 : 2583 : return _g_vsnprintf (string, n, format, args);
296 : : }
297 : :
298 : : /**
299 : : * g_vasprintf:
300 : : * @string: (out) (not optional) (nullable): the return location for the
301 : : * newly-allocated string, which will be `NULL` if (and only if)
302 : : * this function fails
303 : : * @format: (not nullable): a standard `printf()` format string, but notice
304 : : * [string precision pitfalls](string-utils.html#string-precision-pitfalls)
305 : : * @args: the list of arguments to insert in the output
306 : : *
307 : : * An implementation of the GNU `vasprintf()` function which supports
308 : : * positional parameters, as specified in the Single Unix Specification.
309 : : * This function is similar to [func@GLib.vsprintf], except that it allocates a
310 : : * string to hold the output, instead of putting the output in a buffer
311 : : * you allocate in advance.
312 : : *
313 : : * The returned value in @string is guaranteed to be non-`NULL`, unless
314 : : * @format contains `%lc` or `%ls` conversions, which can fail if no
315 : : * multibyte representation is available for the given character.
316 : : *
317 : : * `glib/gprintf.h` must be explicitly included in order to use this function.
318 : : *
319 : : * Returns: the number of bytes printed, or -1 on failure
320 : : *
321 : : * Since: 2.4
322 : : **/
323 : : gint
324 : 1499480 : g_vasprintf (gchar **string,
325 : : gchar const *format,
326 : : va_list args)
327 : : {
328 : : gint len;
329 : 1499480 : g_return_val_if_fail (string != NULL, -1);
330 : :
331 : : #if !defined(USE_SYSTEM_PRINTF)
332 : :
333 : : len = _g_gnulib_vasprintf (string, format, args);
334 : : if (len < 0)
335 : : *string = NULL;
336 : :
337 : : #elif defined (HAVE_VASPRINTF)
338 : :
339 : : {
340 : : int saved_errno;
341 : 1499480 : len = vasprintf (string, format, args);
342 : 1499480 : saved_errno = errno;
343 [ + + ]: 1499480 : if (len < 0)
344 : : {
345 [ - + ]: 3 : if (saved_errno == ENOMEM)
346 : : {
347 : : /* Try and print a message to be a bit helpful, but stick to the
348 : : * bare minimum to avoid any code path which could try and fail to
349 : : * allocate additional memory. */
350 : 0 : fputs (G_STRLOC, stderr);
351 : 0 : fputs (": failed to allocate memory\n", stderr);
352 : 0 : g_abort ();
353 : : }
354 : : else
355 : 3 : *string = NULL;
356 : : }
357 : : }
358 : :
359 : : #else
360 : :
361 : : {
362 : : va_list args2;
363 : : char c;
364 : : int max_len;
365 : :
366 : : va_copy (args2, args);
367 : :
368 : : max_len = _g_vsnprintf (&c, 1, format, args);
369 : : if (max_len < 0)
370 : : {
371 : : /* This can happen if @format contains `%ls` or `%lc` and @args contains
372 : : * something not representable in the current locale’s encoding (which
373 : : * should be UTF-8, but ymmv). Basically: don’t use `%ls` or `%lc`. */
374 : : va_end (args2);
375 : : *string = NULL;
376 : : return -1;
377 : : }
378 : :
379 : : *string = g_new (gchar, (size_t) max_len + 1);
380 : :
381 : : len = _g_vsprintf (*string, format, args2);
382 : : va_end (args2);
383 : :
384 : : /* _g_vsprintf() should have exactly the same failure modes as _g_vsnprintf() */
385 : : g_assert (len >= 0);
386 : : }
387 : : #endif
388 : :
389 : 1499480 : return len;
390 : : }
|
