| blob | 15ed7543914aacae49fc0fcff67180c664d007f1 |
1 '\" t
2 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
3 .\"
4 .\" Earlier versions of this page influenced the present text.
5 .\" It was derived from a Berkeley page with version
6 .\" @(#)printf.3 6.14 (Berkeley) 7/30/91
7 .\" converted for Linux by faith@cs.unc.edu, updated by
8 .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
9 .\"
10 .\" SPDX-License-Identifier: GPL-2.0-or-later
11 .\"
12 .\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99.
13 .\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes
14 .\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes
15 .\"
16 .TH printf 3 (date) "Linux man-pages (unreleased)"
17 .SH NAME
18 printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf,
19 vsprintf, vsnprintf \- formatted output conversion
20 .SH LIBRARY
21 Standard C library
22 .RI ( libc ", " \-lc )
23 .SH SYNOPSIS
24 .nf
25 .B #include <stdio.h>
26 .P
27 .BI "int printf(const char *restrict " format ", ...);"
28 .BI "int fprintf(FILE *restrict " stream ,
29 .BI " const char *restrict " format ", ...);"
30 .BI "int dprintf(int " fd ,
31 .BI " const char *restrict " format ", ...);"
32 .BI "int sprintf(char *restrict " str ,
33 .BI " const char *restrict " format ", ...);"
34 .BI "int snprintf(char " str "[restrict ." size "], size_t " size ,
35 .BI " const char *restrict " format ", ...);"
36 .P
37 .BI "int vprintf(const char *restrict " format ", va_list " ap );
38 .BI "int vfprintf(FILE *restrict " stream ,
39 .BI " const char *restrict " format ", va_list " ap );
40 .BI "int vdprintf(int " fd ,
41 .BI " const char *restrict " format ", va_list " ap );
42 .BI "int vsprintf(char *restrict " str ,
43 .BI " const char *restrict " format ", va_list " ap );
44 .BI "int vsnprintf(char " str "[restrict ." size "], size_t " size ,
45 .BI " const char *restrict " format ", va_list " ap );
46 .fi
47 .P
48 .RS -4
49 Feature Test Macro Requirements for glibc (see
50 .BR feature_test_macros (7)):
51 .RE
52 .P
53 .BR snprintf (),
54 .BR vsnprintf ():
55 .nf
56 _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
57 || /* glibc <= 2.19: */ _BSD_SOURCE
58 .fi
59 .P
60 .BR dprintf (),
61 .BR vdprintf ():
62 .nf
63 Since glibc 2.10:
64 _POSIX_C_SOURCE >= 200809L
65 Before glibc 2.10:
66 _GNU_SOURCE
67 .fi
68 .SH DESCRIPTION
69 The functions in the
70 .BR printf ()
71 family produce output according to a
72 .I format
73 as described below.
74 The functions
75 .BR printf ()
76 and
77 .BR vprintf ()
78 write output to
79 .IR stdout ,
80 the standard output stream;
81 .BR fprintf ()
82 and
83 .BR vfprintf ()
84 write output to the given output
85 .IR stream ;
86 .BR sprintf (),
87 .BR snprintf (),
88 .BR vsprintf (),
89 and
90 .BR vsnprintf ()
91 write to the character string
92 .IR str .
93 .P
94 The function
95 .BR dprintf ()
96 is the same as
97 .BR fprintf ()
98 except that it outputs to a file descriptor,
99 .IR fd ,
100 instead of to a
101 .BR stdio (3)
102 stream.
103 .P
104 The functions
105 .BR snprintf ()
106 and
107 .BR vsnprintf ()
108 write at most
109 .I size
110 bytes (including the terminating null byte (\[aq]\e0\[aq])) to
111 .IR str .
112 .P
113 The functions
114 .BR vprintf (),
115 .BR vfprintf (),
116 .BR vdprintf (),
117 .BR vsprintf (),
118 .BR vsnprintf ()
119 are equivalent to the functions
120 .BR printf (),
121 .BR fprintf (),
122 .BR dprintf (),
123 .BR sprintf (),
124 .BR snprintf (),
125 respectively, except that they are called with a
126 .I va_list
127 instead of a variable number of arguments.
128 These functions do not call the
129 .I va_end
130 macro.
131 Because they invoke the
132 .I va_arg
133 macro, the value of
134 .I ap
135 is undefined after the call.
136 See
137 .BR stdarg (3).
138 .P
139 All of these functions write the output under the control of a
140 .I format
141 string that specifies how subsequent arguments (or arguments accessed via
142 the variable-length argument facilities of
143 .BR stdarg (3))
144 are converted for output.
145 .P
146 C99 and POSIX.1-2001 specify that the results are undefined if a call to
147 .BR sprintf (),
148 .BR snprintf (),
149 .BR vsprintf (),
150 or
151 .BR vsnprintf ()
152 would cause copying to take place between objects that overlap
153 (e.g., if the target string array and one of the supplied input arguments
154 refer to the same buffer).
155 See CAVEATS.
156 .SS Format of the format string
157 The format string is a character string, beginning and ending
158 in its initial shift state, if any.
159 The format string is composed of zero or more directives: ordinary
160 characters (not
161 .BR % ),
162 which are copied unchanged to the output stream;
163 and conversion specifications, each of which results in fetching zero or
164 more subsequent arguments.
165 Each conversion specification is introduced by
166 the character
167 .BR % ,
168 and ends with a
169 .IR "conversion specifier" .
170 In between there may be (in this order) zero or more
171 .IR flags ,
172 an optional minimum
173 .IR "field width" ,
174 an optional
175 .I precision
176 and an optional
177 .IR "length modifier" .
178 .P
179 The overall syntax of a conversion specification is:
180 .P
181 .in +4n
182 .nf
183 %[$][flags][width][.precision][length modifier]conversion
184 .fi
185 .in
186 .P
187 The arguments must correspond properly (after type promotion) with the
188 conversion specifier.
189 By default, the arguments are used in the order
190 given, where each \[aq]*\[aq] (see
191 .I "Field width"
192 and
193 .I Precision
194 below) and each conversion specifier asks for the next
195 argument (and it is an error if insufficiently many arguments are given).
196 One can also specify explicitly which argument is taken,
197 at each place where an argument is required, by writing "%m$" instead
198 of \[aq]%\[aq] and "*m$" instead of \[aq]*\[aq],
199 where the decimal integer \fIm\fP denotes
200 the position in the argument list of the desired argument, indexed starting
201 from 1.
202 Thus,
203 .P
204 .in +4n
205 .EX
206 printf("%*d", width, num);
207 .EE
208 .in
209 .P
210 and
211 .P
212 .in +4n
213 .EX
214 printf("%2$*1$d", width, num);
215 .EE
216 .in
217 .P
218 are equivalent.
219 The second style allows repeated references to the
220 same argument.
221 The C99 standard does not include the style using \[aq]$\[aq],
222 which comes from the Single UNIX Specification.
223 If the style using
224 \[aq]$\[aq] is used, it must be used throughout for all conversions taking an
225 argument and all width and precision arguments, but it may be mixed
226 with "%%" formats, which do not consume an argument.
227 There may be no
228 gaps in the numbers of arguments specified using \[aq]$\[aq]; for example, if
229 arguments 1 and 3 are specified, argument 2 must also be specified
230 somewhere in the format string.
231 .P
232 For some numeric conversions a radix character ("decimal point") or
233 thousands' grouping character is used.
234 The actual character used
235 depends on the
236 .B LC_NUMERIC
237 part of the locale.
238 (See
239 .BR setlocale (3).)
240 The POSIX locale
241 uses \[aq].\[aq] as radix character, and does not have a grouping character.
242 Thus,
243 .P
244 .in +4n
245 .EX
246 printf("%\[aq].2f", 1234567.89);
247 .EE
248 .in
249 .P
250 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
251 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
252 .SS Flag characters
253 The character % is followed by zero or more of the following flags:
254 .TP
255 .B #
256 The value should be converted to an "alternate form".
257 For
258 .B o
259 conversions, the first character of the output string is made zero
260 (by prefixing a 0 if it was not zero already).
261 For
262 .B x
263 and
264 .B X
265 conversions, a nonzero result has the string "0x" (or "0X" for
266 .B X
267 conversions) prepended to it.
268 For
269 .BR a ,
270 .BR A ,
271 .BR e ,
272 .BR E ,
273 .BR f ,
274 .BR F ,
275 .BR g ,
276 and
277 .B G
278 conversions, the result will always contain a decimal point, even if no
279 digits follow it (normally, a decimal point appears in the results of those
280 conversions only if a digit follows).
281 For
282 .B g
283 and
284 .B G
285 conversions, trailing zeros are not removed from the result as they would
286 otherwise be.
287 For
288 .BR m ,
289 if
290 .I errno
291 contains a valid error code,
292 the output of
293 .I strerrorname_np(errno)
294 is printed;
295 otherwise, the value stored in
296 .I errno
297 is printed as a decimal number.
298 For other conversions, the result is undefined.
299 .TP
300 .B \&0
301 The value should be zero padded.
302 For
303 .BR d ,
304 .BR i ,
305 .BR o ,
306 .BR u ,
307 .BR x ,
308 .BR X ,
309 .BR a ,
310 .BR A ,
311 .BR e ,
312 .BR E ,
313 .BR f ,
314 .BR F ,
315 .BR g ,
316 and
317 .B G
318 conversions, the converted value is padded on the left with zeros rather
319 than blanks.
320 If the
321 .B \&0
322 and
323 .B \-
324 flags both appear, the
325 .B \&0
326 flag is ignored.
327 If a precision is given with an integer conversion
328 .RB ( d ,
329 .BR i ,
330 .BR o ,
331 .BR u ,
332 .BR x ,
333 and
334 .BR X ),
335 the
336 .B \&0
337 flag is ignored.
338 For other conversions, the behavior is undefined.
339 .TP
340 .B \-
341 The converted value is to be left adjusted on the field boundary.
342 (The default is right justification.)
343 The converted value is padded on the right with blanks, rather
344 than on the left with blanks or zeros.
345 A
346 .B \-
347 overrides a
348 .B \&0
349 if both are given.
350 .TP
351 .B \[aq] \[aq]
352 (a space) A blank should be left before a positive number
353 (or empty string) produced by a signed conversion.
354 .TP
355 .B +
356 A sign (+ or \-) should always be placed before a number produced by a signed
357 conversion.
358 By default, a sign is used only for negative numbers.
359 A
360 .B +
361 overrides a space if both are used.
362 .P
363 The five flag characters above are defined in the C99 standard.
364 The Single UNIX Specification specifies one further flag character.
365 .TP
366 .B \[aq]
367 For decimal conversion
368 .RB ( i ,
369 .BR d ,
370 .BR u ,
371 .BR f ,
372 .BR F ,
373 .BR g ,
374 .BR G )
375 the output is to be grouped with thousands' grouping characters
376 if the locale information indicates any.
377 (See
378 .BR setlocale (3).)
379 Note that many versions of
380 .BR gcc (1)
381 cannot parse this option and will issue a warning.
382 (SUSv2 did not
383 include \fI%\[aq]F\fP, but SUSv3 added it.)
384 Note also that the default locale of a C program is "C"
385 whose locale information indicates no thousands' grouping character.
386 Therefore, without a prior call to
387 .BR setlocale (3),
388 no thousands' grouping characters will be printed.
389 .P
390 glibc 2.2 adds one further flag character.
391 .TP
392 .B I
393 For decimal integer conversion
394 .RB ( i ,
395 .BR d ,
396 .BR u )
397 the output uses the locale's alternative output digits, if any.
398 For example, since glibc 2.2.3 this will give Arabic-Indic digits
399 in the Persian ("fa_IR") locale.
400 .\" outdigits keyword in locale file
401 .SS Field width
402 An optional decimal digit string (with nonzero first digit) specifying
403 a minimum field width.
404 If the converted value has fewer characters
405 than the field width, it will be padded with spaces on the left
406 (or right, if the left-adjustment flag has been given).
407 Instead of a decimal digit string one may write "*" or "*m$"
408 (for some decimal integer \fIm\fP) to specify that the field width
409 is given in the next argument, or in the \fIm\fP-th argument, respectively,
410 which must be of type
411 .IR int .
412 A negative field width is taken as a \[aq]\-\[aq] flag followed by a
413 positive field width.
414 In no case does a nonexistent or small field width cause truncation of a
415 field; if the result of a conversion is wider than the field width, the
416 field is expanded to contain the conversion result.
417 .SS Precision
418 An optional precision, in the form of a period (\[aq].\[aq]) followed by an
419 optional decimal digit string.
420 Instead of a decimal digit string one may write "*" or "*m$"
421 (for some decimal integer \fIm\fP) to specify that the precision
422 is given in the next argument, or in the \fIm\fP-th argument, respectively,
423 which must be of type
424 .IR int .
425 If the precision is given as just \[aq].\[aq], the precision is taken to
426 be zero.
427 A negative precision is taken as if the precision were omitted.
428 This gives the minimum number of digits to appear for
429 .BR d ,
430 .BR i ,
431 .BR o ,
432 .BR u ,
433 .BR x ,
434 and
435 .B X
436 conversions, the number of digits to appear after the radix character for
437 .BR a ,
438 .BR A ,
439 .BR e ,
440 .BR E ,
441 .BR f ,
442 and
443 .B F
444 conversions, the maximum number of significant digits for
445 .B g
446 and
447 .B G
448 conversions, or the maximum number of characters to be printed from a
449 string for
450 .B s
451 and
452 .B S
453 conversions.
454 .SS Length modifier
455 Here, "integer conversion" stands for
456 .BR d ,
457 .BR i ,
458 .BR o ,
459 .BR u ,
460 .BR x ,
461 or
462 .B X
463 conversion.
464 .TP
465 .B hh
466 A following integer conversion corresponds to a
467 .I signed char
468 or
469 .I unsigned char
470 argument, or a following
471 .B n
472 conversion corresponds to a pointer to a
473 .I signed char
474 argument.
475 .TP
476 .B h
477 A following integer conversion corresponds to a
478 .I short
479 or
480 .I unsigned short
481 argument, or a following
482 .B n
483 conversion corresponds to a pointer to a
484 .I short
485 argument.
486 .TP
487 .B l
488 (ell) A following integer conversion corresponds to a
489 .I long
490 or
491 .I unsigned long
492 argument, or a following
493 .B n
494 conversion corresponds to a pointer to a
495 .I long
496 argument, or a following
497 .B c
498 conversion corresponds to a
499 .I wint_t
500 argument, or a following
501 .B s
502 conversion corresponds to a pointer to
503 .I wchar_t
504 argument.
505 On a following
506 .BR a ,
507 .BR A ,
508 .BR e ,
509 .BR E ,
510 .BR f ,
511 .BR F ,
512 .BR g ,
513 or
514 .B G
515 conversion, this length modifier is ignored (C99; not in SUSv2).
516 .TP
517 .B ll
518 (ell-ell).
519 A following integer conversion corresponds to a
520 .I long long
521 or
522 .I unsigned long long
523 argument, or a following
524 .B n
525 conversion corresponds to a pointer to a
526 .I long long
527 argument.
528 .TP
529 .B q
530 A synonym for
531 .BR ll .
532 This is a nonstandard extension, derived from BSD;
533 avoid its use in new code.
534 .TP
535 .B L
536 A following
537 .BR a ,
538 .BR A ,
539 .BR e ,
540 .BR E ,
541 .BR f ,
542 .BR F ,
543 .BR g ,
544 or
545 .B G
546 conversion corresponds to a
547 .I long double
548 argument.
549 (C99 allows %LF, but SUSv2 does not.)
550 .TP
551 .B j
552 A following integer conversion corresponds to an
553 .I intmax_t
554 or
555 .I uintmax_t
556 argument, or a following
557 .B n
558 conversion corresponds to a pointer to an
559 .I intmax_t
560 argument.
561 .TP
562 .B z
563 A following integer conversion corresponds to a
564 .I size_t
565 or
566 .I ssize_t
567 argument, or a following
568 .B n
569 conversion corresponds to a pointer to a
570 .I size_t
571 argument.
572 .TP
573 .B Z
574 A nonstandard synonym for
575 .B z
576 that predates the appearance of
577 .BR z .
578 Do not use in new code.
579 .TP
580 .B t
581 A following integer conversion corresponds to a
582 .I ptrdiff_t
583 argument, or a following
584 .B n
585 conversion corresponds to a pointer to a
586 .I ptrdiff_t
587 argument.
588 .P
589 SUSv3 specifies all of the above,
590 except for those modifiers explicitly noted as being nonstandard extensions.
591 SUSv2 specified only the length modifiers
592 .B h
593 (in
594 .BR hd ,
595 .BR hi ,
596 .BR ho ,
597 .BR hx ,
598 .BR hX ,
599 .BR hn )
600 and
601 .B l
602 (in
603 .BR ld ,
604 .BR li ,
605 .BR lo ,
606 .BR lx ,
607 .BR lX ,
608 .BR ln ,
609 .BR lc ,
610 .BR ls )
611 and
612 .B L
613 (in
614 .BR Le ,
615 .BR LE ,
616 .BR Lf ,
617 .BR Lg ,
618 .BR LG ).
619 .P
620 As a nonstandard extension, the GNU implementations treats
621 .B ll
622 and
623 .B L
624 as synonyms, so that one can, for example, write
625 .B llg
626 (as a synonym for the standards-compliant
627 .BR Lg )
628 and
629 .B Ld
630 (as a synonym for the standards compliant
631 .BR lld ).
632 Such usage is nonportable.
633 .\"
634 .SS Conversion specifiers
635 A character that specifies the type of conversion to be applied.
636 The conversion specifiers and their meanings are:
637 .TP
638 .BR d ", " i
639 The
640 .I int
641 argument is converted to signed decimal notation.
642 The precision, if any, gives the minimum number of digits
643 that must appear; if the converted value requires fewer digits, it is
644 padded on the left with zeros.
645 The default precision is 1.
646 When 0 is printed with an explicit precision 0, the output is empty.
647 .TP
648 .BR o ", " u ", " x ", " X
649 The
650 .I "unsigned int"
651 argument is converted to unsigned octal
652 .RB ( o ),
653 unsigned decimal
654 .RB ( u ),
655 or unsigned hexadecimal
656 .RB ( x
657 and
658 .BR X )
659 notation.
660 The letters
661 .B abcdef
662 are used for
663 .B x
664 conversions; the letters
665 .B ABCDEF
666 are used for
667 .B X
668 conversions.
669 The precision, if any, gives the minimum number of digits
670 that must appear; if the converted value requires fewer digits, it is
671 padded on the left with zeros.
672 The default precision is 1.
673 When 0 is printed with an explicit precision 0, the output is empty.
674 .TP
675 .BR e ", " E
676 The
677 .I double
678 argument is rounded and converted in the style
679 .RB [\-]d \&. ddd e \(+-dd
680 where there is one digit (which is nonzero if the argument is nonzero)
681 before the decimal-point character and the number
682 of digits after it is equal to the precision; if the precision is missing,
683 it is taken as 6; if the precision is zero, no decimal-point character
684 appears.
685 An
686 .B E
687 conversion uses the letter
688 .B E
689 (rather than
690 .BR e )
691 to introduce the exponent.
692 The exponent always contains at least two
693 digits; if the value is zero, the exponent is 00.
694 .TP
695 .BR f ", " F
696 The
697 .I double
698 argument is rounded and converted to decimal notation in the style
699 .RB [\-]ddd \&. ddd,
700 where the number of digits after the decimal-point character is equal to
701 the precision specification.
702 If the precision is missing, it is taken as
703 6; if the precision is explicitly zero, no decimal-point character appears.
704 If a decimal point appears, at least one digit appears before it.
705 .IP
706 (SUSv2 does not know about
707 .B F
708 and says that character string representations for infinity and NaN
709 may be made available.
710 SUSv3 adds a specification for
711 .BR F .
712 The C99 standard specifies "[\-]inf" or "[\-]infinity"
713 for infinity, and a string starting with "nan" for NaN, in the case of
714 .B f
715 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of
716 .B F
717 conversion.)
718 .TP
719 .BR g ", " G
720 The
721 .I double
722 argument is converted in style
723 .B f
724 or
725 .B e
726 (or
727 .B F
728 or
729 .B E
730 for
731 .B G
732 conversions).
733 The precision specifies the number of significant digits.
734 If the precision is missing, 6 digits are given; if the precision is zero,
735 it is treated as 1.
736 Style
737 .B e
738 is used if the exponent from its conversion is less than \-4 or greater
739 than or equal to the precision.
740 Trailing zeros are removed from the
741 fractional part of the result; a decimal point appears only if it is
742 followed by at least one digit.
743 .TP
744 .BR a ", " A
745 (C99; not in SUSv2, but added in SUSv3)
746 For
747 .B a
748 conversion, the
749 .I double
750 argument is converted to hexadecimal notation (using the letters abcdef)
751 in the style
752 .RB [\-] 0x h \&. hhhh p \(+-d;
753 for
754 .B A
755 conversion the prefix
756 .BR 0X ,
757 the letters ABCDEF, and the exponent separator
758 .B P
759 is used.
760 There is one hexadecimal digit before the decimal point,
761 and the number of digits after it is equal to the precision.
762 The default precision suffices for an exact representation of the value
763 if an exact representation in base 2 exists
764 and otherwise is sufficiently large to distinguish values of type
765 .IR double .
766 The digit before the decimal point is unspecified for nonnormalized
767 numbers, and nonzero but otherwise unspecified for normalized numbers.
768 The exponent always contains at least one
769 digit; if the value is zero, the exponent is 0.
770 .TP
771 .B c
772 If no
773 .B l
774 modifier is present, the
775 .I int
776 argument is converted to an
777 .IR "unsigned char" ,
778 and the resulting character is written.
779 If an
780 .B l
781 modifier is present, the
782 .I wint_t
783 (wide character) argument is converted to a multibyte sequence by a call
784 to the
785 .BR wcrtomb (3)
786 function, with a conversion state starting in the initial state, and the
787 resulting multibyte string is written.
788 .TP
789 .B s
790 If no
791 .B l
792 modifier is present: the
793 .I "const char\ *"
794 argument is expected to be a pointer to an array of character type (pointer
795 to a string).
796 Characters from the array are written up to (but not
797 including) a terminating null byte (\[aq]\e0\[aq]);
798 if a precision is specified, no more than the number specified
799 are written.
800 If a precision is given, no null byte need be present;
801 if the precision is not specified, or is greater than the size of the
802 array, the array must contain a terminating null byte.
803 .IP
804 If an
805 .B l
806 modifier is present: the
807 .I "const wchar_t\ *"
808 argument is expected to be a pointer to an array of wide characters.
809 Wide characters from the array are converted to multibyte characters
810 (each by a call to the
811 .BR wcrtomb (3)
812 function, with a conversion state starting in the initial state before
813 the first wide character), up to and including a terminating null
814 wide character.
815 The resulting multibyte characters are written up to
816 (but not including) the terminating null byte.
817 If a precision is
818 specified, no more bytes than the number specified are written, but
819 no partial multibyte characters are written.
820 Note that the precision
821 determines the number of
822 .I bytes
823 written, not the number of
824 .I wide characters
825 or
826 .IR "screen positions" .
827 The array must contain a terminating null wide character, unless a
828 precision is given and it is so small that the number of bytes written
829 exceeds it before the end of the array is reached.
830 .TP
831 .B C
832 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
833 Synonym for
834 .BR lc .
835 Don't use.
836 .TP
837 .B S
838 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
839 Synonym for
840 .BR ls .
841 Don't use.
842 .TP
843 .B p
844 The
845 .I "void\ *"
846 pointer argument is printed in hexadecimal (as if by
847 .B %#x
848 or
849 .BR %#lx ).
850 .TP
851 .B n
852 The number of characters written so far is stored into the integer
853 pointed to by the corresponding argument.
854 That argument shall be an
855 .IR "int\ *" ,
856 or variant whose size matches the (optionally)
857 supplied integer length modifier.
858 No argument is converted.
859 (This specifier is not supported by the bionic C library.)
860 The behavior is undefined if the conversion specification includes
861 any flags, a field width, or a precision.
862 .TP
863 .B m
864 (glibc extension; supported by uClibc and musl.)
865 Print output of
866 .I strerror(errno)
867 (or
868 .I strerrorname_np(errno)
869 in the alternate form).
870 No argument is required.
871 .TP
872 .B %
873 A \[aq]%\[aq] is written.
874 No argument is converted.
875 The complete conversion
876 specification is \[aq]%%\[aq].
877 .SH RETURN VALUE
878 Upon successful return, these functions return the number of bytes
879 printed (excluding the null byte used to end output to strings).
880 .P
881 The functions
882 .BR snprintf ()
883 and
884 .BR vsnprintf ()
885 do not write more than
886 .I size
887 bytes (including the terminating null byte (\[aq]\e0\[aq])).
888 If the output was truncated due to this limit, then the return value
889 is the number of characters (excluding the terminating null byte)
890 which would have been written to the final string if enough space
891 had been available.
892 Thus, a return value of
893 .I size
894 or more means that the output was truncated.
895 (See also below under CAVEATS.)
896 .P
897 If an output error is encountered, a negative value is returned.
898 .SH ATTRIBUTES
899 For an explanation of the terms used in this section, see
900 .BR attributes (7).
901 .TS
902 allbox;
903 lbx lb lb
904 l l l.
905 Interface Attribute Value
906 T{
907 .na
908 .nh
909 .BR printf (),
910 .BR fprintf (),
911 .BR sprintf (),
912 .BR snprintf (),
913 .BR vprintf (),
914 .BR vfprintf (),
915 .BR vsprintf (),
916 .BR vsnprintf ()
917 T} Thread safety MT-Safe locale
918 .TE
919 .SH STANDARDS
920 .TP
921 .BR fprintf ()
922 .TQ
923 .BR printf ()
924 .TQ
925 .BR sprintf ()
926 .TQ
927 .BR vprintf ()
928 .TQ
929 .BR vfprintf ()
930 .TQ
931 .BR vsprintf ()
932 .TQ
933 .BR snprintf ()
934 .TQ
935 .BR vsnprintf ()
936 C11, POSIX.1-2008.
937 .TP
938 .BR dprintf ()
939 .TQ
940 .BR vdprintf ()
941 GNU, POSIX.1-2008.
942 .SH HISTORY
943 .TP
944 .BR fprintf ()
945 .TQ
946 .BR printf ()
947 .TQ
948 .BR sprintf ()
949 .TQ
950 .BR vprintf ()
951 .TQ
952 .BR vfprintf ()
953 .TQ
954 .BR vsprintf ()
955 C89, POSIX.1-2001.
956 .TP
957 .BR snprintf ()
958 .TQ
959 .BR vsnprintf ()
960 SUSv2, C99, POSIX.1-2001.
961 .IP
962 Concerning the return value of
963 .BR snprintf (),
964 SUSv2 and C99 contradict each other: when
965 .BR snprintf ()
966 is called with
967 .IR size =0
968 then SUSv2 stipulates an unspecified return value less than 1,
969 while C99 allows
970 .I str
971 to be NULL in this case, and gives the return value (as always)
972 as the number of characters that would have been written in case
973 the output string has been large enough.
974 POSIX.1-2001 and later align their specification of
975 .BR snprintf ()
976 with C99.
977 .TP
978 .BR dprintf ()
979 .TQ
980 .BR vdprintf ()
981 GNU, POSIX.1-2008.
982 .P
983 .\" Linux libc4 knows about the five C standard flags.
984 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
985 .\" and the conversions
986 .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
987 .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
988 .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
989 .\" where \fBF\fP is a synonym for \fBf\fP.
990 .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
991 .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
992 .\" (This is bad, and caused serious bugs later, when
993 .\" support for \fB%D\fP disappeared.)
994 .\" No locale-dependent radix character,
995 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
996 .\" .P
997 .\" Linux libc5 knows about the five C standard flags and the \[aq] flag,
998 .\" locale, "%m$" and "*m$".
999 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
1000 .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
1001 .\" both for \fIlong double\fP and for \fIlong long\fP (this is a bug).
1002 .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
1003 .\" but adds the conversion character
1004 .\" .BR m ,
1005 .\" which outputs
1006 .\" .IR strerror(errno) .
1007 .\" .P
1008 .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
1009 .\" .P
1010 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
1011 and conversion characters \fBa\fP and \fBA\fP.
1012 .P
1013 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
1014 and the flag character \fBI\fP.
1015 .P
1016 glibc 2.35 gives a meaning to the alternate form
1017 .RB ( # )
1018 of the
1019 .B m
1020 conversion specifier, that is
1021 .IR %#m .
1022 .SH CAVEATS
1023 Some programs imprudently rely on code such as the following
1024 .P
1025 .in +4n
1026 .EX
1027 sprintf(buf, "%s some further text", buf);
1028 .EE
1029 .in
1030 .P
1031 to append text to
1032 .IR buf .
1033 However, the standards explicitly note that the results are undefined
1034 if source and destination buffers overlap when calling
1035 .BR sprintf (),
1036 .BR snprintf (),
1037 .BR vsprintf (),
1038 and
1039 .BR vsnprintf ().
1040 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
1041 Depending on the version of
1042 .BR gcc (1)
1043 used, and the compiler options employed, calls such as the above will
1044 .B not
1045 produce the expected results.
1046 .P
1047 The glibc implementation of the functions
1048 .BR snprintf ()
1049 and
1050 .BR vsnprintf ()
1051 conforms to the C99 standard, that is, behaves as described above,
1052 since glibc 2.1.
1053 Until glibc 2.0.6, they would return \-1
1054 when the output was truncated.
1055 .\" .SH HISTORY
1056 .\" UNIX V7 defines the three routines
1057 .\" .BR printf (),
1058 .\" .BR fprintf (),
1059 .\" .BR sprintf (),
1060 .\" and has the flag \-, the width or precision *, the length modifier l,
1061 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
1062 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
1063 .\" #, + and <space> and no longer mentions D,O,U,X.
1064 .\" 2.11BSD has
1065 .\" .BR vprintf (),
1066 .\" .BR vfprintf (),
1067 .\" .BR vsprintf (),
1068 .\" and warns not to use D,O,U,X.
1069 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
1070 .\" and the conversions n, p, E, G, X (with current meaning)
1071 .\" and deprecates D,O,U.
1072 .\" 4.4BSD introduces the functions
1073 .\" .BR snprintf ()
1074 .\" and
1075 .\" .BR vsnprintf (),
1076 .\" and the length modifier q.
1077 .\" FreeBSD also has functions
1078 .\" .BR asprintf ()
1079 .\" and
1080 .\" .BR vasprintf (),
1081 .\" that allocate a buffer large enough for
1082 .\" .BR sprintf ().
1083 .\" In glibc there are functions
1084 .\" .BR dprintf ()
1085 .\" and
1086 .\" .BR vdprintf ()
1087 .\" that print to a file descriptor instead of a stream.
1088 .SH BUGS
1089 Because
1090 .BR sprintf ()
1091 and
1092 .BR vsprintf ()
1093 assume an arbitrarily long string, callers must be careful not to overflow
1094 the actual space; this is often impossible to assure.
1095 Note that the length
1096 of the strings produced is locale-dependent and difficult to predict.
1097 Use
1098 .BR snprintf ()
1099 and
1100 .BR vsnprintf ()
1101 instead (or
1102 .BR asprintf (3)
1103 and
1104 .BR vasprintf (3)).
1105 .\" .P
1106 .\" Linux libc4.[45] does not have a
1107 .\" .BR snprintf (),
1108 .\" but provides a libbsd that contains an
1109 .\" .BR snprintf ()
1110 .\" equivalent to
1111 .\" .BR sprintf (),
1112 .\" that is, one that ignores the
1113 .\" .I size
1114 .\" argument.
1115 .\" Thus, the use of
1116 .\" .BR snprintf ()
1117 .\" with early libc4 leads to serious security problems.
1118 .P
1119 Code such as
1120 .BI printf( foo );
1121 often indicates a bug, since
1122 .I foo
1123 may contain a % character.
1124 If
1125 .I foo
1126 comes from untrusted user input, it may contain \fB%n\fP, causing the
1127 .BR printf ()
1128 call to write to memory and creating a security hole.
1129 .\" .P
1130 .\" Some floating-point conversions under early libc4
1131 .\" caused memory leaks.
1132 .SH EXAMPLES
1133 To print
1134 .I Pi
1135 to five decimal places:
1136 .P
1137 .in +4n
1138 .EX
1139 #include <math.h>
1140 #include <stdio.h>
1141 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
1142 .EE
1143 .in
1144 .P
1145 To print a date and time in the form "Sunday, July 3, 10:02",
1146 where
1147 .I weekday
1148 and
1149 .I month
1150 are pointers to strings:
1151 .P
1152 .in +4n
1153 .EX
1154 #include <stdio.h>
1155 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
1156 weekday, month, day, hour, min);
1157 .EE
1158 .in
1159 .P
1160 Many countries use the day-month-year order.
1161 Hence, an internationalized version must be able to print
1162 the arguments in an order specified by the format:
1163 .P
1164 .in +4n
1165 .EX
1166 #include <stdio.h>
1167 fprintf(stdout, format,
1168 weekday, month, day, hour, min);
1169 .EE
1170 .in
1171 .P
1172 where
1173 .I format
1174 depends on locale, and may permute the arguments.
1175 With the value:
1176 .P
1177 .in +4n
1178 .EX
1179 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
1180 .EE
1181 .in
1182 .P
1183 one might obtain "Sonntag, 3. Juli, 10:02".
1184 .P
1185 To allocate a sufficiently large string and print into it
1186 (code correct for both glibc 2.0 and glibc 2.1):
1187 .P
1188 .EX
1189 #include <stdio.h>
1190 #include <stdlib.h>
1191 #include <stdarg.h>
1192 \&
1193 char *
1194 make_message(const char *fmt, ...)
1195 {
1196 int n = 0;
1197 size_t size = 0;
1198 char *p = NULL;
1199 va_list ap;
1200 \&
1201 /* Determine required size. */
1202 \&
1203 va_start(ap, fmt);
1204 n = vsnprintf(p, size, fmt, ap);
1205 va_end(ap);
1206 \&
1207 if (n < 0)
1208 return NULL;
1209 \&
1210 size = (size_t) n + 1; /* One extra byte for \[aq]\e0\[aq] */
1211 p = malloc(size);
1212 if (p == NULL)
1213 return NULL;
1214 \&
1215 va_start(ap, fmt);
1216 n = vsnprintf(p, size, fmt, ap);
1217 va_end(ap);
1218 \&
1219 if (n < 0) {
1220 free(p);
1221 return NULL;
1222 }
1223 \&
1224 return p;
1225 }
1226 .EE
1227 .P
1228 If truncation occurs in glibc versions prior to glibc 2.0.6,
1229 this is treated as an error instead of being handled gracefully.
1230 .SH SEE ALSO
1231 .BR printf (1),
1232 .BR asprintf (3),
1233 .BR puts (3),
1234 .BR scanf (3),
1235 .BR setlocale (3),
1236 .BR strfromd (3),
1237 .BR wcrtomb (3),
1238 .BR wprintf (3),
1239 .BR locale (5)