1 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
3 .\" Earlier versions of this page influenced the present text.
4 .\" It was derived from a Berkeley page with version
5 .\" @(#)printf.3 6.14 (Berkeley) 7/30/91
6 .\" converted for Linux by faith@cs.unc.edu, updated by
7 .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
9 .\" SPDX-License-Identifier: GPL-2.0-or-later
11 .\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99.
12 .\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes
13 .\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes
15 .TH PRINTF 3 2021-03-22 "GNU" "Linux Programmer's Manual"
17 printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf,
18 vsprintf, vsnprintf \- formatted output conversion
21 .RI ( libc ", " \-lc )
26 .BI "int printf(const char *restrict " format ", ...);"
27 .BI "int fprintf(FILE *restrict " stream ,
28 .BI " const char *restrict " format ", ...);"
29 .BI "int dprintf(int " fd ,
30 .BI " const char *restrict " format ", ...);"
31 .BI "int sprintf(char *restrict " str ,
32 .BI " const char *restrict " format ", ...);"
33 .BI "int snprintf(char *restrict " str ", size_t " size ,
34 .BI " const char *restrict " format ", ...);"
36 .B #include <stdarg.h>
38 .BI "int vprintf(const char *restrict " format ", va_list " ap );
39 .BI "int vfprintf(FILE *restrict " stream ,
40 .BI " const char *restrict " format ", va_list " ap );
41 .BI "int vdprintf(int " fd ,
42 .BI " const char *restrict " format ", va_list " ap );
43 .BI "int vsprintf(char *restrict " str ,
44 .BI " const char *restrict " format ", va_list " ap );
45 .BI "int vsnprintf(char *restrict " str ", size_t " size ,
46 .BI " const char *restrict " format ", va_list " ap );
50 Feature Test Macro Requirements for glibc (see
51 .BR feature_test_macros (7)):
57 _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
58 || /* Glibc <= 2.19: */ _BSD_SOURCE
65 _POSIX_C_SOURCE >= 200809L
72 family produce output according to a
81 the standard output stream;
85 write output to the given output
92 write to the character string
99 except that it outputs to a file descriptor,
111 bytes (including the terminating null byte (\(aq\e0\(aq)) to
120 are equivalent to the functions
126 respectively, except that they are called with a
128 instead of a variable number of arguments.
129 These functions do not call the
132 Because they invoke the
136 is undefined after the call.
140 All of these functions write the output under the control of a
142 string that specifies how subsequent arguments (or arguments accessed via
143 the variable-length argument facilities of
145 are converted for output.
147 C99 and POSIX.1-2001 specify that the results are undefined if a call to
153 would cause copying to take place between objects that overlap
154 (e.g., if the target string array and one of the supplied input arguments
155 refer to the same buffer).
157 .SS Format of the format string
158 The format string is a character string, beginning and ending
159 in its initial shift state, if any.
160 The format string is composed of zero or more directives: ordinary
163 which are copied unchanged to the output stream;
164 and conversion specifications, each of which results in fetching zero or
165 more subsequent arguments.
166 Each conversion specification is introduced by
170 .IR "conversion specifier" .
171 In between there may be (in this order) zero or more
178 .IR "length modifier" .
180 The overall syntax of a conversion specification is:
184 %[$][flags][width][.precision][length modifier]conversion
188 The arguments must correspond properly (after type promotion) with the
189 conversion specifier.
190 By default, the arguments are used in the order
191 given, where each \(aq*\(aq (see
195 below) and each conversion specifier asks for the next
196 argument (and it is an error if insufficiently many arguments are given).
197 One can also specify explicitly which argument is taken,
198 at each place where an argument is required, by writing "%m$" instead
199 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
200 where the decimal integer \fIm\fP denotes
201 the position in the argument list of the desired argument, indexed starting
207 printf("%*d", width, num);
215 printf("%2$*1$d", width, num);
220 The second style allows repeated references to the
222 The C99 standard does not include the style using \(aq$\(aq,
223 which comes from the Single UNIX Specification.
225 \(aq$\(aq is used, it must be used throughout for all conversions taking an
226 argument and all width and precision arguments, but it may be mixed
227 with "%%" formats, which do not consume an argument.
229 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
230 arguments 1 and 3 are specified, argument 2 must also be specified
231 somewhere in the format string.
233 For some numeric conversions a radix character ("decimal point") or
234 thousands' grouping character is used.
235 The actual character used
242 uses \(aq.\(aq as radix character, and does not have a grouping character.
247 printf("%\(aq.2f", 1234567.89);
251 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
252 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
254 The character % is followed by zero or more of the following flags:
257 The value should be converted to an "alternate form".
260 conversions, the first character of the output string is made zero
261 (by prefixing a 0 if it was not zero already).
266 conversions, a nonzero result has the string "0x" (or "0X" for
268 conversions) prepended to it.
279 conversions, the result will always contain a decimal point, even if no
280 digits follow it (normally, a decimal point appears in the results of those
281 conversions only if a digit follows).
286 conversions, trailing zeros are not removed from the result as they would
292 contains a valid error code,
294 .I strerrorname_np(errno)
296 otherwise, the value stored in
298 is printed as a decimal number.
299 For other conversions, the result is undefined.
302 The value should be zero padded.
319 conversions, the converted value is padded on the left with zeros rather
325 flags both appear, the
328 If a precision is given with a numeric conversion
339 For other conversions, the behavior is undefined.
342 The converted value is to be left adjusted on the field boundary.
343 (The default is right justification.)
344 The converted value is padded on the right with blanks, rather
345 than on the left with blanks or zeros.
353 (a space) A blank should be left before a positive number
354 (or empty string) produced by a signed conversion.
357 A sign (+ or \-) should always be placed before a number produced by a signed
359 By default, a sign is used only for negative numbers.
362 overrides a space if both are used.
364 The five flag characters above are defined in the C99 standard.
365 The Single UNIX Specification specifies one further flag character.
368 For decimal conversion
376 the output is to be grouped with thousands' grouping characters
377 if the locale information indicates any.
380 Note that many versions of
382 cannot parse this option and will issue a warning.
384 include \fI%\(aqF\fP, but SUSv3 added it.)
386 glibc 2.2 adds one further flag character.
389 For decimal integer conversion
393 the output uses the locale's alternative output digits, if any.
394 For example, since glibc 2.2.3 this will give Arabic-Indic digits
395 in the Persian ("fa_IR") locale.
396 .\" outdigits keyword in locale file
398 An optional decimal digit string (with nonzero first digit) specifying
399 a minimum field width.
400 If the converted value has fewer characters
401 than the field width, it will be padded with spaces on the left
402 (or right, if the left-adjustment flag has been given).
403 Instead of a decimal digit string one may write "*" or "*m$"
404 (for some decimal integer \fIm\fP) to specify that the field width
405 is given in the next argument, or in the \fIm\fP-th argument, respectively,
406 which must be of type
408 A negative field width is taken as a \(aq\-\(aq flag followed by a
409 positive field width.
410 In no case does a nonexistent or small field width cause truncation of a
411 field; if the result of a conversion is wider than the field width, the
412 field is expanded to contain the conversion result.
414 An optional precision, in the form of a period (\(aq.\(aq) followed by an
415 optional decimal digit string.
416 Instead of a decimal digit string one may write "*" or "*m$"
417 (for some decimal integer \fIm\fP) to specify that the precision
418 is given in the next argument, or in the \fIm\fP-th argument, respectively,
419 which must be of type
421 If the precision is given as just \(aq.\(aq, the precision is taken to
423 A negative precision is taken as if the precision were omitted.
424 This gives the minimum number of digits to appear for
432 conversions, the number of digits to appear after the radix character for
440 conversions, the maximum number of significant digits for
444 conversions, or the maximum number of characters to be printed from a
451 Here, "integer conversion" stands for
462 A following integer conversion corresponds to a
466 argument, or a following
468 conversion corresponds to a pointer to a
473 A following integer conversion corresponds to a
477 argument, or a following
479 conversion corresponds to a pointer to a
484 (ell) A following integer conversion corresponds to a
488 argument, or a following
490 conversion corresponds to a pointer to a
492 argument, or a following
494 conversion corresponds to a
496 argument, or a following
498 conversion corresponds to a pointer to
504 A following integer conversion corresponds to a
507 .I unsigned long long
508 argument, or a following
510 conversion corresponds to a pointer to a
517 This is a nonstandard extension, derived from BSD;
518 avoid its use in new code.
531 conversion corresponds to a
534 (C99 allows %LF, but SUSv2 does not.)
537 A following integer conversion corresponds to an
541 argument, or a following
543 conversion corresponds to a pointer to an
548 A following integer conversion corresponds to a
552 argument, or a following
554 conversion corresponds to a pointer to a
559 A nonstandard synonym for
561 that predates the appearance of
563 Do not use in new code.
566 A following integer conversion corresponds to a
568 argument, or a following
570 conversion corresponds to a pointer to a
574 SUSv3 specifies all of the above,
575 except for those modifiers explicitly noted as being nonstandard extensions.
576 SUSv2 specified only the length modifiers
605 As a nonstandard extension, the GNU implementations treats
609 as synonyms, so that one can, for example, write
611 (as a synonym for the standards-compliant
615 (as a synonym for the standards compliant
617 Such usage is nonportable.
619 .SS Conversion specifiers
620 A character that specifies the type of conversion to be applied.
621 The conversion specifiers and their meanings are:
626 argument is converted to signed decimal notation.
627 The precision, if any, gives the minimum number of digits
628 that must appear; if the converted value requires fewer digits, it is
629 padded on the left with zeros.
630 The default precision is 1.
631 When 0 is printed with an explicit precision 0, the output is empty.
633 .BR o ", " u ", " x ", " X
636 argument is converted to unsigned octal
640 or unsigned hexadecimal
649 conversions; the letters
654 The precision, if any, gives the minimum number of digits
655 that must appear; if the converted value requires fewer digits, it is
656 padded on the left with zeros.
657 The default precision is 1.
658 When 0 is printed with an explicit precision 0, the output is empty.
663 argument is rounded and converted in the style
664 .RB [\-]d \&. ddd e \(+-dd
665 where there is one digit (which is nonzero if the argument is nonzero)
666 before the decimal-point character and the number
667 of digits after it is equal to the precision; if the precision is missing,
668 it is taken as 6; if the precision is zero, no decimal-point character
672 conversion uses the letter
676 to introduce the exponent.
677 The exponent always contains at least two
678 digits; if the value is zero, the exponent is 00.
683 argument is rounded and converted to decimal notation in the style
685 where the number of digits after the decimal-point character is equal to
686 the precision specification.
687 If the precision is missing, it is taken as
688 6; if the precision is explicitly zero, no decimal-point character appears.
689 If a decimal point appears, at least one digit appears before it.
691 (SUSv2 does not know about
693 and says that character string representations for infinity and NaN
694 may be made available.
695 SUSv3 adds a specification for
697 The C99 standard specifies "[\-]inf" or "[\-]infinity"
698 for infinity, and a string starting with "nan" for NaN, in the case of
700 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of
707 argument is converted in style
718 The precision specifies the number of significant digits.
719 If the precision is missing, 6 digits are given; if the precision is zero,
723 is used if the exponent from its conversion is less than \-4 or greater
724 than or equal to the precision.
725 Trailing zeros are removed from the
726 fractional part of the result; a decimal point appears only if it is
727 followed by at least one digit.
730 (C99; not in SUSv2, but added in SUSv3)
735 argument is converted to hexadecimal notation (using the letters abcdef)
737 .RB [\-] 0x h \&. hhhh p \(+-d;
740 conversion the prefix
742 the letters ABCDEF, and the exponent separator
745 There is one hexadecimal digit before the decimal point,
746 and the number of digits after it is equal to the precision.
747 The default precision suffices for an exact representation of the value
748 if an exact representation in base 2 exists
749 and otherwise is sufficiently large to distinguish values of type
751 The digit before the decimal point is unspecified for nonnormalized
752 numbers, and nonzero but otherwise unspecified for normalized numbers.
753 The exponent always contains at least one
754 digit; if the value is zero, the exponent is 0.
759 modifier is present, the
761 argument is converted to an
762 .IR "unsigned char" ,
763 and the resulting character is written.
766 modifier is present, the
768 (wide character) argument is converted to a multibyte sequence by a call
771 function, with a conversion state starting in the initial state, and the
772 resulting multibyte string is written.
777 modifier is present: the
779 argument is expected to be a pointer to an array of character type (pointer
781 Characters from the array are written up to (but not
782 including) a terminating null byte (\(aq\e0\(aq);
783 if a precision is specified, no more than the number specified
785 If a precision is given, no null byte need be present;
786 if the precision is not specified, or is greater than the size of the
787 array, the array must contain a terminating null byte.
791 modifier is present: the
792 .I "const wchar_t\ *"
793 argument is expected to be a pointer to an array of wide characters.
794 Wide characters from the array are converted to multibyte characters
795 (each by a call to the
797 function, with a conversion state starting in the initial state before
798 the first wide character), up to and including a terminating null
800 The resulting multibyte characters are written up to
801 (but not including) the terminating null byte.
803 specified, no more bytes than the number specified are written, but
804 no partial multibyte characters are written.
805 Note that the precision
806 determines the number of
808 written, not the number of
811 .IR "screen positions" .
812 The array must contain a terminating null wide character, unless a
813 precision is given and it is so small that the number of bytes written
814 exceeds it before the end of the array is reached.
817 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
823 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
831 pointer argument is printed in hexadecimal (as if by
837 The number of characters written so far is stored into the integer
838 pointed to by the corresponding argument.
839 That argument shall be an
841 or variant whose size matches the (optionally)
842 supplied integer length modifier.
843 No argument is converted.
844 (This specifier is not supported by the bionic C library.)
845 The behavior is undefined if the conversion specification includes
846 any flags, a field width, or a precision.
849 (Glibc extension; supported by uClibc and musl.)
853 .I strerrorname_np(errno)
854 in the alternate form).
855 No argument is required.
858 A \(aq%\(aq is written.
859 No argument is converted.
860 The complete conversion
861 specification is \(aq%%\(aq.
863 Upon successful return, these functions return the number of characters
864 printed (excluding the null byte used to end output to strings).
870 do not write more than
872 bytes (including the terminating null byte (\(aq\e0\(aq)).
873 If the output was truncated due to this limit, then the return value
874 is the number of characters (excluding the terminating null byte)
875 which would have been written to the final string if enough space
877 Thus, a return value of
879 or more means that the output was truncated.
880 (See also below under NOTES.)
882 If an output error is encountered, a negative value is returned.
884 .\" Linux libc4 knows about the five C standard flags.
885 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
886 .\" and the conversions
887 .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
888 .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
889 .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
890 .\" where \fBF\fP is a synonym for \fBf\fP.
891 .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
892 .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
893 .\" (This is bad, and caused serious bugs later, when
894 .\" support for \fB%D\fP disappeared.)
895 .\" No locale-dependent radix character,
896 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
898 .\" Linux libc5 knows about the five C standard flags and the \(aq flag,
899 .\" locale, "%m$" and "*m$".
900 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
901 .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
902 .\" both for \fIlong double\fP and for \fIlong long\fP (this is a bug).
903 .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
904 .\" but adds the conversion character
907 .\" .IR strerror(errno) .
909 .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
911 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
912 and conversion characters \fBa\fP and \fBA\fP.
914 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
915 and the flag character \fBI\fP.
917 glibc 2.35 gives a meaning to the alternate form
921 conversion specifier, that is
924 For an explanation of the terms used in this section, see
932 Interface Attribute Value
942 T} Thread safety MT-Safe locale
954 POSIX.1-2001, POSIX.1-2008, C89, C99.
958 POSIX.1-2001, POSIX.1-2008, C99.
964 functions were originally GNU extensions that were later standardized
967 Concerning the return value of
969 SUSv2 and C99 contradict each other: when
973 then SUSv2 stipulates an unspecified return value less than 1,
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
983 Some programs imprudently rely on code such as the following
987 sprintf(buf, "%s some further text", buf);
993 However, the standards explicitly note that the results are undefined
994 if source and destination buffers overlap when calling
1000 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
1001 Depending on the version of
1003 used, and the compiler options employed, calls such as the above will
1005 produce the expected results.
1007 The glibc implementation of the functions
1011 conforms to the C99 standard, that is, behaves as described above,
1012 since glibc version 2.1.
1013 Until glibc 2.0.6, they would return \-1
1014 when the output was truncated.
1016 .\" UNIX V7 defines the three routines
1020 .\" and has the flag \-, the width or precision *, the length modifier l,
1021 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
1022 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
1023 .\" #, + and <space> and no longer mentions D,O,U,X.
1026 .\" .BR vfprintf (),
1027 .\" .BR vsprintf (),
1028 .\" and warns not to use D,O,U,X.
1029 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
1030 .\" and the conversions n, p, E, G, X (with current meaning)
1031 .\" and deprecates D,O,U.
1032 .\" 4.4BSD introduces the functions
1035 .\" .BR vsnprintf (),
1036 .\" and the length modifier q.
1037 .\" FreeBSD also has functions
1040 .\" .BR vasprintf (),
1041 .\" that allocate a buffer large enough for
1043 .\" In glibc there are functions
1047 .\" that print to a file descriptor instead of a stream.
1053 assume an arbitrarily long string, callers must be careful not to overflow
1054 the actual space; this is often impossible to assure.
1055 Note that the length
1056 of the strings produced is locale-dependent and difficult to predict.
1066 .\" Linux libc4.[45] does not have a
1067 .\" .BR snprintf (),
1068 .\" but provides a libbsd that contains an
1072 .\" that is, one that ignores the
1075 .\" Thus, the use of
1077 .\" with early libc4 leads to serious security problems.
1081 often indicates a bug, since
1083 may contain a % character.
1086 comes from untrusted user input, it may contain \fB%n\fP, causing the
1088 call to write to memory and creating a security hole.
1090 .\" Some floating-point conversions under early libc4
1091 .\" caused memory leaks.
1095 to five decimal places:
1101 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
1105 To print a date and time in the form "Sunday, July 3, 10:02",
1110 are pointers to strings:
1115 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
1116 weekday, month, day, hour, min);
1120 Many countries use the day-month-year order.
1121 Hence, an internationalized version must be able to print
1122 the arguments in an order specified by the format:
1127 fprintf(stdout, format,
1128 weekday, month, day, hour, min);
1134 depends on locale, and may permute the arguments.
1139 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
1143 one might obtain "Sonntag, 3. Juli, 10:02".
1145 To allocate a sufficiently large string and print into it
1146 (code correct for both glibc 2.0 and glibc 2.1):
1154 make_message(const char *fmt, ...)
1161 /* Determine required size. */
1164 n = vsnprintf(p, size, fmt, ap);
1170 size = (size_t) n + 1; /* One extra byte for \(aq\e0\(aq */
1176 n = vsnprintf(p, size, fmt, ap);
1188 If truncation occurs in glibc versions prior to 2.0.6, this is treated as an
1189 error instead of being handled gracefully.