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