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.
24 #define _GNU_SOURCE /* For vasprintf */
32 #include "gprintfint.h"
36 * @format: a standard printf() format string, but notice
37 * <link linkend="string-precision">string precision pitfalls</link>.
38 * @Varargs: the arguments to insert in the output.
40 * An implementation of the standard printf() function which supports
41 * positional parameters, as specified in the Single Unix Specification.
43 * Returns: the number of characters 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 * @Varargs: 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 characters printed.
76 g_fprintf (FILE *file,
83 va_start (args, format);
84 retval = g_vfprintf (file, format, args);
92 * @string: the buffer to hold the output.
93 * @format: a standard printf() format string, but notice
94 * <link linkend="string-precision">string precision pitfalls</link>.
95 * @Varargs: the arguments to insert in the output.
97 * An implementation of the standard sprintf() function which supports
98 * positional parameters, as specified in the Single Unix Specification.
100 * Returns: the number of characters printed.
105 g_sprintf (gchar *string,
112 va_start (args, format);
113 retval = g_vsprintf (string, format, args);
121 * @string: the buffer to hold the output.
122 * @n: the maximum number of characters to produce (including the
123 * terminating nul character).
124 * @format: a standard printf() format string, but notice
125 * <link linkend="string-precision">string precision pitfalls</link>.
126 * @Varargs: the arguments to insert in the output.
128 * A safer form of the standard sprintf() function. The output is guaranteed
129 * to not exceed @n characters (including the terminating nul character), so
130 * it is easy to ensure that a buffer overflow cannot occur.
132 * See also g_strdup_printf().
134 * In versions of GLib prior to 1.2.3, this function may return -1 if the
135 * output was truncated, and the truncated string may not be nul-terminated.
136 * In versions prior to 1.3.12, this function returns the length of the output
139 * The return value of g_snprintf() conforms to the snprintf()
140 * function as standardized in ISO C99. Note that this is different from
141 * traditional snprintf(), which returns the length of the output string.
143 * The format string may contain positional parameters, as specified in
144 * the Single Unix Specification.
146 * Returns: the number of characters which would be produced if the buffer
150 g_snprintf (gchar *string,
158 va_start (args, format);
159 retval = g_vsnprintf (string, n, format, args);
167 * @format: a standard printf() format string, but notice
168 * <link linkend="string-precision">string precision pitfalls</link>.
169 * @args: the list of arguments to insert in the output.
171 * An implementation of the standard vprintf() function which supports
172 * positional parameters, as specified in the Single Unix Specification.
174 * Returns: the number of characters printed.
179 g_vprintf (gchar const *format,
182 g_return_val_if_fail (format != NULL, -1);
184 return _g_vprintf (format, args);
189 * @file: the stream to write to.
190 * @format: a standard printf() format string, but notice
191 * <link linkend="string-precision">string precision pitfalls</link>.
192 * @args: the list of arguments to insert in the output.
194 * An implementation of the standard fprintf() function which supports
195 * positional parameters, as specified in the Single Unix Specification.
197 * Returns: the number of characters printed.
202 g_vfprintf (FILE *file,
206 g_return_val_if_fail (format != NULL, -1);
208 return _g_vfprintf (file, format, args);
213 * @string: the buffer to hold the output.
214 * @format: a standard printf() format string, but notice
215 * <link linkend="string-precision">string precision pitfalls</link>.
216 * @args: the list of arguments to insert in the output.
218 * An implementation of the standard vsprintf() function which supports
219 * positional parameters, as specified in the Single Unix Specification.
221 * Returns: the number of characters printed.
226 g_vsprintf (gchar *string,
230 g_return_val_if_fail (string != NULL, -1);
231 g_return_val_if_fail (format != NULL, -1);
233 return _g_vsprintf (string, format, args);
238 * @string: the buffer to hold the output.
239 * @n: the maximum number of characters to produce (including the
240 * terminating nul character).
241 * @format: a standard printf() format string, but notice
242 * <link linkend="string-precision">string precision pitfalls</link>.
243 * @args: the list of arguments to insert in the output.
245 * A safer form of the standard vsprintf() function. The output is guaranteed
246 * to not exceed @n characters (including the terminating nul character), so
247 * it is easy to ensure that a buffer overflow cannot occur.
249 * See also g_strdup_vprintf().
251 * In versions of GLib prior to 1.2.3, this function may return -1 if the
252 * output was truncated, and the truncated string may not be nul-terminated.
253 * In versions prior to 1.3.12, this function returns the length of the output
256 * The return value of g_vsnprintf() conforms to the vsnprintf() function
257 * as standardized in ISO C99. Note that this is different from traditional
258 * vsnprintf(), which returns the length of the output string.
260 * The format string may contain positional parameters, as specified in
261 * the Single Unix Specification.
263 * Returns: the number of characters which would be produced if the buffer
267 g_vsnprintf (gchar *string,
272 g_return_val_if_fail (n == 0 || string != NULL, -1);
273 g_return_val_if_fail (format != NULL, -1);
275 return _g_vsnprintf (string, n, format, args);
280 * @string: the return location for the newly-allocated string.
281 * @format: a standard printf() format string, but notice
282 * <link linkend="string-precision">string precision pitfalls</link>.
283 * @args: the list of arguments to insert in the output.
285 * An implementation of the GNU vasprintf() function which supports
286 * positional parameters, as specified in the Single Unix Specification.
287 * This function is similar to g_vsprintf(), except that it allocates a
288 * string to hold the output, instead of putting the output in a buffer
289 * you allocate in advance.
291 * Returns: the number of characters printed.
296 g_vasprintf (gchar **string,
301 g_return_val_if_fail (string != NULL, -1);
304 len = _g_vasprintf (string, format, args);
307 else if (!g_mem_is_system_malloc ())
309 gchar *string1 = g_strndup (*string, len);
317 G_VA_COPY (args2, args);
319 *string = g_new (gchar, g_printf_string_upper_bound (format, args));
321 len = _g_vsprintf (*string, format, args2);