1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997, 2002 Peter Mattis, Red Hat, Inc.
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 of the License, or (at your option) any later version.
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.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
27 #include "gprintfint.h"
32 * @format: a standard printf() format string, but notice
33 * <link linkend="string-precision">string precision pitfalls</link>.
34 * @...: the arguments to insert in the output.
36 * An implementation of the standard printf() function which supports
37 * positional parameters, as specified in the Single Unix Specification.
39 * As with the standard printf(), this does not automatically append a trailing
40 * new-line character to the message, so typically @format should end with its
41 * own new-line character.
43 * Returns: the number of bytes printed.
48 g_printf (gchar
const *format
,
54 va_start (args
, format
);
55 retval
= g_vprintf (format
, args
);
63 * @file: the stream to write to.
64 * @format: a standard printf() format string, but notice
65 * <link linkend="string-precision">string precision pitfalls</link>.
66 * @...: the arguments to insert in the output.
68 * An implementation of the standard fprintf() function which supports
69 * positional parameters, as specified in the Single Unix Specification.
71 * Returns: the number of bytes printed.
76 g_fprintf (FILE *file
,
83 va_start (args
, format
);
84 retval
= g_vfprintf (file
, format
, args
);
92 * @string: A pointer to a memory buffer to contain the resulting string. It
93 * is up to the caller to ensure that the allocated buffer is large
94 * enough to hold the formatted result
95 * @format: a standard printf() format string, but notice
96 * <link linkend="string-precision">string precision pitfalls</link>.
97 * @...: the arguments to insert in the output.
99 * An implementation of the standard sprintf() function which supports
100 * positional parameters, as specified in the Single Unix Specification.
102 * Note that it is usually better to use g_snprintf(), to avoid the
103 * risk of buffer overflow.
105 * See also g_strdup_printf().
107 * Returns: the number of bytes printed.
112 g_sprintf (gchar
*string
,
119 va_start (args
, format
);
120 retval
= g_vsprintf (string
, format
, args
);
128 * @string: the buffer to hold the output.
129 * @n: the maximum number of bytes to produce (including the
130 * terminating nul character).
131 * @format: a standard printf() format string, but notice
132 * <link linkend="string-precision">string precision pitfalls</link>.
133 * @...: the arguments to insert in the output.
135 * A safer form of the standard sprintf() function. The output is guaranteed
136 * to not exceed @n characters (including the terminating nul character), so
137 * it is easy to ensure that a buffer overflow cannot occur.
139 * See also g_strdup_printf().
141 * In versions of GLib prior to 1.2.3, this function may return -1 if the
142 * output was truncated, and the truncated string may not be nul-terminated.
143 * In versions prior to 1.3.12, this function returns the length of the output
146 * The return value of g_snprintf() conforms to the snprintf()
147 * function as standardized in ISO C99. Note that this is different from
148 * traditional snprintf(), which returns the length of the output string.
150 * The format string may contain positional parameters, as specified in
151 * the Single Unix Specification.
153 * Returns: the number of bytes which would be produced if the buffer
157 g_snprintf (gchar
*string
,
165 va_start (args
, format
);
166 retval
= g_vsnprintf (string
, n
, format
, args
);
174 * @format: a standard printf() format string, but notice
175 * <link linkend="string-precision">string precision pitfalls</link>.
176 * @args: the list of arguments to insert in the output.
178 * An implementation of the standard vprintf() function which supports
179 * positional parameters, as specified in the Single Unix Specification.
181 * Returns: the number of bytes printed.
186 g_vprintf (gchar
const *format
,
189 g_return_val_if_fail (format
!= NULL
, -1);
191 return _g_vprintf (format
, args
);
196 * @file: the stream to write to.
197 * @format: a standard printf() format string, but notice
198 * <link linkend="string-precision">string precision pitfalls</link>.
199 * @args: the list of arguments to insert in the output.
201 * An implementation of the standard fprintf() function which supports
202 * positional parameters, as specified in the Single Unix Specification.
204 * Returns: the number of bytes printed.
209 g_vfprintf (FILE *file
,
213 g_return_val_if_fail (format
!= NULL
, -1);
215 return _g_vfprintf (file
, format
, args
);
220 * @string: the buffer to hold the output.
221 * @format: a standard printf() format string, but notice
222 * <link linkend="string-precision">string precision pitfalls</link>.
223 * @args: the list of arguments to insert in the output.
225 * An implementation of the standard vsprintf() function which supports
226 * positional parameters, as specified in the Single Unix Specification.
228 * Returns: the number of bytes printed.
233 g_vsprintf (gchar
*string
,
237 g_return_val_if_fail (string
!= NULL
, -1);
238 g_return_val_if_fail (format
!= NULL
, -1);
240 return _g_vsprintf (string
, format
, args
);
245 * @string: the buffer to hold the output.
246 * @n: the maximum number of bytes to produce (including the
247 * terminating nul character).
248 * @format: a standard printf() format string, but notice
249 * <link linkend="string-precision">string precision pitfalls</link>.
250 * @args: the list of arguments to insert in the output.
252 * A safer form of the standard vsprintf() function. The output is guaranteed
253 * to not exceed @n characters (including the terminating nul character), so
254 * it is easy to ensure that a buffer overflow cannot occur.
256 * See also g_strdup_vprintf().
258 * In versions of GLib prior to 1.2.3, this function may return -1 if the
259 * output was truncated, and the truncated string may not be nul-terminated.
260 * In versions prior to 1.3.12, this function returns the length of the output
263 * The return value of g_vsnprintf() conforms to the vsnprintf() function
264 * as standardized in ISO C99. Note that this is different from traditional
265 * vsnprintf(), which returns the length of the output string.
267 * The format string may contain positional parameters, as specified in
268 * the Single Unix Specification.
270 * Returns: the number of bytes which would be produced if the buffer
274 g_vsnprintf (gchar
*string
,
279 g_return_val_if_fail (n
== 0 || string
!= NULL
, -1);
280 g_return_val_if_fail (format
!= NULL
, -1);
282 return _g_vsnprintf (string
, n
, format
, args
);
287 * @string: the return location for the newly-allocated string.
288 * @format: a standard printf() format string, but notice
289 * <link linkend="string-precision">string precision pitfalls</link>.
290 * @args: the list of arguments to insert in the output.
292 * An implementation of the GNU vasprintf() function which supports
293 * positional parameters, as specified in the Single Unix Specification.
294 * This function is similar to g_vsprintf(), except that it allocates a
295 * string to hold the output, instead of putting the output in a buffer
296 * you allocate in advance.
298 * Returns: the number of bytes printed.
303 g_vasprintf (gchar
**string
,
308 g_return_val_if_fail (string
!= NULL
, -1);
310 #if !defined(HAVE_GOOD_PRINTF)
312 len
= _g_gnulib_vasprintf (string
, format
, args
);
316 #elif defined (HAVE_VASPRINTF)
318 len
= vasprintf (string
, format
, args
);
321 else if (!g_mem_is_system_malloc ())
323 /* vasprintf returns malloc-allocated memory */
324 gchar
*string1
= g_strndup (*string
, len
);
334 G_VA_COPY (args2
, args
);
336 *string
= g_new (gchar
, g_printf_string_upper_bound (format
, args
));
338 len
= _g_vsprintf (*string
, format
, args2
);