Penguin
Recent Changes
Blame: vsnprintf(3)
EditPageHistoryDiffInfoLikePages
Annotated edit history of vsnprintf(3) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 PRINTF
2 !!!PRINTF
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 EXAMPLES
7 SEE ALSO
8 CONFORMING TO
9 HISTORY
10 BUGS
11 ----
12 !!NAME
13
14
15 printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - formatted output conversion
16 !!SYNOPSIS
17
18
19 __#include __
20
21
2 JosephLunderville 22 __int printf(const char *__''format''__, ...);__
23
24 __int fprintf(FILE *__''stream''__, const char *__''format''__, ...);__
25
26 __int sprintf(char *__''str''__, const char *__''format''__, ...);__
27
28 __int snprintf(char *__''str''__, size_t__ ''size''__, const char *__''format''__, ...);__
29
30 __int asprintf(char **__''strp''__, const char *__''format''__, ...);__
31
32 __int dprintf(int __''d''__, const char *__''format''__, ...);__
1 perry 33
34
35 __#include __
36
37
2 JosephLunderville 38 __int vprintf(const char *__''format''__, va_list __''ap''__);__
39
40 __int vfprintf(FILE *__''stream''__, const char *__''format''__, va_list __''ap''__);__
41
42 __int vsprintf(char *__''str''__, const char *__''format''__, va_list __''ap''__);__
43
44 __int vsnprintf(char *__''str''__, size_t__ ''size''__, const char *__''format''__, va_list __''ap''__);__
45
46 __int vasprintf(char **__''strp''__, const char *__''format''__, va_list __''ap''__);__
47
48 __int vdprintf(int __''d''__, const char *__''format''__, va_list __''ap''__);__
49
1 perry 50 !!DESCRIPTION
51
52
53 The functions in the __printf__ family produce output
54 according to a ''format'' as described below. The
55 functions __printf__ and __vprintf__ write output to
56 ''stdout'', the standard output stream; __fprintf__
57 and __vfprintf__ write output to the given output
58 ''stream''; __sprintf__, __snprintf__,
59 __vsprintf__ and __vsnprintf__ write to the character
60 string ''str''.
61
62
63 The functions __vprintf__, __vfprintf__,
64 __vsprintf__, __vsnprintf__ are equivalent to the
65 functions __printf__, __fprintf__, __sprintf__,
66 __snprintf__, respectively, except that they are called
67 with a va_list instead of a variable number of arguments.
68 These functions do not call the ''va_end'' macro.
69 Consequently, the value of ''ap'' is undefined after the
70 call. The application should call ''va_end(ap)'' itself
71 afterwards.
72
73
74 These eight functions write the output under the control of
75 a ''format'' string that specifies how subsequent
76 arguments (or arguments accessed via the variable-length
77 argument facilities of stdarg(3)) are converted for
78 output.
79
80
81 __Return value__
82
83
84 These functions return the number of characters printed (not
85 including the trailing `0' used to end output to strings).
86 __snprintf__ and __vsnprintf__ do not write more than
87 ''size'' bytes (including the trailing '0'), and return
88 -1 if the output was truncated due to this limit. (Thus
89 until glibc 2.0.6. Since glibc 2.1 these functions follow
90 the C99 standard and return the number of characters
91 (excluding the trailing '0') which would have been written
92 to the final string if enough space had been
93 available.)
94
95
96 __Format of the format string__
97
98
99 The format string is a character string, beginning and
100 ending in its initial shift state, if any. The format string
101 is composed of zero or more directives: ordinary characters
102 (not __%__), which are copied unchanged to the output
103 stream; and conversion specifications, each of which results
104 in fetching zero or more subsequent arguments. Each
105 conversion specification is introduced by the character
106 __%__, and ends with a ''conversion specifier''. In
107 between there may be (in this order) zero or more
108 ''flags'', an optional minimum ''field width'', an
109 optional ''precision'' and an optional ''length
110 modifier''.
111
112
113 The arguments must correspond properly (after type
114 promotion) with the conversion specifier. By default, the
115 arguments are used in the order given, where each `*' and
116 each conversion specifier asks for the next argument (and it
117 is an error if insufficiently many arguments are given). One
118 can also specify explicitly which argument is taken, at each
119 place where an argument is required, by writing `%m$'
120 instead of `%' and `*m$' instead of `*', where the decimal
121 integer m denotes the position in the argument list of the
122 desired argument, indexed starting from 1.
123 Thus,
124
125
126 printf(
127
128
129 and
130
131
132 printf(
133
134
135 are equivalent. The second style allows repeated references
136 to the same argument. The C99 standard does not include the
137 style using `$', which comes from the Single Unix
138 Specification. If the style using `$' is used, it must be
139 used throughout for all conversions taking an argument and
140 all width and precision arguments, but it may be mixed with
141 `%%' formats which do not consume an argument. There may be
142 no gaps in the numbers of arguments specified using `$'; for
143 example, if arguments 1 and 3 are specified, argument 2 must
144 also be specified somewhere in the format
145 string.
146
147
148 For some numeric conversions a radix character (`decimal
149 point') or thousands' grouping character is used. The actual
150 character used depends on the LC_NUMERIC part of the locale.
151 The POSIX locale uses `.' as radix character, and does not
152 have a grouping character. Thus,
153
154
155 printf(
156
157
158 results in `1234567.89' in the POSIX locale, in `1234567,89'
159 in the nl_NL locale, and in `1.234.567,89' in the da_DK
160 locale.
161
162
163 __The flag characters__
164
165
166 The character % is followed by zero or more of the following
167 flags:
168
169
170 __#__
171
172
173 The value should be converted to an ``alternate form''. For
174 __o__ conversions, the first character of the output
175 string is made zero (by prefixing a 0 if it was not zero
176 already). For __x__ and __X__ conversions, a non-zero
177 result has the string `0x' (or `0X' for __X__
178 conversions) prepended to it. For __a__, __A__,
179 __e__, __E__, __f__, __F__, __g__, and
180 __G__ conversions, the result will always contain a
181 decimal point, even if no digits follow it (normally, a
182 decimal point appears in the results of those conversions
183 only if a digit follows). For __g__ and __G__
184 conversions, trailing zeros are not removed from the result
185 as they would otherwise be. For other conversions, the
186 result is undefined.
187
188
189 __0__
190
191
192 The value should be zero padded. For __d__, __i__,
193 __o__, __u__, __x__, __X__, __a__, __A__,
194 __e__, __E__, __f__, __F__, __g__, and
195 __G__ conversions, the converted value is padded on the
196 left with zeros rather than blanks. If the __0__ and
197 __-__ flags both appear, the __0__ flag is ignored. If
198 a precision is given with a numeric conversion (__d__,
199 __i__, __o__, __u__, __x__, and __X__), the
200 __0__ flag is ignored. For other conversions, the
201 behavior is undefined.
202
203
204 __-__
205
206
207 The converted value is to be left adjusted on the field
208 boundary. (The default is right justification.) Except for
209 __n__ conversions, the converted value is padded on the
210 right with blanks, rather than on the left with blanks or
211 zeros. A __-__ overrides a __0__ if both are
212 given.
213
214
215 __' '__
216
217
218 (a space) A blank should be left before a positive number
219 (or empty string) produced by a signed
220 conversion.
221
222
223 __+__
224
225
226 A sign (+ or -) always be placed before a number produced by
227 a signed conversion. By default a sign is used only for
228 negative numbers. A __+__ overrides a space if both are
229 used.
230
231
232 The five flag characters above are defined in the C
233 standard. The SUSv2 specifies one further flag
234 character.
235
236
237 __'__
238
239
240 For decimal conversion (__i__, __d__, __u__,
241 __f__, __F__, __g__, __G__) the output is to be
242 grouped with thousands' grouping characters if the locale
243 information indicates any. Note that many versions of
244 __gcc__ cannot parse this option and will issue a
245 warning. SUSv2 does not include %'F.
246
247
248 glibc 2.2 adds one further flag character.
249
250
251 __I__
252
253
254 For decimal integer conversion (__i__, __d__,
255 __u__) the output uses the locale's alternative output
256 digits, if any (for example, Arabic digits). However, it
257 does not include any locale definitions with such
258 __outdigits__ defined.
259
260
261 __The field width__
262
263
264 An optional decimal digit string (with nonzero first digit)
265 specifying a minimum field width. If the converted value has
266 fewer characters than the field width, it will be padded
267 with spaces on the left (or right, if the left-adjustment
268 flag has been given). Instead of a decimal digit string one
269 may write `*' or `*m$' (for some decimal integer m) to
270 specify that the field width is given in the next argument,
271 or in the m-th argument, respectively, which must be of type
272 ''int''. A negative field width is taken as a `-' flag
273 followed by a positive field width. In no case does a
274 non-existent or small field width cause truncation of a
275 field; if the result of a conversion is wider than the field
276 width, the field is expanded to contain the conversion
277 result.
278
279
280 __The precision__
281
282
283 An optional precision, in the form of a period (`.')
284 followed by an optional decimal digit string. Instead of a
285 decimal digit string one may write `*' or `*m$' (for some
286 decimal integer m) to specify that the precision is given in
287 the next argument, or in the m-th argument, respectively,
288 which must be of type ''int''. If the precision is given
289 as just `.', or the precision is negative, the precision is
290 taken to be zero. This gives the minimum number of digits to
291 appear for __d__, __i__, __o__, __u__, __x__,
292 and __X__ conversions, the number of digits to appear
293 after the radix character for __a__, __A__, __e__,
294 __E__, __f__, and __F__ conversions, the maximum
295 number of significant digits for __g__ and __G__
296 conversions, or the maximum number of characters to be
297 printed from a string for __s__ and __S__
298 conversions.
299
300
301 __The length modifier__
302
303
304 Here, `integer conversion' stands for __d__, __i__,
305 __o__, __u__, __x__, or __X__
306 conversion.
307
308
309 __hh__
310
311
312 A following integer conversion corresponds to a ''signed
313 char'' or ''unsigned char'' argument, or a following
314 __n__ conversion corresponds to a pointer to a ''signed
315 char'' argument.
316
317
318 __h__
319
320
321 A following integer conversion corresponds to a ''short
322 int'' or ''unsigned short int'' argument, or a
323 following __n__ conversion corresponds to a pointer to a
324 ''short int'' argument.
325
326
327 __l__
328
329
330 (ell) A following integer conversion corresponds to a
331 ''long int'' or ''unsigned long int'' argument, or a
332 following __n__ conversion corresponds to a pointer to a
333 ''long int'' argument, or a following __c__ conversion
334 corresponds to a ''wint_t'' argument, or a following
335 __s__ conversion corresponds to a pointer to
336 ''wchar_t'' argument.
337
338
339 __ll__
340
341
342 (ell-ell). A following integer conversion corresponds to a
343 ''long long int'' or ''unsigned long long int''
344 argument, or a following __n__ conversion corresponds to
345 a pointer to a ''long long int'' argument.
346
347
348 __L__
349
350
351 A following __a__, __A__, __e__, __E__,
352 __f__, __F__, __g__, or __G__ conversion
353 corresponds to a ''long double'' argument. (C99 allows
354 %LF, but SUSv2 does not.)
355
356
357 __q__
358
359
360 (`quad'. BSD 4.4 and Linux libc5 only. Don't use.) This is a
361 synonym for __ll__.
362
363
364 __j__
365
366
367 A following integer conversion corresponds to an
368 ''intmax_t'' or ''uintmax_t'' argument.
369
370
371 __z__
372
373
374 A following integer conversion corresponds to a
375 ''size_t'' or ''ssize_t'' argument. (Linux libc5 has
376 __Z__ with this meaning. Don't use it.)
377
378
379 __t__
380
381
382 A following integer conversion corresponds to a
383 ''ptrdiff_t'' argument.
384
385
386 The SUSv2 only knows about the length modifiers __h__ (in
387 __hd__, __hi__, __ho__, __hx__, __hX__,
388 __hn__) and __l__ (in __ld__, __li__, __lo__,
389 __lx__, __lX__, __ln__, __lc__, __ls__) and
390 __L__ (in __Le__, __LE__, __Lf__, __Lg__,
391 __LG__).
392
393
394 __The conversion specifier__
395
396
397 A character that specifies the type of conversion to be
398 applied. The conversion specifiers and their meanings
399 are:
400
401
402 __d__,__i__
403
404
405 The ''int'' argument is converted to signed decimal
406 notation. The precision, if any, gives the minimum number of
407 digits that must appear; if the converted value requires
408 fewer digits, it is padded on the left with zeros. The
409 default precision is 1. When 0 is printed with an explicit
410 precision 0, the output is empty.
411
412
413 __o__,__u__,__x__,__X__
414
415
416 The ''unsigned int'' argument is converted to unsigned
417 octal (__o__), unsigned decimal (__u__), or unsigned
418 hexadecimal (__x__ and __X__) notation. The letters
419 __abcdef__ are used for __x__ conversions; the letters
420 __ABCDEF__ are used for __X__ conversions. The
421 precision, if any, gives the minimum number of digits that
422 must appear; if the converted value requires fewer digits,
423 it is padded on the left with zeros. The default precision
424 is 1. When 0 is printed with an explicit precision 0, the
425 output is empty.
426
427
428 __e__,__E__
429
430
431 The ''double'' argument is rounded and converted in the
432 style [[-]d__.__ddd__e__
433 __E__ conversion uses
434 the letter __E__ (rather than __e__) to introduce the
435 exponent. The exponent always contains at least two digits;
436 if the value is zero, the exponent is 00.
437
438
439 __f__,__F__
440
441
442 The ''double'' argument is rounded and converted to
443 decimal notation in the style [[-]ddd__.__ddd, where the
444 number of digits after the decimal-point character is equal
445 to the precision specification. If the precision is missing,
446 it is taken as 6; if the precision is explicitly zero, no
447 decimal-point character appears. If a decimal point appears,
448 at least one digit appears before it.
449
450
451 (The SUSv2 does not know about __F__ and says that
452 character string representations for infinity and NaN may be
453 made available. The C99 standard specifies `[[-]inf' or
454 `[[-]infinity' for infinity, and a string starting with `nan'
455 for NaN, in the case of __f__ conversion, and `[[-]INF' or
456 `[[-]INFINITY' or `NAN*' in the case of __F__
457 conversion.)
458
459
460 __g__,__G__
461
462
463 The ''double'' argument is converted in style __f__ or
464 __e__ (or __F__ or __E__ for __G__ conversions).
465 The precision specifies the number of significant digits. If
466 the precision is missing, 6 digits are given; if the
467 precision is zero, it is treated as 1. Style __e__ is
468 used if the exponent from its conversion is less than -4 or
469 greater than or equal to the precision. Trailing zeros are
470 removed from the fractional part of the result; a decimal
471 point appears only if it is followed by at least one
472 digit.
473
474
475 __a__,__A__
476
477
478 (C99; not in SUSv2) For __a__ conversion, the
479 ''double'' argument is converted to hexadecimal notation
480 (using the letters abcdef) in the style
481 [[-]__0x__h__.__hhhh__p____A__
482 conversion the prefix __0X__, the letters ABCDEF, and the
483 exponent separator __P__ is used. There is one
484 hexadecimal digit before the decimal point, and the number
485 of digits after it is equal to the precision. The default
486 precision suffices for an exact representation of the value
487 if an exact representation in base 2 exists and otherwise is
488 sufficiently large to distinguish values of type
489 ''double''. The digit before the decimal point is
490 unspecified for non-normalized numbers, and nonzero but
491 otherwise unspecified for normalized numbers.
492
493
494 __c__
495
496
497 If no __l__ modifier is present, the ''int'' argument
498 is converted to an ''unsigned char'', and the resulting
499 character is written. If an __l__ modifier is present,
500 the ''wint_t'' (wide character) argument is converted to
501 a multibyte sequence by a call to the __wcrtomb__
502 function, with a conversion state starting in the initial
503 state, and the resulting multibyte string is
504 written.
505
506
507 __s__
508
509
510 If no __l__ modifier is present: The ''const char *''
511 argument is expected to be a pointer to an array of
512 character type (pointer to a string). Characters from the
513 array are written up to (but not including) a terminating
514 __NUL__ character; if a precision is specified, no more
515 than the number specified are written. If a precision is
516 given, no null character need be present; if the precision
517 is not specified, or is greater than the size of the array,
518 the array must contain a terminating __NUL__
519 character.
520
521
522 If an __l__ modifier is present: The ''const wchar_t
523 *'' argument is expected to be a pointer to an array of
524 wide characters. Wide characters from the array are
525 converted to multibyte characters (each by a call to the
526 __wcrtomb__ function, with a conversion state starting in
527 the initial state before the first wide character), up to
528 and including a terminating null wide character. The
529 resulting multibyte characters are written up to (but not
530 including) the terminating null byte. If a precision is
531 specified, no more bytes than the number specified are
532 written, but no partial multibyte characters are written.
533 Note that the precision determines the number of
534 ''bytes'' written, not the number of ''wide
535 characters'' or ''screen positions''. The array must
536 contain a terminating null wide character, unless a
537 precision is given and it is so small that the number of
538 bytes written exceeds it before the end of the array is
539 reached.
540
541
542 __C__
543
544
545 (Not in C99, but in SUSv2.) Synonym for __lc__. Don't
546 use.
547
548
549 __S__
550
551
552 (Not in C99, but in SUSv2.) Synonym for __ls__. Don't
553 use.
554
555
556 __p__
557
558
559 The ''void *'' pointer argument is printed in hexadecimal
560 (as if by __%#x__ or __%#lx__).
561
562
563 __n__
564
565
566 The number of characters written so far is stored into the
567 integer indicated by the ''int *'' (or variant) pointer
568 argument. No argument is converted.
569
570
571 __%__
572
573
574 A `%' is written. No argument is converted. The complete
575 conversion specification is `%%'.
576 !!EXAMPLES
577
578
579 To print pi to five decimal places:
580
581
582 #include
583
584
585 To print a date and time in the form `Sunday, July 3,
586 10:02', where ''weekday'' and ''month'' are pointers
587 to strings:
588
589
590 #include
591
592
593 Many countries use the day-month-year order. Hence, an
594 internationalized version must be able to print the
595 arguments in an order specified by the format:
596
597
598 #include
599
600
601 where ''format'' depends on locale, and may permute the
602 arguments. With the value
603
604
605
606
607 one might obtain `Sonntag, 3. Juli, 10:02'.
608
609
610 To allocate a sufficiently large string and print into it
611 (code correct for both glibc 2.0 and glibc
612 2.1):
613
614
615 #include
616 !!SEE ALSO
617
618
619 printf(1), wcrtomb(3), wprintf(3),
620 scanf(3), locale(5)
621 !!CONFORMING TO
622
623
624 The __fprintf__, __printf__, __sprintf__,
625 __vprintf__, __vfprintf__, and __vsprintf__
626 functions conform to ANSI X3.159-1989 (``ANSI C'') and
627 ISO/IEC 9899:1999 (``ISO C99''). The __snprintf__ and
628 __vsnprintf__ functions conform to ISO/IEC
629 9899:1999.
630
631
632 Concerning the return value of __snprintf__, the SUSv2
633 and the C99 standard contradict each other: when
634 __snprintf__ is called with ''size''=0 then SUSv2
635 stipulates an unspecified return value less than 1, while
636 C99 allows ''str'' to be NULL in this case, and gives the
637 return value (as always) as the number of characters that
638 would have been written in case the output string has been
639 large enough.
640
641
642 Linux libc5 knows about the five C standard flags and the '
643 flag, locale, %m$ and *m$. It knows about the length
644 modifiers h,l,L,Z,q, but accepts L and q both for long
645 doubles and for long long integers (this is a bug). It no
646 longer recognizes FDOU, but adds a new conversion character
647 __m__, which outputs ''strerror(errno)''.
648
649
650 glibc 2.0 adds conversion characters C and S.
651
652
653 glibc 2.1 adds length modifiers hh,j,t,z and conversion
654 characters a,A.
655
656
657 glibc 2.2 adds the conversion character F with C99
658 semantics, and the flag character I.
659 !!HISTORY
660
661
662 Unix V7 defines the three routines __printf__,
663 __fprintf__, __sprintf__, and has the flag -, the
664 width or precision *, the length modifier l, and the
665 conversions doxfegcsu, and also D,O,U,X as synonyms for
666 ld,lo,lu,lx. This is still true for BSD 2.9.1, but BSD 2.10
667 has the flags #, + and
668 __vprintf__, __vfprintf__,
669 __vsprintf__, and warns not to use D,O,U,X. BSD 4.3 Reno
670 has the flag 0, the length modifiers h and L, and the
671 conversions n, p, E, G, X (with current meaning) and
672 deprecates D,O,U. BSD 4.4 introduces the functions
673 __snprintf__ and __vsnprintf__, and the length
674 modifier q. FreeBSD also has functions ''asprintf'' and
675 ''vasprintf'', that allocate a buffer large enough for
676 __sprintf__.
677 !!BUGS
678
679
680 Because __sprintf__ and __vsprintf__ assume an
681 arbitrarily long string, callers must be careful not to
682 overflow the actual space; this is often impossible to
683 assure. Note that the length of the strings produced is
684 locale-dependent and difficult to predict. Use
685 __snprintf__ and __vsnprintf__ instead (or
686 __asprintf__ and __vasprintf__).
687
688
689 Code such as __printf(__''foo''__);__ often
690 indicates a bug, since ''foo'' may contain a % character.
691 If ''foo'' comes from untrusted user input, it may
692 contain %n, causing the __printf__ call to write to
693 memory and creating a security hole.
694 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.