Debian Codegraph @

upstream/debian-unstable/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-16 "Linux man-pages 6.18"
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 .BI w N
532 A following integer conversion corresponds to an
533 integer of a width of
534 .I N
535 bits
536 (C23).
537 .TP
538 .B z
539 A following integer conversion corresponds to a
540 .I size_t
541 or
542 .I ssize_t
543 argument, or a following
544 .B n
545 conversion corresponds to a pointer to a
546 .I size_t
547 argument.
548 .TP
549 .B Z
550 A nonstandard synonym for
551 .B z
552 that predates the appearance of
553 .BR z .
554 Do not use in new code.
555 .TP
556 .B t
557 A following integer conversion corresponds to a
558 .I ptrdiff_t
559 argument, or a following
560 .B n
561 conversion corresponds to a pointer to a
562 .I ptrdiff_t
563 argument.
564 .P
565 SUSv3 specifies all of the above,
566 except for those modifiers explicitly noted as being nonstandard extensions.
567 SUSv2 specified only the length modifiers
568 .B h
569 (in
570 .BR hd ,
571 .BR hi ,
572 .BR ho ,
573 .BR hx ,
574 .BR hX ,
575 .BR hn )
576 and
577 .B l
578 (in
579 .BR ld ,
580 .BR li ,
581 .BR lo ,
582 .BR lx ,
583 .BR lX ,
584 .BR ln ,
585 .BR lc ,
586 .BR ls )
587 and
588 .B L
589 (in
590 .BR Le ,
591 .BR LE ,
592 .BR Lf ,
593 .BR Lg ,
594 .BR LG ).
595 .P
596 As a nonstandard extension, the GNU implementations treats
597 .B ll
598 and
599 .B L
600 as synonyms, so that one can, for example, write
601 .B llg
602 (as a synonym for the standards-compliant
603 .BR Lg )
604 and
605 .B Ld
606 (as a synonym for the standards compliant
607 .BR lld ).
608 Such usage is nonportable.
609 .\"
610 .SS Conversion specifiers
611 A character that specifies the type of conversion to be applied.
612 The conversion specifiers and their meanings are:
613 .TP
614 .BR d ", " i
615 The
616 .I int
617 argument is converted to signed decimal notation.
618 The precision, if any,
619 gives the minimum number of digits that must appear;
620 if the converted value requires fewer digits,
621 it is padded on the left with zeros.
622 The default precision is 1.
623 When 0 is printed with an explicit precision 0,
624 the output is empty.
625 .TP
626 .BR o ", " u ", " x ", " X
627 The
628 .I "unsigned int"
629 argument is converted to unsigned octal
630 .RB ( o ),
631 unsigned decimal
632 .RB ( u ),
633 or unsigned hexadecimal
634 .RB ( x
635 and
636 .BR X )
637 notation.
638 The letters
639 .B abcdef
640 are used for
641 .B x
642 conversions;
643 the letters
644 .B ABCDEF
645 are used for
646 .B X
647 conversions.
648 The precision, if any,
649 gives the minimum number of digits that must appear;
650 if the converted value requires fewer digits,
651 it is padded on the left with zeros.
652 The default precision is 1.
653 When 0 is printed with an explicit precision 0,
654 the output is empty.
655 .TP
656 .BR e ", " E
657 The
658 .I double
659 argument is rounded and converted in the style
660 .RB [\-]d \&. ddd e \(+-dd
661 where there is one digit
662 (which is nonzero if the argument is nonzero)
663 before the decimal-point character
664 and the number of digits after it is equal to the precision;
665 if the precision is missing,
666 it is taken as 6;
667 if the precision is zero,
668 no decimal-point character appears.
669 An
670 .B E
671 conversion uses the letter
672 .B E
673 (rather than
674 .BR e )
675 to introduce the exponent.
676 The exponent always contains at least two digits;
677 if the value is zero,
678 the exponent is 00.
679 .TP
680 .BR f ", " F
681 The
682 .I double
683 argument is rounded and converted to decimal notation in the style
684 .RB [\-]ddd \&. ddd,
685 where the number of digits after the decimal-point character
686 is equal to the precision specification.
687 If the precision is missing,
688 it is taken as 6;
689 if the precision is explicitly zero,
690 no decimal-point character appears.
691 If a decimal point appears,
692 at least one digit appears before it.
693 .IP
694 (SUSv2 does not know about
695 .B F
696 and says that character string representations for infinity and NaN
697 may be made available.
698 SUSv3 adds a specification for
699 .BR F .
700 The C99 standard specifies "[\-]inf" or "[\-]infinity"
701 for infinity, and a string starting with "nan" for NaN, in the case of
702 .B f
703 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of
704 .B F
705 conversion.)
706 .TP
707 .BR g ", " G
708 The
709 .I double
710 argument is converted in style
711 .B f
712 or
713 .B e
714 (or
715 .B F
716 or
717 .B E
718 for
719 .B G
720 conversions).
721 The precision specifies the number of significant digits.
722 If the precision is missing,
723 6 digits are given;
724 if the precision is zero,
725 it is treated as 1.
726 Style
727 .B e
728 is used if the exponent from its conversion is less than \-4
729 or greater than or equal to the precision.
730 Trailing zeros are removed from the fractional part of the result;
731 a decimal point appears
732 only if it is followed by at least one digit.
733 .TP
734 .BR a ", " A
735 (C99;
736 not in SUSv2, but added in SUSv3)
737 For
738 .B a
739 conversion, the
740 .I double
741 argument is converted to hexadecimal notation (using the letters abcdef)
742 in the style
743 .RB [\-] 0x h \&. hhhh p \(+-d;
744 for
745 .B A
746 conversion the prefix
747 .BR 0X ,
748 the letters ABCDEF, and the exponent separator
749 .B P
750 is used.
751 There is one hexadecimal digit before the radix point,
752 and the number of digits after it is equal to the precision.
753 The default precision suffices for an exact representation of the value
754 if an exact representation in base 2 exists
755 and otherwise is sufficiently large to distinguish values of type
756 .IR double .
757 The digit before the radix point is unspecified for nonnormalized
758 numbers, and nonzero but otherwise unspecified for normalized numbers.
759 The exponent,
760 .IR d ,
761 is the appropriate exponent of 2 expressed as a decimal integer;
762 it always contains at least one digit;
763 if the value is zero, the exponent is 0.
764 .TP
765 .B c
766 If no
767 .B l
768 modifier is present, the
769 .I int
770 argument is converted to an
771 .IR "unsigned char" ,
772 and the resulting character is written.
773 If an
774 .B l
775 modifier is present, the
776 .I wint_t
777 (wide character) argument is converted to a multibyte sequence by a call
778 to the
779 .BR wcrtomb (3)
780 function, with a conversion state starting in the initial state, and the
781 resulting multibyte string is written.
782 .TP
783 .B s
784 If no
785 .B l
786 modifier is present: the
787 .I "const char\ *"
788 argument is expected to be a pointer to an array of character type (pointer
789 to a string).
790 Characters from the array are written up to (but not
791 including) a terminating null byte (\[aq]\[rs]0\[aq]);
792 if a precision is specified, no more than the number specified
793 are written.
794 If a precision is given, no null byte need be present;
795 if the precision is not specified, or is greater than the size of the
796 array, the array must contain a terminating null byte.
797 .IP
798 If an
799 .B l
800 modifier is present: the
801 .I "const wchar_t\ *"
802 argument is expected to be a pointer to an array of wide characters.
803 Wide characters from the array are converted to multibyte characters
804 (each by a call to the
805 .BR wcrtomb (3)
806 function, with a conversion state starting in the initial state before
807 the first wide character), up to and including a terminating null
808 wide character.
809 The resulting multibyte characters are written up to
810 (but not including) the terminating null byte.
811 If a precision is
812 specified, no more bytes than the number specified are written, but
813 no partial multibyte characters are written.
814 Note that the precision
815 determines the number of
816 .I bytes
817 written, not the number of
818 .I wide characters
819 or
820 .IR "screen positions" .
821 The array must contain a terminating null wide character, unless a
822 precision is given and it is so small that the number of bytes written
823 exceeds it before the end of the array is reached.
824 .TP
825 .B C
826 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
827 Synonym for
828 .BR lc .
829 Don't use.
830 .TP
831 .B S
832 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
833 Synonym for
834 .BR ls .
835 Don't use.
836 .TP
837 .B p
838 The
839 .I "void\ *"
840 pointer argument is printed in hexadecimal (as if by
841 .B %#x
842 or
843 .BR %#lx ).
844 .TP
845 .B n
846 The number of characters written so far is stored into the integer
847 pointed to by the corresponding argument.
848 That argument shall be an
849 .IR "int\ *" ,
850 or variant whose size matches the (optionally)
851 supplied integer length modifier.
852 No argument is converted.
853 (This specifier is not supported by the bionic C library.)
854 The behavior is undefined if the conversion specification includes
855 any flags, a field width, or a precision.
856 .TP
857 .B m
858 (glibc extension;
859 supported by uClibc and musl,
860 and on Android from API level 29.)
861 Print output of
862 .I strerror(errno)
863 (or
864 .I strerrorname_np(errno)
865 in the alternate form).
866 No argument is required.
867 .TP
868 .B %
869 A \[aq]%\[aq] is written.
870 No argument is converted.
871 The complete conversion
872 specification is \[aq]%%\[aq].
873 .SH RETURN VALUE
874 Upon successful return, these functions return the number of bytes
875 printed (excluding the null byte used to end output to strings).
876 .P
877 On error,
878 a negative value is returned,
879 and
880 .I errno
881 is set to indicate the error.
882 .SH ERRORS
883 See
884 .BR write (2)
885 and
886 .BR putwc (3).
887 In addition, the following error may occur:
888 .TP
889 .B EOVERFLOW
890 The value to be returned is greater than
891 .BR INT_MAX .
892 .P
893 The
894 .BR dprintf ()
895 function may fail additionally if:
896 .TP
897 .B EBADF
898 The
899 .I fd
900 argument is not a valid file descriptor.
901 .SH ATTRIBUTES
902 For an explanation of the terms used in this section, see
903 .BR attributes (7).
904 .TS
905 allbox;
906 lbx lb lb
907 l l l.
908 Interface Attribute Value
909 T{
910 .na
911 .nh
912 .BR printf (),
913 .BR fprintf (),
914 .BR vprintf (),
915 .BR vfprintf ()
916 T} Thread safety MT-Safe locale
917 .TE
918 .SH STANDARDS
919 .TP
920 .BR fprintf ()
921 .TQ
922 .BR printf ()
923 .TQ
924 .BR vprintf ()
925 .TQ
926 .BR vfprintf ()
927 C11, POSIX.1-2008.
928 .TP
929 .BR dprintf ()
930 .TQ
931 .BR vdprintf ()
932 GNU, POSIX.1-2008.
933 .SH HISTORY
934 .TP
935 .BR fprintf ()
936 .TQ
937 .BR printf ()
938 .TQ
939 .BR vprintf ()
940 .TQ
941 .BR vfprintf ()
942 C89, POSIX.1-2001.
943 .TP
944 .BR dprintf ()
945 .TQ
946 .BR vdprintf ()
947 GNU, POSIX.1-2008.
948 .P
949 Issue 4 of the X/Open Portability Guide (SUSv1, 1994) adds
950 .BR \[aq] .
951 .P
952 .\" Linux libc4 knows about the five C standard flags.
953 .\" It knows about the length modifiers \f[B]h\f[], \f[B]l\f[], \f[B]L\f[],
954 .\" and the conversions
955 .\" \f[B]c\f[], \f[B]d\f[], \f[B]e\f[], \f[B]E\f[], \f[B]f\f[], \f[B]F\f[],
956 .\" \f[B]g\f[], \f[B]G\f[], \f[B]i\f[], \f[B]n\f[], \f[B]o\f[], \f[B]p\f[],
957 .\" \f[B]s\f[], \f[B]u\f[], \f[B]x\f[], and \f[B]X\f[],
958 .\" where \f[B]F\f[] is a synonym for \f[B]f\f[].
959 .\" Additionally, it accepts \f[B]D\f[], \f[B]O\f[], and \f[B]U\f[] as synonyms
960 .\" for \f[B]ld\f[], \f[B]lo\f[], and \f[B]lu\f[].
961 .\" (This is bad, and caused serious bugs later, when
962 .\" support for \f[B]%D\f[] disappeared.)
963 .\" No locale-dependent radix character,
964 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
965 .\" .P
966 .\" Linux libc5 knows about the five C standard flags and the \[aq] flag,
967 .\" locale, "%m$" and "*m$".
968 .\" It knows about the length modifiers \f[B]h\f[], \f[B]l\f[], \f[B]L\f[],
969 .\" \f[B]Z\f[], and \f[B]q\f[], but accepts \f[B]L\f[] and \f[B]q\f[]
970 .\" both for \f[I]long double\f[] and for \f[I]long long\f[] (this is a bug).
971 .\" It no longer recognizes \f[B]F\f[], \f[B]D\f[], \f[B]O\f[], and \f[B]U\f[],
972 .\" but adds the conversion character
973 .\" .BR m ,
974 .\" which outputs
975 .\" .IR strerror(errno) .
976 .\" .P
977 .\" glibc 2.0 adds conversion characters \f[B]C\f[] and \f[B]S\f[].
978 .\" .P
979 glibc 2.1 adds length modifiers
980 .BR hh ,
981 .BR j ,
982 .BR t ,
983 and
984 .B z
985 and conversion characters
986 .B a
987 and
988 .BR A .
989 .P
990 glibc 2.2 adds the conversion character
991 .B F
992 with C99 semantics,
993 and the flag character
994 .BR I .
995 .P
996 glibc 2.35 gives a meaning to the alternate form
997 .RB ( # )
998 of the
999 .B m
1000 conversion specifier, that is
1001 .IR %#m .
1002 .\" .SH HISTORY
1003 .\" UNIX V7 defines the three routines
1004 .\" .BR printf (),
1005 .\" .BR fprintf (),
1006 .\" .BR sprintf (),
1007 .\" and has the flag \-, the width or precision *, the length modifier l,
1008 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
1009 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
1010 .\" #, + and <space> and no longer mentions D,O,U,X.
1011 .\" 2.11BSD has
1012 .\" .BR vprintf (),
1013 .\" .BR vfprintf (),
1014 .\" .BR vsprintf (),
1015 .\" and warns not to use D,O,U,X.
1016 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
1017 .\" and the conversions n, p, E, G, X (with current meaning)
1018 .\" and deprecates D,O,U.
1019 .\" 4.4BSD introduces the functions
1020 .\" .BR snprintf ()
1021 .\" and
1022 .\" .BR vsnprintf (),
1023 .\" and the length modifier q.
1024 .\" FreeBSD also has functions
1025 .\" .BR asprintf ()
1026 .\" and
1027 .\" .BR vasprintf (),
1028 .\" that allocate a buffer large enough for
1029 .\" .BR sprintf ().
1030 .\" In glibc there are functions
1031 .\" .BR dprintf ()
1032 .\" and
1033 .\" .BR vdprintf ()
1034 .\" that print to a file descriptor instead of a stream.
1035 .SH BUGS
1036 Code such as
1037 .BI printf( foo );
1038 often indicates a bug, since
1039 .I foo
1040 may contain a % character.
1041 If
1042 .I foo
1043 comes from untrusted user input, it may contain
1044 .BR %n ,
1045 causing the
1046 .BR printf ()
1047 call to write to memory and creating a security hole.
1048 .\" .P
1049 .\" Some floating-point conversions under early libc4
1050 .\" caused memory leaks.
1051 .SH EXAMPLES
1052 To print
1053 .I Pi
1054 to five decimal places:
1055 .P
1056 .in +4n
1057 .EX
1058 #include <math.h>
1059 #include <stdio.h>
1060 fprintf(stdout, "pi = %.5f\[rs]n", 4 * atan(1.0));
1061 .EE
1062 .in
1063 .P
1064 To print a date and time in the form "Sunday, July 3, 10:02",
1065 where
1066 .I weekday
1067 and
1068 .I month
1069 are pointers to strings:
1070 .P
1071 .in +4n
1072 .EX
1073 #include <stdio.h>
1074 fprintf(stdout, "%s, %s %d, %.2d:%.2d\[rs]n",
1075 weekday, month, day, hour, min);
1076 .EE
1077 .in
1078 .P
1079 Many countries use the day-month-year order.
1080 Hence, an internationalized version must be able to print
1081 the arguments in an order specified by the format:
1082 .P
1083 .in +4n
1084 .EX
1085 #include <stdio.h>
1086 fprintf(stdout, format,
1087 weekday, month, day, hour, min);
1088 .EE
1089 .in
1090 .P
1091 where
1092 .I format
1093 depends on locale, and may permute the arguments.
1094 With the value:
1095 .P
1096 .in +4n
1097 .EX
1098 "%1$s, %3$d.\& %2$s, %4$d:%5$.2d\[rs]n"
1099 .EE
1100 .in
1101 .P
1102 one might obtain "Sonntag, 3.\& Juli, 10:02".
1103 .SH SEE ALSO
1104 .BR printf (1),
1105 .BR asprintf (3),
1106 .BR puts (3),
1107 .BR scanf (3),
1108 .BR setlocale (3),
1109 .BR snprintf (3),
1110 .BR strfromd (3),
1111 .BR wcrtomb (3),
1112 .BR wprintf (3),
1113 .BR locale (5)