Debian Codegraph @

upstream/fedora-44/man3/printf.3

raw
1 '\" t
2 .\" Copyright (c) 1999 Andries Brouwer ([email protected])
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 [email protected], updated by
8 .\" [email protected], [email protected] 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 [email protected] - three small fixes
14 .\" 2000-10-16 [email protected] - more fixes
15 .\"
16 .TH printf 3 2024-11-17 "Linux man-pages 6.13"
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]\[rs]0\[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 %[argument$][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 POSIX 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 as a
377 .I non-monetary
378 quantity.
379 Misleadingly, this isn't necessarily every thousand:
380 for example Karbi ("mjw_IN"), groups its digits into 3 once, then 2 repeatedly.
381 Compare
382 .BR locale (7)
383 .I grouping
384 and
385 .IR thousands_sep ,
386 contrast with
387 .IR mon_grouping / mon_thousands_sep
388 and
389 .BR strfmon (3).
390 This is a no-op in the default "C" locale.
391 .P
392 glibc 2.2 adds one further flag character.
393 .TP
394 .B I
395 For decimal integer conversion
396 .RB ( i ,
397 .BR d ,
398 .BR u )
399 the output uses the locale's alternative output digits, if any.
400 For example, since glibc 2.2.3 this will give Arabic-Indic digits
401 in the Persian ("fa_IR") locale.
402 .\" outdigits keyword in locale file
403 .SS Field width
404 An optional decimal digit string (with nonzero first digit) specifying
405 a minimum field width.
406 If the converted value has fewer characters
407 than the field width, it will be padded with spaces on the left
408 (or right, if the left-adjustment flag has been given).
409 Instead of a decimal digit string one may write "*" or "*m$"
410 (for some decimal integer \fIm\fP) to specify that the field width
411 is given in the next argument, or in the \fIm\fP-th argument, respectively,
412 which must be of type
413 .IR int .
414 A negative field width is taken as a \[aq]\-\[aq] flag followed by a
415 positive field width.
416 In no case does a nonexistent or small field width cause truncation of a
417 field; if the result of a conversion is wider than the field width, the
418 field is expanded to contain the conversion result.
419 .SS Precision
420 An optional precision, in the form of a period (\[aq].\[aq]) followed by an
421 optional decimal digit string.
422 Instead of a decimal digit string one may write "*" or "*m$"
423 (for some decimal integer \fIm\fP) to specify that the precision
424 is given in the next argument, or in the \fIm\fP-th argument, respectively,
425 which must be of type
426 .IR int .
427 If the precision is given as just \[aq].\[aq], the precision is taken to
428 be zero.
429 A negative precision is taken as if the precision were omitted.
430 This gives the minimum number of digits to appear for
431 .BR d ,
432 .BR i ,
433 .BR o ,
434 .BR u ,
435 .BR x ,
436 and
437 .B X
438 conversions, the number of digits to appear after the radix character for
439 .BR a ,
440 .BR A ,
441 .BR e ,
442 .BR E ,
443 .BR f ,
444 and
445 .B F
446 conversions, the maximum number of significant digits for
447 .B g
448 and
449 .B G
450 conversions, or the maximum number of characters to be printed from a
451 string for
452 .B s
453 and
454 .B S
455 conversions.
456 .SS Length modifier
457 Here, "integer conversion" stands for
458 .BR d ,
459 .BR i ,
460 .BR o ,
461 .BR u ,
462 .BR x ,
463 or
464 .B X
465 conversion.
466 .TP
467 .B hh
468 A following integer conversion corresponds to a
469 .I signed char
470 or
471 .I unsigned char
472 argument, or a following
473 .B n
474 conversion corresponds to a pointer to a
475 .I signed char
476 argument.
477 .TP
478 .B h
479 A following integer conversion corresponds to a
480 .I short
481 or
482 .I unsigned short
483 argument, or a following
484 .B n
485 conversion corresponds to a pointer to a
486 .I short
487 argument.
488 .TP
489 .B l
490 (ell) A following integer conversion corresponds to a
491 .I long
492 or
493 .I unsigned long
494 argument, or a following
495 .B n
496 conversion corresponds to a pointer to a
497 .I long
498 argument, or a following
499 .B c
500 conversion corresponds to a
501 .I wint_t
502 argument, or a following
503 .B s
504 conversion corresponds to a pointer to
505 .I wchar_t
506 argument.
507 On a following
508 .BR a ,
509 .BR A ,
510 .BR e ,
511 .BR E ,
512 .BR f ,
513 .BR F ,
514 .BR g ,
515 or
516 .B G
517 conversion, this length modifier is ignored (C99; not in SUSv2).
518 .TP
519 .B ll
520 (ell-ell).
521 A following integer conversion corresponds to a
522 .I long long
523 or
524 .I unsigned long long
525 argument, or a following
526 .B n
527 conversion corresponds to a pointer to a
528 .I long long
529 argument.
530 .TP
531 .B q
532 A synonym for
533 .BR ll .
534 This is a nonstandard extension, derived from BSD;
535 avoid its use in new code.
536 .TP
537 .B L
538 A following
539 .BR a ,
540 .BR A ,
541 .BR e ,
542 .BR E ,
543 .BR f ,
544 .BR F ,
545 .BR g ,
546 or
547 .B G
548 conversion corresponds to a
549 .I long double
550 argument.
551 (C99 allows %LF, but SUSv2 does not.)
552 .TP
553 .B j
554 A following integer conversion corresponds to an
555 .I intmax_t
556 or
557 .I uintmax_t
558 argument, or a following
559 .B n
560 conversion corresponds to a pointer to an
561 .I intmax_t
562 argument.
563 .TP
564 .B z
565 A following integer conversion corresponds to a
566 .I size_t
567 or
568 .I ssize_t
569 argument, or a following
570 .B n
571 conversion corresponds to a pointer to a
572 .I size_t
573 argument.
574 .TP
575 .B Z
576 A nonstandard synonym for
577 .B z
578 that predates the appearance of
579 .BR z .
580 Do not use in new code.
581 .TP
582 .B t
583 A following integer conversion corresponds to a
584 .I ptrdiff_t
585 argument, or a following
586 .B n
587 conversion corresponds to a pointer to a
588 .I ptrdiff_t
589 argument.
590 .P
591 SUSv3 specifies all of the above,
592 except for those modifiers explicitly noted as being nonstandard extensions.
593 SUSv2 specified only the length modifiers
594 .B h
595 (in
596 .BR hd ,
597 .BR hi ,
598 .BR ho ,
599 .BR hx ,
600 .BR hX ,
601 .BR hn )
602 and
603 .B l
604 (in
605 .BR ld ,
606 .BR li ,
607 .BR lo ,
608 .BR lx ,
609 .BR lX ,
610 .BR ln ,
611 .BR lc ,
612 .BR ls )
613 and
614 .B L
615 (in
616 .BR Le ,
617 .BR LE ,
618 .BR Lf ,
619 .BR Lg ,
620 .BR LG ).
621 .P
622 As a nonstandard extension, the GNU implementations treats
623 .B ll
624 and
625 .B L
626 as synonyms, so that one can, for example, write
627 .B llg
628 (as a synonym for the standards-compliant
629 .BR Lg )
630 and
631 .B Ld
632 (as a synonym for the standards compliant
633 .BR lld ).
634 Such usage is nonportable.
635 .\"
636 .SS Conversion specifiers
637 A character that specifies the type of conversion to be applied.
638 The conversion specifiers and their meanings are:
639 .TP
640 .BR d ", " i
641 The
642 .I int
643 argument is converted to signed decimal notation.
644 The precision, if any, gives the minimum number of digits
645 that must appear; if the converted value requires fewer digits, it is
646 padded on the left with zeros.
647 The default precision is 1.
648 When 0 is printed with an explicit precision 0, the output is empty.
649 .TP
650 .BR o ", " u ", " x ", " X
651 The
652 .I "unsigned int"
653 argument is converted to unsigned octal
654 .RB ( o ),
655 unsigned decimal
656 .RB ( u ),
657 or unsigned hexadecimal
658 .RB ( x
659 and
660 .BR X )
661 notation.
662 The letters
663 .B abcdef
664 are used for
665 .B x
666 conversions; the letters
667 .B ABCDEF
668 are used for
669 .B X
670 conversions.
671 The precision, if any, gives the minimum number of digits
672 that must appear; if the converted value requires fewer digits, it is
673 padded on the left with zeros.
674 The default precision is 1.
675 When 0 is printed with an explicit precision 0, the output is empty.
676 .TP
677 .BR e ", " E
678 The
679 .I double
680 argument is rounded and converted in the style
681 .RB [\-]d \&. ddd e \(+-dd
682 where there is one digit (which is nonzero if the argument is nonzero)
683 before the decimal-point character and the number
684 of digits after it is equal to the precision; if the precision is missing,
685 it is taken as 6; if the precision is zero, no decimal-point character
686 appears.
687 An
688 .B E
689 conversion uses the letter
690 .B E
691 (rather than
692 .BR e )
693 to introduce the exponent.
694 The exponent always contains at least two
695 digits; if the value is zero, the exponent is 00.
696 .TP
697 .BR f ", " F
698 The
699 .I double
700 argument is rounded and converted to decimal notation in the style
701 .RB [\-]ddd \&. ddd,
702 where the number of digits after the decimal-point character is equal to
703 the precision specification.
704 If the precision is missing, it is taken as
705 6; if the precision is explicitly zero, no decimal-point character appears.
706 If a decimal point appears, at least one digit appears before it.
707 .IP
708 (SUSv2 does not know about
709 .B F
710 and says that character string representations for infinity and NaN
711 may be made available.
712 SUSv3 adds a specification for
713 .BR F .
714 The C99 standard specifies "[\-]inf" or "[\-]infinity"
715 for infinity, and a string starting with "nan" for NaN, in the case of
716 .B f
717 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of
718 .B F
719 conversion.)
720 .TP
721 .BR g ", " G
722 The
723 .I double
724 argument is converted in style
725 .B f
726 or
727 .B e
728 (or
729 .B F
730 or
731 .B E
732 for
733 .B G
734 conversions).
735 The precision specifies the number of significant digits.
736 If the precision is missing, 6 digits are given; if the precision is zero,
737 it is treated as 1.
738 Style
739 .B e
740 is used if the exponent from its conversion is less than \-4 or greater
741 than or equal to the precision.
742 Trailing zeros are removed from the
743 fractional part of the result; a decimal point appears only if it is
744 followed by at least one digit.
745 .TP
746 .BR a ", " A
747 (C99; not in SUSv2, but added in SUSv3)
748 For
749 .B a
750 conversion, the
751 .I double
752 argument is converted to hexadecimal notation (using the letters abcdef)
753 in the style
754 .RB [\-] 0x h \&. hhhh p \(+-d;
755 for
756 .B A
757 conversion the prefix
758 .BR 0X ,
759 the letters ABCDEF, and the exponent separator
760 .B P
761 is used.
762 There is one hexadecimal digit before the radix point,
763 and the number of digits after it is equal to the precision.
764 The default precision suffices for an exact representation of the value
765 if an exact representation in base 2 exists
766 and otherwise is sufficiently large to distinguish values of type
767 .IR double .
768 The digit before the radix point is unspecified for nonnormalized
769 numbers, and nonzero but otherwise unspecified for normalized numbers.
770 The exponent,
771 .IR d ,
772 is the appropriate exponent of 2 expressed as a decimal integer;
773 it always contains at least one digit;
774 if the value is zero, the exponent is 0.
775 .TP
776 .B c
777 If no
778 .B l
779 modifier is present, the
780 .I int
781 argument is converted to an
782 .IR "unsigned char" ,
783 and the resulting character is written.
784 If an
785 .B l
786 modifier is present, the
787 .I wint_t
788 (wide character) argument is converted to a multibyte sequence by a call
789 to the
790 .BR wcrtomb (3)
791 function, with a conversion state starting in the initial state, and the
792 resulting multibyte string is written.
793 .TP
794 .B s
795 If no
796 .B l
797 modifier is present: the
798 .I "const char\ *"
799 argument is expected to be a pointer to an array of character type (pointer
800 to a string).
801 Characters from the array are written up to (but not
802 including) a terminating null byte (\[aq]\[rs]0\[aq]);
803 if a precision is specified, no more than the number specified
804 are written.
805 If a precision is given, no null byte need be present;
806 if the precision is not specified, or is greater than the size of the
807 array, the array must contain a terminating null byte.
808 .IP
809 If an
810 .B l
811 modifier is present: the
812 .I "const wchar_t\ *"
813 argument is expected to be a pointer to an array of wide characters.
814 Wide characters from the array are converted to multibyte characters
815 (each by a call to the
816 .BR wcrtomb (3)
817 function, with a conversion state starting in the initial state before
818 the first wide character), up to and including a terminating null
819 wide character.
820 The resulting multibyte characters are written up to
821 (but not including) the terminating null byte.
822 If a precision is
823 specified, no more bytes than the number specified are written, but
824 no partial multibyte characters are written.
825 Note that the precision
826 determines the number of
827 .I bytes
828 written, not the number of
829 .I wide characters
830 or
831 .IR "screen positions" .
832 The array must contain a terminating null wide character, unless a
833 precision is given and it is so small that the number of bytes written
834 exceeds it before the end of the array is reached.
835 .TP
836 .B C
837 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
838 Synonym for
839 .BR lc .
840 Don't use.
841 .TP
842 .B S
843 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
844 Synonym for
845 .BR ls .
846 Don't use.
847 .TP
848 .B p
849 The
850 .I "void\ *"
851 pointer argument is printed in hexadecimal (as if by
852 .B %#x
853 or
854 .BR %#lx ).
855 .TP
856 .B n
857 The number of characters written so far is stored into the integer
858 pointed to by the corresponding argument.
859 That argument shall be an
860 .IR "int\ *" ,
861 or variant whose size matches the (optionally)
862 supplied integer length modifier.
863 No argument is converted.
864 (This specifier is not supported by the bionic C library.)
865 The behavior is undefined if the conversion specification includes
866 any flags, a field width, or a precision.
867 .TP
868 .B m
869 (glibc extension; supported by uClibc and musl.)
870 Print output of
871 .I strerror(errno)
872 (or
873 .I strerrorname_np(errno)
874 in the alternate form).
875 No argument is required.
876 .TP
877 .B %
878 A \[aq]%\[aq] is written.
879 No argument is converted.
880 The complete conversion
881 specification is \[aq]%%\[aq].
882 .SH RETURN VALUE
883 Upon successful return, these functions return the number of bytes
884 printed (excluding the null byte used to end output to strings).
885 .P
886 The functions
887 .BR snprintf ()
888 and
889 .BR vsnprintf ()
890 do not write more than
891 .I size
892 bytes (including the terminating null byte (\[aq]\[rs]0\[aq])).
893 If the output was truncated due to this limit, then the return value
894 is the number of characters (excluding the terminating null byte)
895 which would have been written to the final string if enough space
896 had been available.
897 Thus, a return value of
898 .I size
899 or more means that the output was truncated.
900 (See also below under CAVEATS.)
901 .P
902 If an output error is encountered, a negative value is returned.
903 .SH ATTRIBUTES
904 For an explanation of the terms used in this section, see
905 .BR attributes (7).
906 .TS
907 allbox;
908 lbx lb lb
909 l l l.
910 Interface Attribute Value
911 T{
912 .na
913 .nh
914 .BR printf (),
915 .BR fprintf (),
916 .BR sprintf (),
917 .BR snprintf (),
918 .BR vprintf (),
919 .BR vfprintf (),
920 .BR vsprintf (),
921 .BR vsnprintf ()
922 T} Thread safety MT-Safe locale
923 .TE
924 .SH STANDARDS
925 .TP
926 .BR fprintf ()
927 .TQ
928 .BR printf ()
929 .TQ
930 .BR sprintf ()
931 .TQ
932 .BR vprintf ()
933 .TQ
934 .BR vfprintf ()
935 .TQ
936 .BR vsprintf ()
937 .TQ
938 .BR snprintf ()
939 .TQ
940 .BR vsnprintf ()
941 C11, POSIX.1-2008.
942 .TP
943 .BR dprintf ()
944 .TQ
945 .BR vdprintf ()
946 GNU, POSIX.1-2008.
947 .SH HISTORY
948 .TP
949 .BR fprintf ()
950 .TQ
951 .BR printf ()
952 .TQ
953 .BR sprintf ()
954 .TQ
955 .BR vprintf ()
956 .TQ
957 .BR vfprintf ()
958 .TQ
959 .BR vsprintf ()
960 C89, POSIX.1-2001.
961 .TP
962 .BR snprintf ()
963 .TQ
964 .BR vsnprintf ()
965 SUSv2, C99, POSIX.1-2001.
966 .IP
967 Concerning the return value of
968 .BR snprintf (),
969 SUSv2 and C99 contradict each other: when
970 .BR snprintf ()
971 is called with
972 .IR size =0
973 then SUSv2 stipulates an unspecified return value less than 1,
974 while C99 allows
975 .I str
976 to be NULL in this case, and gives the return value (as always)
977 as the number of characters that would have been written in case
978 the output string has been large enough.
979 POSIX.1-2001 and later align their specification of
980 .BR snprintf ()
981 with C99.
982 .TP
983 .BR dprintf ()
984 .TQ
985 .BR vdprintf ()
986 GNU, POSIX.1-2008.
987 .P
988 Issue 4 of the X/Open Portability Guide (SUSv1, 1994) adds
989 .BR \[aq] .
990 .P
991 .\" Linux libc4 knows about the five C standard flags.
992 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
993 .\" and the conversions
994 .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
995 .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
996 .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
997 .\" where \fBF\fP is a synonym for \fBf\fP.
998 .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
999 .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
1000 .\" (This is bad, and caused serious bugs later, when
1001 .\" support for \fB%D\fP disappeared.)
1002 .\" No locale-dependent radix character,
1003 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
1004 .\" .P
1005 .\" Linux libc5 knows about the five C standard flags and the \[aq] flag,
1006 .\" locale, "%m$" and "*m$".
1007 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
1008 .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
1009 .\" both for \fIlong double\fP and for \fIlong long\fP (this is a bug).
1010 .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
1011 .\" but adds the conversion character
1012 .\" .BR m ,
1013 .\" which outputs
1014 .\" .IR strerror(errno) .
1015 .\" .P
1016 .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
1017 .\" .P
1018 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
1019 and conversion characters \fBa\fP and \fBA\fP.
1020 .P
1021 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
1022 and the flag character \fBI\fP.
1023 .P
1024 glibc 2.35 gives a meaning to the alternate form
1025 .RB ( # )
1026 of the
1027 .B m
1028 conversion specifier, that is
1029 .IR %#m .
1030 .SH CAVEATS
1031 Some programs imprudently rely on code such as the following
1032 .P
1033 .in +4n
1034 .EX
1035 sprintf(buf, "%s some further text", buf);
1036 .EE
1037 .in
1038 .P
1039 to append text to
1040 .IR buf .
1041 However, the standards explicitly note that the results are undefined
1042 if source and destination buffers overlap when calling
1043 .BR sprintf (),
1044 .BR snprintf (),
1045 .BR vsprintf (),
1046 and
1047 .BR vsnprintf ().
1048 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
1049 Depending on the version of
1050 .BR gcc (1)
1051 used, and the compiler options employed, calls such as the above will
1052 .B not
1053 produce the expected results.
1054 .P
1055 The glibc implementation of the functions
1056 .BR snprintf ()
1057 and
1058 .BR vsnprintf ()
1059 conforms to the C99 standard, that is, behaves as described above,
1060 since glibc 2.1.
1061 Until glibc 2.0.6, they would return \-1
1062 when the output was truncated.
1063 .\" .SH HISTORY
1064 .\" UNIX V7 defines the three routines
1065 .\" .BR printf (),
1066 .\" .BR fprintf (),
1067 .\" .BR sprintf (),
1068 .\" and has the flag \-, the width or precision *, the length modifier l,
1069 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
1070 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
1071 .\" #, + and <space> and no longer mentions D,O,U,X.
1072 .\" 2.11BSD has
1073 .\" .BR vprintf (),
1074 .\" .BR vfprintf (),
1075 .\" .BR vsprintf (),
1076 .\" and warns not to use D,O,U,X.
1077 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
1078 .\" and the conversions n, p, E, G, X (with current meaning)
1079 .\" and deprecates D,O,U.
1080 .\" 4.4BSD introduces the functions
1081 .\" .BR snprintf ()
1082 .\" and
1083 .\" .BR vsnprintf (),
1084 .\" and the length modifier q.
1085 .\" FreeBSD also has functions
1086 .\" .BR asprintf ()
1087 .\" and
1088 .\" .BR vasprintf (),
1089 .\" that allocate a buffer large enough for
1090 .\" .BR sprintf ().
1091 .\" In glibc there are functions
1092 .\" .BR dprintf ()
1093 .\" and
1094 .\" .BR vdprintf ()
1095 .\" that print to a file descriptor instead of a stream.
1096 .SH BUGS
1097 Because
1098 .BR sprintf ()
1099 and
1100 .BR vsprintf ()
1101 assume an arbitrarily long string, callers must be careful not to overflow
1102 the actual space; this is often impossible to assure.
1103 Note that the length
1104 of the strings produced is locale-dependent and difficult to predict.
1105 Use
1106 .BR snprintf ()
1107 and
1108 .BR vsnprintf ()
1109 instead (or
1110 .BR asprintf (3)
1111 and
1112 .BR vasprintf (3)).
1113 .\" .P
1114 .\" Linux libc4.[45] does not have a
1115 .\" .BR snprintf (),
1116 .\" but provides a libbsd that contains an
1117 .\" .BR snprintf ()
1118 .\" equivalent to
1119 .\" .BR sprintf (),
1120 .\" that is, one that ignores the
1121 .\" .I size
1122 .\" argument.
1123 .\" Thus, the use of
1124 .\" .BR snprintf ()
1125 .\" with early libc4 leads to serious security problems.
1126 .P
1127 Code such as
1128 .BI printf( foo );
1129 often indicates a bug, since
1130 .I foo
1131 may contain a % character.
1132 If
1133 .I foo
1134 comes from untrusted user input, it may contain \fB%n\fP, causing the
1135 .BR printf ()
1136 call to write to memory and creating a security hole.
1137 .\" .P
1138 .\" Some floating-point conversions under early libc4
1139 .\" caused memory leaks.
1140 .SH EXAMPLES
1141 To print
1142 .I Pi
1143 to five decimal places:
1144 .P
1145 .in +4n
1146 .EX
1147 #include <math.h>
1148 #include <stdio.h>
1149 fprintf(stdout, "pi = %.5f\[rs]n", 4 * atan(1.0));
1150 .EE
1151 .in
1152 .P
1153 To print a date and time in the form "Sunday, July 3, 10:02",
1154 where
1155 .I weekday
1156 and
1157 .I month
1158 are pointers to strings:
1159 .P
1160 .in +4n
1161 .EX
1162 #include <stdio.h>
1163 fprintf(stdout, "%s, %s %d, %.2d:%.2d\[rs]n",
1164 weekday, month, day, hour, min);
1165 .EE
1166 .in
1167 .P
1168 Many countries use the day-month-year order.
1169 Hence, an internationalized version must be able to print
1170 the arguments in an order specified by the format:
1171 .P
1172 .in +4n
1173 .EX
1174 #include <stdio.h>
1175 fprintf(stdout, format,
1176 weekday, month, day, hour, min);
1177 .EE
1178 .in
1179 .P
1180 where
1181 .I format
1182 depends on locale, and may permute the arguments.
1183 With the value:
1184 .P
1185 .in +4n
1186 .EX
1187 "%1$s, %3$d. %2$s, %4$d:%5$.2d\[rs]n"
1188 .EE
1189 .in
1190 .P
1191 one might obtain "Sonntag, 3. Juli, 10:02".
1192 .P
1193 To allocate a sufficiently large string and print into it
1194 (code correct for both glibc 2.0 and glibc 2.1):
1195 .P
1196 .EX
1197 #include <stdio.h>
1198 #include <stdlib.h>
1199 #include <stdarg.h>
1200 \&
1201 char *
1202 make_message(const char *fmt, ...)
1203 {
1204 int n = 0;
1205 size_t size = 0;
1206 char *p = NULL;
1207 va_list ap;
1208 \&
1209 /* Determine required size. */
1210 \&
1211 va_start(ap, fmt);
1212 n = vsnprintf(p, size, fmt, ap);
1213 va_end(ap);
1214 \&
1215 if (n < 0)
1216 return NULL;
1217 \&
1218 size = (size_t) n + 1; /* One extra byte for \[aq]\[rs]0\[aq] */
1219 p = malloc(size);
1220 if (p == NULL)
1221 return NULL;
1222 \&
1223 va_start(ap, fmt);
1224 n = vsnprintf(p, size, fmt, ap);
1225 va_end(ap);
1226 \&
1227 if (n < 0) {
1228 free(p);
1229 return NULL;
1230 }
1231 \&
1232 return p;
1233 }
1234 .EE
1235 .P
1236 If truncation occurs in glibc versions prior to glibc 2.0.6,
1237 this is treated as an error instead of being handled gracefully.
1238 .SH SEE ALSO
1239 .BR printf (1),
1240 .BR asprintf (3),
1241 .BR puts (3),
1242 .BR scanf (3),
1243 .BR setlocale (3),
1244 .BR strfromd (3),
1245 .BR wcrtomb (3),
1246 .BR wprintf (3),
1247 .BR locale (5)