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