Debian Codegraph @

upstream/mageia-cauldron/man3/printf.3

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