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 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
10 .\" This is free documentation; you can redistribute it and/or
11 .\" modify it under the terms of the GNU General Public License as
12 .\" published by the Free Software Foundation; either version 2 of
13 .\" the License, or (at your option) any later version.
15 .\" The GNU General Public License's references to "object code"
16 .\" and "executables" are to be interpreted as the output of any
17 .\" document formatting or typesetting system, including
18 .\" intermediate and printed output.
20 .\" This manual is distributed in the hope that it will be useful,
21 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
22 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 .\" GNU General Public License for more details.
25 .\" You should have received a copy of the GNU General Public
26 .\" License along with this manual; if not, see
27 .\" <http://www.gnu.org/licenses/>.
30 .\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99.
31 .\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes
32 .\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes
34 .TH PRINTF 3 2017-09-15 "GNU" "Linux Programmer's Manual"
36 printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf,
37 vsprintf, vsnprintf \- formatted output conversion
42 .BI "int printf(const char *" format ", ...);"
43 .BI "int fprintf(FILE *" stream ", const char *" format ", ...);"
44 .BI "int dprintf(int " fd ", const char *" format ", ...);"
45 .BI "int sprintf(char *" str ", const char *" format ", ...);"
46 .BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);"
48 .B #include <stdarg.h>
50 .BI "int vprintf(const char *" format ", va_list " ap );
51 .BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap );
52 .BI "int vdprintf(int " fd ", const char *" format ", va_list " ap );
53 .BI "int vsprintf(char *" str ", const char *" format ", va_list " ap );
54 .BI "int vsnprintf(char *" str ", size_t " size ", const char *" format \
59 Feature Test Macro Requirements for glibc (see
60 .BR feature_test_macros (7)):
67 _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
68 || /* Glibc versions <= 2.19: */ _BSD_SOURCE
77 _POSIX_C_SOURCE\ >=\ 200809L
87 family produce output according to a
96 the standard output stream;
100 write output to the given output
107 write to the character string
114 except that it outputs to a file descriptor,
126 bytes (including the terminating null byte (\(aq\e0\(aq)) to
135 are equivalent to the functions
141 respectively, except that they are called with a
143 instead of a variable number of arguments.
144 These functions do not call the
147 Because they invoke the
151 is undefined after the call.
155 All of these functions write the output under the control of a
157 string that specifies how subsequent arguments (or arguments accessed via
158 the variable-length argument facilities of
160 are converted for output.
162 C99 and POSIX.1-2001 specify that the results are undefined if a call to
168 would cause copying to take place between objects that overlap
169 (e.g., if the target string array and one of the supplied input arguments
170 refer to the same buffer).
172 .SS Format of the format string
173 The format string is a character string, beginning and ending
174 in its initial shift state, if any.
175 The format string is composed of zero or more directives: ordinary
178 which are copied unchanged to the output stream;
179 and conversion specifications, each of which results in fetching zero or
180 more subsequent arguments.
181 Each conversion specification is introduced by
185 .IR "conversion specifier" .
186 In between there may be (in this order) zero or more
193 .IR "length modifier" .
195 The arguments must correspond properly (after type promotion) with the
196 conversion specifier.
197 By default, the arguments are used in the order
198 given, where each \(aq*\(aq (see
202 below) and each conversion specifier asks for the next
203 argument (and it is an error if insufficiently many arguments are given).
204 One can also specify explicitly which argument is taken,
205 at each place where an argument is required, by writing "%m$" instead
206 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
207 where the decimal integer \fIm\fP denotes
208 the position in the argument list of the desired argument, indexed starting
214 printf("%*d", width, num);
222 printf("%2$*1$d", width, num);
227 The second style allows repeated references to the
229 The C99 standard does not include the style using \(aq$\(aq,
230 which comes from the Single UNIX Specification.
232 \(aq$\(aq is used, it must be used throughout for all conversions taking an
233 argument and all width and precision arguments, but it may be mixed
234 with "%%" formats, which do not consume an argument.
236 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
237 arguments 1 and 3 are specified, argument 2 must also be specified
238 somewhere in the format string.
240 For some numeric conversions a radix character ("decimal point") or
241 thousands' grouping character is used.
242 The actual character used
249 uses \(aq.\(aq as radix character, and does not have a grouping character.
254 printf("%\(aq.2f", 1234567.89);
258 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
259 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
261 The character % is followed by zero or more of the following flags:
264 The value should be converted to an "alternate form".
267 conversions, the first character of the output string is made zero
268 (by prefixing a 0 if it was not zero already).
273 conversions, a nonzero result has the string "0x" (or "0X" for
275 conversions) prepended to it.
286 conversions, the result will always contain a decimal point, even if no
287 digits follow it (normally, a decimal point appears in the results of those
288 conversions only if a digit follows).
293 conversions, trailing zeros are not removed from the result as they would
295 For other conversions, the result is undefined.
298 The value should be zero padded.
315 conversions, the converted value is padded on the left with zeros rather
321 flags both appear, the
324 If a precision is given with a numeric conversion
335 For other conversions, the behavior is undefined.
338 The converted value is to be left adjusted on the field boundary.
339 (The default is right justification.)
340 The converted value is padded on the right with blanks, rather
341 than on the left with blanks or zeros.
349 (a space) A blank should be left before a positive number
350 (or empty string) produced by a signed conversion.
353 A sign (+ or \-) should always be placed before a number produced by a signed
355 By default, a sign is used only for negative numbers.
358 overrides a space if both are used.
360 The five flag characters above are defined in the C99 standard.
361 The Single UNIX Specification specifies one further flag character.
364 For decimal conversion
372 the output is to be grouped with thousands' grouping characters
373 if the locale information indicates any.
376 Note that many versions of
378 cannot parse this option and will issue a warning.
380 include \fI%\(aqF\fP, but SUSv3 added it.)
382 glibc 2.2 adds one further flag character.
385 For decimal integer conversion
389 the output uses the locale's alternative output digits, if any.
390 For example, since glibc 2.2.3 this will give Arabic-Indic digits
391 in the Persian ("fa_IR") locale.
392 .\" outdigits keyword in locale file
394 An optional decimal digit string (with nonzero first digit) specifying
395 a minimum field width.
396 If the converted value has fewer characters
397 than the field width, it will be padded with spaces on the left
398 (or right, if the left-adjustment flag has been given).
399 Instead of a decimal digit string one may write "*" or "*m$"
400 (for some decimal integer \fIm\fP) to specify that the field width
401 is given in the next argument, or in the \fIm\fP-th argument, respectively,
402 which must be of type
404 A negative field width is taken as a \(aq\-\(aq flag followed by a
405 positive field width.
406 In no case does a nonexistent or small field width cause truncation of a
407 field; if the result of a conversion is wider than the field width, the
408 field is expanded to contain the conversion result.
410 An optional precision, in the form of a period (\(aq.\(aq) followed by an
411 optional decimal digit string.
412 Instead of a decimal digit string one may write "*" or "*m$"
413 (for some decimal integer \fIm\fP) to specify that the precision
414 is given in the next argument, or in the \fIm\fP-th argument, respectively,
415 which must be of type
417 If the precision is given as just \(aq.\(aq, the precision is taken to
419 A negative precision is taken as if the precision were omitted.
420 This gives the minimum number of digits to appear for
428 conversions, the number of digits to appear after the radix character for
436 conversions, the maximum number of significant digits for
440 conversions, or the maximum number of characters to be printed from a
447 Here, "integer conversion" stands for
458 A following integer conversion corresponds to a
462 argument, or a following
464 conversion corresponds to a pointer to a
469 A following integer conversion corresponds to a
472 .I unsigned short int
473 argument, or a following
475 conversion corresponds to a pointer to a
480 (ell) A following integer conversion corresponds to a
484 argument, or a following
486 conversion corresponds to a pointer to a
488 argument, or a following
490 conversion corresponds to a
492 argument, or a following
494 conversion corresponds to a pointer to
500 A following integer conversion corresponds to a
503 .I unsigned long long int
504 argument, or a following
506 conversion corresponds to a pointer to a
513 This is a nonstandard extension, derived from BSD;
514 avoid its use in new code.
527 conversion corresponds to a
530 (C99 allows %LF, but SUSv2 does not.)
533 A following integer conversion corresponds to an
537 argument, or a following
539 conversion corresponds to a pointer to an
544 A following integer conversion corresponds to a
548 argument, or a following
550 conversion corresponds to a pointer to a
555 A nonstandard synonym for
557 that predates the appearance of
559 Do not use in new code.
562 A following integer conversion corresponds to a
564 argument, or a following
566 conversion corresponds to a pointer to a
570 SUSv3 specifies all of the above,
571 except for those modifiers explicitly noted as being nonstandard extensions.
572 SUSv2 specified only the length modifiers
601 As a nonstandard extension, the GNU implementations treats
605 as synonyms, so that one can, for example, write
607 (as a synonym for the standards-compliant
611 (as a synonym for the standards compliant
613 Such usage is nonportable.
615 .SS Conversion specifiers
616 A character that specifies the type of conversion to be applied.
617 The conversion specifiers and their meanings are:
622 argument is converted to signed decimal notation.
623 The precision, if any, gives the minimum number of digits
624 that must appear; if the converted value requires fewer digits, it is
625 padded on the left with zeros.
626 The default precision is 1.
627 When 0 is printed with an explicit precision 0, the output is empty.
629 .BR o ", " u ", " x ", " X
632 argument is converted to unsigned octal
636 or unsigned hexadecimal
645 conversions; the letters
650 The precision, if any, gives the minimum number of digits
651 that must appear; if the converted value requires fewer digits, it is
652 padded on the left with zeros.
653 The default precision is 1.
654 When 0 is printed with an explicit precision 0, the output is empty.
659 argument is rounded and converted in the style
660 .RB [\-]d \&. ddd e \(+-dd
661 where there is one digit before the decimal-point character and the number
662 of digits after it is equal to the precision; if the precision is missing,
663 it is taken as 6; if the precision is zero, no decimal-point character
667 conversion uses the letter
671 to introduce the exponent.
672 The exponent always contains at least two
673 digits; if the value is zero, the exponent is 00.
678 argument is rounded and converted to decimal notation in the style
680 where the number of digits after the decimal-point character is equal to
681 the precision specification.
682 If the precision is missing, it is taken as
683 6; if the precision is explicitly zero, no decimal-point character appears.
684 If a decimal point appears, at least one digit appears before it.
686 (SUSv2 does not know about
688 and says that character string representations for infinity and NaN
689 may be made available.
690 SUSv3 adds a specification for
692 The C99 standard specifies "[\-]inf" or "[\-]infinity"
693 for infinity, and a string starting with "nan" for NaN, in the case of
695 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of
702 argument is converted in style
713 The precision specifies the number of significant digits.
714 If the precision is missing, 6 digits are given; if the precision is zero,
718 is used if the exponent from its conversion is less than \-4 or greater
719 than or equal to the precision.
720 Trailing zeros are removed from the
721 fractional part of the result; a decimal point appears only if it is
722 followed by at least one digit.
725 (C99; not in SUSv2, but added in SUSv3)
730 argument is converted to hexadecimal notation (using the letters abcdef)
732 .RB [\-] 0x h \&. hhhh p \(+-;
735 conversion the prefix
737 the letters ABCDEF, and the exponent separator
740 There is one hexadecimal digit before the decimal point,
741 and the number of digits after it is equal to the precision.
742 The default precision suffices for an exact representation of the value
743 if an exact representation in base 2 exists
744 and otherwise is sufficiently large to distinguish values of type
746 The digit before the decimal point is unspecified for nonnormalized
747 numbers, and nonzero but otherwise unspecified for normalized numbers.
752 modifier is present, the
754 argument is converted to an
755 .IR "unsigned char" ,
756 and the resulting character is written.
759 modifier is present, the
761 (wide character) argument is converted to a multibyte sequence by a call
764 function, with a conversion state starting in the initial state, and the
765 resulting multibyte string is written.
770 modifier is present: the
772 argument is expected to be a pointer to an array of character type (pointer
774 Characters from the array are written up to (but not
775 including) a terminating null byte (\(aq\\0\(aq);
776 if a precision is specified, no more than the number specified
778 If a precision is given, no null byte need be present;
779 if the precision is not specified, or is greater than the size of the
780 array, the array must contain a terminating null byte.
784 modifier is present: the
785 .I "const wchar_t\ *"
786 argument is expected to be a pointer to an array of wide characters.
787 Wide characters from the array are converted to multibyte characters
788 (each by a call to the
790 function, with a conversion state starting in the initial state before
791 the first wide character), up to and including a terminating null
793 The resulting multibyte characters are written up to
794 (but not including) the terminating null byte.
796 specified, no more bytes than the number specified are written, but
797 no partial multibyte characters are written.
798 Note that the precision
799 determines the number of
801 written, not the number of
804 .IR "screen positions" .
805 The array must contain a terminating null wide character, unless a
806 precision is given and it is so small that the number of bytes written
807 exceeds it before the end of the array is reached.
810 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
816 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
824 pointer argument is printed in hexadecimal (as if by
830 The number of characters written so far is stored into the integer
831 pointed to by the corresponding argument.
832 That argument shall be an
834 or variant whose size matches the (optionally)
835 supplied integer length modifier.
836 No argument is converted.
837 (This specifier is not supported by the bionic C library.)
838 The behavior is undefined if the conversion specification includes
839 any flags, a field width, or a precision.
842 (Glibc extension; supported by uClibc and musl.)
844 .IR strerror(errno) .
845 No argument is required.
848 A \(aq%\(aq is written.
849 No argument is converted.
850 The complete conversion
851 specification is \(aq%%\(aq.
853 Upon successful return, these functions return the number of characters
854 printed (excluding the null byte used to end output to strings).
860 do not write more than
862 bytes (including the terminating null byte (\(aq\e0\(aq)).
863 If the output was truncated due to this limit, then the return value
864 is the number of characters (excluding the terminating null byte)
865 which would have been written to the final string if enough space
867 Thus, a return value of
869 or more means that the output was truncated.
870 (See also below under NOTES.)
872 If an output error is encountered, a negative value is returned.
874 For an explanation of the terms used in this section, see
880 Interface Attribute Value
893 T} Thread safety MT-Safe locale
903 POSIX.1-2001, POSIX.1-2008, C89, C99.
907 POSIX.1-2001, POSIX.1-2008, C99.
913 functions were originally GNU extensions that were later standardized
916 Concerning the return value of
918 SUSv2 and C99 contradict each other: when
922 then SUSv2 stipulates an unspecified return value less than 1,
925 to be NULL in this case, and gives the return value (as always)
926 as the number of characters that would have been written in case
927 the output string has been large enough.
928 POSIX.1-2001 and later align their specification of
932 .\" Linux libc4 knows about the five C standard flags.
933 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
934 .\" and the conversions
935 .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
936 .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
937 .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
938 .\" where \fBF\fP is a synonym for \fBf\fP.
939 .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
940 .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
941 .\" (This is bad, and caused serious bugs later, when
942 .\" support for \fB%D\fP disappeared.)
943 .\" No locale-dependent radix character,
944 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
946 .\" Linux libc5 knows about the five C standard flags and the \(aq flag,
947 .\" locale, "%m$" and "*m$".
948 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
949 .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
950 .\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
951 .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
952 .\" but adds the conversion character
955 .\" .IR strerror(errno) .
957 .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
959 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
960 and conversion characters \fBa\fP and \fBA\fP.
962 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
963 and the flag character \fBI\fP.
965 Some programs imprudently rely on code such as the following
967 sprintf(buf, "%s some further text", buf);
971 However, the standards explicitly note that the results are undefined
972 if source and destination buffers overlap when calling
978 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
979 Depending on the version of
981 used, and the compiler options employed, calls such as the above will
983 produce the expected results.
985 The glibc implementation of the functions
989 conforms to the C99 standard, that is, behaves as described above,
990 since glibc version 2.1.
991 Until glibc 2.0.6, they would return \-1
992 when the output was truncated.
994 .\" UNIX V7 defines the three routines
998 .\" and has the flag \-, the width or precision *, the length modifier l,
999 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
1000 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
1001 .\" #, + and <space> and no longer mentions D,O,U,X.
1004 .\" .BR vfprintf (),
1005 .\" .BR vsprintf (),
1006 .\" and warns not to use D,O,U,X.
1007 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
1008 .\" and the conversions n, p, E, G, X (with current meaning)
1009 .\" and deprecates D,O,U.
1010 .\" 4.4BSD introduces the functions
1013 .\" .BR vsnprintf (),
1014 .\" and the length modifier q.
1015 .\" FreeBSD also has functions
1018 .\" .BR vasprintf (),
1019 .\" that allocate a buffer large enough for
1021 .\" In glibc there are functions
1025 .\" that print to a file descriptor instead of a stream.
1031 assume an arbitrarily long string, callers must be careful not to overflow
1032 the actual space; this is often impossible to assure.
1033 Note that the length
1034 of the strings produced is locale-dependent and difficult to predict.
1044 .\" Linux libc4.[45] does not have a
1045 .\" .BR snprintf (),
1046 .\" but provides a libbsd that contains an
1050 .\" that is, one that ignores the
1053 .\" Thus, the use of
1055 .\" with early libc4 leads to serious security problems.
1059 often indicates a bug, since
1061 may contain a % character.
1064 comes from untrusted user input, it may contain \fB%n\fP, causing the
1066 call to write to memory and creating a security hole.
1068 .\" Some floating-point conversions under early libc4
1069 .\" caused memory leaks.
1073 to five decimal places:
1079 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
1083 To print a date and time in the form "Sunday, July 3, 10:02",
1088 are pointers to strings:
1093 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
1094 weekday, month, day, hour, min);
1098 Many countries use the day-month-year order.
1099 Hence, an internationalized version must be able to print
1100 the arguments in an order specified by the format:
1105 fprintf(stdout, format,
1106 weekday, month, day, hour, min);
1112 depends on locale, and may permute the arguments.
1117 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
1121 one might obtain "Sonntag, 3. Juli, 10:02".
1123 To allocate a sufficiently large string and print into it
1124 (code correct for both glibc 2.0 and glibc 2.1):
1132 make_message(const char *fmt, ...)
1138 /* Determine required size */
1141 size = vsnprintf(p, size, fmt, ap);
1147 size++; /* For '\\0' */
1153 size = vsnprintf(p, size, fmt, ap);
1165 If truncation occurs in glibc versions prior to 2.0.6, this is treated as an
1166 error instead of being handled gracefully.