1/* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997, 2002  Peter Mattis, Red Hat, Inc.
3 *
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.
8 *
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.
13 *
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.
18 */
19
20#include "config.h"
21
22#ifndef _WIN32
23#define _GNU_SOURCE		/* For vasprintf */
24#endif
25
26#include <stdarg.h>
27#include <stdlib.h>
28#include <stdio.h>
29
30#include "glib.h"
31#include "gprintf.h"
32#include "gprintfint.h"
33
34#include "galias.h"
35
36/**
37 * g_printf:
38 * @format: a standard printf() format string, but notice
39 *          <link linkend="string-precision">string precision pitfalls</link>.
40 * @Varargs: the arguments to insert in the output.
41 *
42 * An implementation of the standard printf() function which supports
43 * positional parameters, as specified in the Single Unix Specification.
44 *
45 * Returns: the number of bytes printed.
46 *
47 * Since: 2.2
48 **/
49gint
50g_printf (gchar const *format,
51	  ...)
52{
53  va_list args;
54  gint retval;
55
56  va_start (args, format);
57  retval = g_vprintf (format, args);
58  va_end (args);
59
60  return retval;
61}
62
63/**
64 * g_fprintf:
65 * @file: the stream to write to.
66 * @format: a standard printf() format string, but notice
67 *          <link linkend="string-precision">string precision pitfalls</link>.
68 * @Varargs: the arguments to insert in the output.
69 *
70 * An implementation of the standard fprintf() function which supports
71 * positional parameters, as specified in the Single Unix Specification.
72 *
73 * Returns: the number of bytes printed.
74 *
75 * Since: 2.2
76 **/
77gint
78g_fprintf (FILE        *file,
79           gchar const *format,
80	   ...)
81{
82  va_list args;
83  gint retval;
84
85  va_start (args, format);
86  retval = g_vfprintf (file, format, args);
87  va_end (args);
88
89  return retval;
90}
91
92/**
93 * g_sprintf:
94 * @string: A pointer to a memory buffer to contain the resulting string. It
95 *          is up to the caller to ensure that the allocated buffer is large
96 *          enough to hold the formatted result
97 * @format: a standard printf() format string, but notice
98 *          <link linkend="string-precision">string precision pitfalls</link>.
99 * @Varargs: the arguments to insert in the output.
100 *
101 * An implementation of the standard sprintf() function which supports
102 * positional parameters, as specified in the Single Unix Specification.
103 *
104 * Returns: the number of bytes printed.
105 *
106 * Since: 2.2
107 **/
108gint
109g_sprintf (gchar       *string,
110	   gchar const *format,
111	   ...)
112{
113  va_list args;
114  gint retval;
115
116  va_start (args, format);
117  retval = g_vsprintf (string, format, args);
118  va_end (args);
119
120  return retval;
121}
122
123/**
124 * g_snprintf:
125 * @string: the buffer to hold the output.
126 * @n: the maximum number of bytes to produce (including the
127 *     terminating nul character).
128 * @format: a standard printf() format string, but notice
129 *          <link linkend="string-precision">string precision pitfalls</link>.
130 * @Varargs: the arguments to insert in the output.
131 *
132 * A safer form of the standard sprintf() function. The output is guaranteed
133 * to not exceed @n characters (including the terminating nul character), so
134 * it is easy to ensure that a buffer overflow cannot occur.
135 *
136 * See also g_strdup_printf().
137 *
138 * In versions of GLib prior to 1.2.3, this function may return -1 if the
139 * output was truncated, and the truncated string may not be nul-terminated.
140 * In versions prior to 1.3.12, this function returns the length of the output
141 * string.
142 *
143 * The return value of g_snprintf() conforms to the snprintf()
144 * function as standardized in ISO C99. Note that this is different from
145 * traditional snprintf(), which returns the length of the output string.
146 *
147 * The format string may contain positional parameters, as specified in
148 * the Single Unix Specification.
149 *
150 * Returns: the number of bytes which would be produced if the buffer
151 *     was large enough.
152 **/
153gint
154g_snprintf (gchar	*string,
155	    gulong	 n,
156	    gchar const *format,
157	    ...)
158{
159  va_list args;
160  gint retval;
161
162  va_start (args, format);
163  retval = g_vsnprintf (string, n, format, args);
164  va_end (args);
165
166  return retval;
167}
168
169/**
170 * g_vprintf:
171 * @format: a standard printf() format string, but notice
172 *          <link linkend="string-precision">string precision pitfalls</link>.
173 * @args: the list of arguments to insert in the output.
174 *
175 * An implementation of the standard vprintf() function which supports
176 * positional parameters, as specified in the Single Unix Specification.
177 *
178 * Returns: the number of bytes printed.
179 *
180 * Since: 2.2
181 **/
182gint
183g_vprintf (gchar const *format,
184	   va_list      args)
185{
186  g_return_val_if_fail (format != NULL, -1);
187
188  return _g_vprintf (format, args);
189}
190
191/**
192 * g_vfprintf:
193 * @file: the stream to write to.
194 * @format: a standard printf() format string, but notice
195 *          <link linkend="string-precision">string precision pitfalls</link>.
196 * @args: the list of arguments to insert in the output.
197 *
198 * An implementation of the standard fprintf() function which supports
199 * positional parameters, as specified in the Single Unix Specification.
200 *
201 * Returns: the number of bytes printed.
202 *
203 * Since: 2.2
204 **/
205gint
206g_vfprintf (FILE        *file,
207            gchar const *format,
208	    va_list      args)
209{
210  g_return_val_if_fail (format != NULL, -1);
211
212  return _g_vfprintf (file, format, args);
213}
214
215/**
216 * g_vsprintf:
217 * @string: the buffer to hold the output.
218 * @format: a standard printf() format string, but notice
219 *          <link linkend="string-precision">string precision pitfalls</link>.
220 * @args: the list of arguments to insert in the output.
221 *
222 * An implementation of the standard vsprintf() function which supports
223 * positional parameters, as specified in the Single Unix Specification.
224 *
225 * Returns: the number of bytes printed.
226 *
227 * Since: 2.2
228 **/
229gint
230g_vsprintf (gchar	 *string,
231	    gchar const *format,
232	    va_list      args)
233{
234  g_return_val_if_fail (string != NULL, -1);
235  g_return_val_if_fail (format != NULL, -1);
236
237  return _g_vsprintf (string, format, args);
238}
239
240/**
241 * g_vsnprintf:
242 * @string: the buffer to hold the output.
243 * @n: the maximum number of bytes to produce (including the
244 *     terminating nul character).
245 * @format: a standard printf() format string, but notice
246 *          <link linkend="string-precision">string precision pitfalls</link>.
247 * @args: the list of arguments to insert in the output.
248 *
249 * A safer form of the standard vsprintf() function. The output is guaranteed
250 * to not exceed @n characters (including the terminating nul character), so
251 * it is easy to ensure that a buffer overflow cannot occur.
252 *
253 * See also g_strdup_vprintf().
254 *
255 * In versions of GLib prior to 1.2.3, this function may return -1 if the
256 * output was truncated, and the truncated string may not be nul-terminated.
257 * In versions prior to 1.3.12, this function returns the length of the output
258 * string.
259 *
260 * The return value of g_vsnprintf() conforms to the vsnprintf() function
261 * as standardized in ISO C99. Note that this is different from traditional
262 * vsnprintf(), which returns the length of the output string.
263 *
264 * The format string may contain positional parameters, as specified in
265 * the Single Unix Specification.
266 *
267 * Returns: the number of bytes which would be produced if the buffer
268 *  was large enough.
269 */
270gint
271g_vsnprintf (gchar	 *string,
272	     gulong	  n,
273	     gchar const *format,
274	     va_list      args)
275{
276  g_return_val_if_fail (n == 0 || string != NULL, -1);
277  g_return_val_if_fail (format != NULL, -1);
278
279  return _g_vsnprintf (string, n, format, args);
280}
281
282/**
283 * g_vasprintf:
284 * @string: the return location for the newly-allocated string.
285 * @format: a standard printf() format string, but notice
286 *          <link linkend="string-precision">string precision pitfalls</link>.
287 * @args: the list of arguments to insert in the output.
288 *
289 * An implementation of the GNU vasprintf() function which supports
290 * positional parameters, as specified in the Single Unix Specification.
291 * This function is similar to g_vsprintf(), except that it allocates a
292 * string to hold the output, instead of putting the output in a buffer
293 * you allocate in advance.
294 *
295 * Returns: the number of bytes printed.
296 *
297 * Since: 2.4
298 **/
299gint
300g_vasprintf (gchar      **string,
301	     gchar const *format,
302	     va_list      args)
303{
304  gint len;
305  g_return_val_if_fail (string != NULL, -1);
306
307#if !defined(HAVE_GOOD_PRINTF)
308
309  len = _g_gnulib_vasprintf (string, format, args);
310  if (len < 0)
311    *string = NULL;
312
313#elif defined (HAVE_VASPRINTF)
314
315  len = vasprintf (string, format, args);
316  if (len < 0)
317    *string = NULL;
318  else if (!g_mem_is_system_malloc ())
319    {
320      /* vasprintf returns malloc-allocated memory */
321      gchar *string1 = g_strndup (*string, len);
322      free (*string);
323      *string = string1;
324    }
325
326#else
327
328  {
329    va_list args2;
330
331    G_VA_COPY (args2, args);
332
333    *string = g_new (gchar, g_printf_string_upper_bound (format, args));
334
335    len = _g_vsprintf (*string, format, args2);
336    va_end (args2);
337  }
338#endif
339
340  return len;
341}
342
343#define __G_PRINTF_C__
344#include "galiasdef.c"
345