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.
23 #define _GNU_SOURCE /* For vasprintf */
32 #include "gprintfint.h"
37 * @format: a standard printf() format string, but notice
38 * <link linkend="string-precision">string precision pitfalls</link>.
39 * @Varargs: the arguments to insert in the output.
41 * An implementation of the standard printf() function which supports
42 * positional parameters, as specified in the Single Unix Specification.
44 * Returns: the number of bytes printed.
49 g_printf (gchar const *format,
55 va_start (args, format);
56 retval = g_vprintf (format, args);
64 * @file: the stream to write to.
65 * @format: a standard printf() format string, but notice
66 * <link linkend="string-precision">string precision pitfalls</link>.
67 * @Varargs: the arguments to insert in the output.
69 * An implementation of the standard fprintf() function which supports
70 * positional parameters, as specified in the Single Unix Specification.
72 * Returns: the number of bytes printed.
77 g_fprintf (FILE *file,
84 va_start (args, format);
85 retval = g_vfprintf (file, format, args);
93 * @string: A pointer to a memory buffer to contain the resulting string. It
94 * is up to the caller to ensure that the allocated buffer is large
95 * enough to hold the formatted result
96 * @format: a standard printf() format string, but notice
97 * <link linkend="string-precision">string precision pitfalls</link>.
98 * @Varargs: the arguments to insert in the output.
100 * An implementation of the standard sprintf() function which supports
101 * positional parameters, as specified in the Single Unix Specification.
103 * Note that it is usually better to use g_snprintf(), to avoid the
104 * risk of buffer overflow.
106 * See also g_strdup_printf().
108 * Returns: the number of bytes printed.
113 g_sprintf (gchar *string,
120 va_start (args, format);
121 retval = g_vsprintf (string, format, args);
129 * @string: the buffer to hold the output.
130 * @n: the maximum number of bytes to produce (including the
131 * terminating nul character).
132 * @format: a standard printf() format string, but notice
133 * <link linkend="string-precision">string precision pitfalls</link>.
134 * @Varargs: the arguments to insert in the output.
136 * A safer form of the standard sprintf() function. The output is guaranteed
137 * to not exceed @n characters (including the terminating nul character), so
138 * it is easy to ensure that a buffer overflow cannot occur.
140 * See also g_strdup_printf().
142 * In versions of GLib prior to 1.2.3, this function may return -1 if the
143 * output was truncated, and the truncated string may not be nul-terminated.
144 * In versions prior to 1.3.12, this function returns the length of the output
147 * The return value of g_snprintf() conforms to the snprintf()
148 * function as standardized in ISO C99. Note that this is different from
149 * traditional snprintf(), which returns the length of the output string.
151 * The format string may contain positional parameters, as specified in
152 * the Single Unix Specification.
154 * Returns: the number of bytes which would be produced if the buffer
158 g_snprintf (gchar *string,
166 va_start (args, format);
167 retval = g_vsnprintf (string, n, format, args);
175 * @format: a standard printf() format string, but notice
176 * <link linkend="string-precision">string precision pitfalls</link>.
177 * @args: the list of arguments to insert in the output.
179 * An implementation of the standard vprintf() function which supports
180 * positional parameters, as specified in the Single Unix Specification.
182 * Returns: the number of bytes printed.
187 g_vprintf (gchar const *format,
190 g_return_val_if_fail (format != NULL, -1);
192 return _g_vprintf (format, args);
197 * @file: the stream to write to.
198 * @format: a standard printf() format string, but notice
199 * <link linkend="string-precision">string precision pitfalls</link>.
200 * @args: the list of arguments to insert in the output.
202 * An implementation of the standard fprintf() function which supports
203 * positional parameters, as specified in the Single Unix Specification.
205 * Returns: the number of bytes printed.
210 g_vfprintf (FILE *file,
214 g_return_val_if_fail (format != NULL, -1);
216 return _g_vfprintf (file, format, args);
221 * @string: the buffer to hold the output.
222 * @format: a standard printf() format string, but notice
223 * <link linkend="string-precision">string precision pitfalls</link>.
224 * @args: the list of arguments to insert in the output.
226 * An implementation of the standard vsprintf() function which supports
227 * positional parameters, as specified in the Single Unix Specification.
229 * Returns: the number of bytes printed.
234 g_vsprintf (gchar *string,
238 g_return_val_if_fail (string != NULL, -1);
239 g_return_val_if_fail (format != NULL, -1);
241 return _g_vsprintf (string, format, args);
246 * @string: the buffer to hold the output.
247 * @n: the maximum number of bytes to produce (including the
248 * terminating nul character).
249 * @format: a standard printf() format string, but notice
250 * <link linkend="string-precision">string precision pitfalls</link>.
251 * @args: the list of arguments to insert in the output.
253 * A safer form of the standard vsprintf() function. The output is guaranteed
254 * to not exceed @n characters (including the terminating nul character), so
255 * it is easy to ensure that a buffer overflow cannot occur.
257 * See also g_strdup_vprintf().
259 * In versions of GLib prior to 1.2.3, this function may return -1 if the
260 * output was truncated, and the truncated string may not be nul-terminated.
261 * In versions prior to 1.3.12, this function returns the length of the output
264 * The return value of g_vsnprintf() conforms to the vsnprintf() function
265 * as standardized in ISO C99. Note that this is different from traditional
266 * vsnprintf(), which returns the length of the output string.
268 * The format string may contain positional parameters, as specified in
269 * the Single Unix Specification.
271 * Returns: the number of bytes which would be produced if the buffer
275 g_vsnprintf (gchar *string,
280 g_return_val_if_fail (n == 0 || string != NULL, -1);
281 g_return_val_if_fail (format != NULL, -1);
283 return _g_vsnprintf (string, n, format, args);
288 * @string: the return location for the newly-allocated string.
289 * @format: a standard printf() format string, but notice
290 * <link linkend="string-precision">string precision pitfalls</link>.
291 * @args: the list of arguments to insert in the output.
293 * An implementation of the GNU vasprintf() function which supports
294 * positional parameters, as specified in the Single Unix Specification.
295 * This function is similar to g_vsprintf(), except that it allocates a
296 * string to hold the output, instead of putting the output in a buffer
297 * you allocate in advance.
299 * Returns: the number of bytes printed.
304 g_vasprintf (gchar **string,
309 g_return_val_if_fail (string != NULL, -1);
311 #if !defined(HAVE_GOOD_PRINTF)
313 len = _g_gnulib_vasprintf (string, format, args);
317 #elif defined (HAVE_VASPRINTF)
319 len = vasprintf (string, format, args);
322 else if (!g_mem_is_system_malloc ())
324 /* vasprintf returns malloc-allocated memory */
325 gchar *string1 = g_strndup (*string, len);
335 G_VA_COPY (args2, args);
337 *string = g_new (gchar, g_printf_string_upper_bound (format, args));
339 len = _g_vsprintf (*string, format, args2);