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 2016-12-12 "GNU" "Linux Programmer's Manual"
36 printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf,
37 vsprintf, vsnprintf \- formatted output conversion
41 .BI "int printf(const char *" format ", ...);"
43 .BI "int fprintf(FILE *" stream ", const char *" format ", ...);"
45 .BI "int dprintf(int " fd ", const char *" format ", ...);"
47 .BI "int sprintf(char *" str ", const char *" format ", ...);"
49 .BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);"
51 .B #include <stdarg.h>
53 .BI "int vprintf(const char *" format ", va_list " ap );
55 .BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap );
57 .BI "int vdprintf(int " fd ", const char *" format ", va_list " ap );
59 .BI "int vsprintf(char *" str ", const char *" format ", va_list " ap );
61 .BI "int vsnprintf(char *" str ", size_t " size ", const char *" format \
65 Feature Test Macro Requirements for glibc (see
66 .BR feature_test_macros (7)):
73 _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
74 || /* Glibc versions <= 2.19: */ _BSD_SOURCE
83 _POSIX_C_SOURCE\ >=\ 200809L
93 family produce output according to a
102 the standard output stream;
106 write output to the given output
113 write to the character string
120 except that it outputs to a file descriptor,
132 bytes (including the terminating null byte (\(aq\e0\(aq)) to
141 are equivalent to the functions
147 respectively, except that they are called with a
149 instead of a variable number of arguments.
150 These functions do not call the
153 Because they invoke the
157 is undefined after the call.
161 All of these functions write the output under the control of a
163 string that specifies how subsequent arguments (or arguments accessed via
164 the variable-length argument facilities of
166 are converted for output.
168 C99 and POSIX.1-2001 specify that the results are undefined if a call to
174 would cause copying to take place between objects that overlap
175 (e.g., if the target string array and one of the supplied input arguments
176 refer to the same buffer).
178 .SS Format of the format string
179 The format string is a character string, beginning and ending
180 in its initial shift state, if any.
181 The format string is composed of zero or more directives: ordinary
184 which are copied unchanged to the output stream;
185 and conversion specifications, each of which results in fetching zero or
186 more subsequent arguments.
187 Each conversion specification is introduced by
191 .IR "conversion specifier" .
192 In between there may be (in this order) zero or more
199 .IR "length modifier" .
201 The arguments must correspond properly (after type promotion) with the
202 conversion specifier.
203 By default, the arguments are used in the order
204 given, where each \(aq*\(aq (see
208 below) and each conversion specifier asks for the next
209 argument (and it is an error if insufficiently many arguments are given).
210 One can also specify explicitly which argument is taken,
211 at each place where an argument is required, by writing "%m$" instead
212 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
213 where the decimal integer \fIm\fP denotes
214 the position in the argument list of the desired argument, indexed starting
220 printf("%*d", width, num);
228 printf("%2$*1$d", width, num);
233 The second style allows repeated references to the
235 The C99 standard does not include the style using \(aq$\(aq,
236 which comes from the Single UNIX Specification.
238 \(aq$\(aq is used, it must be used throughout for all conversions taking an
239 argument and all width and precision arguments, but it may be mixed
240 with "%%" formats, which do not consume an argument.
242 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
243 arguments 1 and 3 are specified, argument 2 must also be specified
244 somewhere in the format string.
246 For some numeric conversions a radix character ("decimal point") or
247 thousands' grouping character is used.
248 The actual character used
253 uses \(aq.\(aq as radix character, and does not have a grouping character.
258 printf("%\(aq.2f", 1234567.89);
262 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
263 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
265 The character % is followed by zero or more of the following flags:
268 The value should be converted to an "alternate form".
271 conversions, the first character of the output string is made zero
272 (by prefixing a 0 if it was not zero already).
277 conversions, a nonzero result has the string "0x" (or "0X" for
279 conversions) prepended to it.
290 conversions, the result will always contain a decimal point, even if no
291 digits follow it (normally, a decimal point appears in the results of those
292 conversions only if a digit follows).
297 conversions, trailing zeros are not removed from the result as they would
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.
378 Note that many versions of
380 cannot parse this option and will issue a warning.
382 include \fI%\(aqF\fP, but SUSv3 added it.)
384 glibc 2.2 adds one further flag character.
387 For decimal integer conversion
391 the output uses the locale's alternative output digits, if any.
392 For example, since glibc 2.2.3 this will give Arabic-Indic digits
393 in the Persian ("fa_IR") locale.
394 .\" outdigits keyword in locale file
396 An optional decimal digit string (with nonzero first digit) specifying
397 a minimum field width.
398 If the converted value has fewer characters
399 than the field width, it will be padded with spaces on the left
400 (or right, if the left-adjustment flag has been given).
401 Instead of a decimal digit string one may write "*" or "*m$"
402 (for some decimal integer \fIm\fP) to specify that the field width
403 is given in the next argument, or in the \fIm\fP-th argument, respectively,
404 which must be of type
406 A negative field width is taken as a \(aq\-\(aq flag followed by a
407 positive field width.
408 In no case does a nonexistent or small field width cause truncation of a
409 field; if the result of a conversion is wider than the field width, the
410 field is expanded to contain the conversion result.
412 An optional precision, in the form of a period (\(aq.\(aq) followed by an
413 optional decimal digit string.
414 Instead of a decimal digit string one may write "*" or "*m$"
415 (for some decimal integer \fIm\fP) to specify that the precision
416 is given in the next argument, or in the \fIm\fP-th argument, respectively,
417 which must be of type
419 If the precision is given as just \(aq.\(aq, the precision is taken to
421 A negative precision is taken as if the precision were omitted.
422 This gives the minimum number of digits to appear for
430 conversions, the number of digits to appear after the radix character for
438 conversions, the maximum number of significant digits for
442 conversions, or the maximum number of characters to be printed from a
449 Here, "integer conversion" stands for
460 A following integer conversion corresponds to a
464 argument, or a following
466 conversion corresponds to a pointer to a
471 A following integer conversion corresponds to a
474 .I unsigned short int
475 argument, or a following
477 conversion corresponds to a pointer to a
482 (ell) A following integer conversion corresponds to a
486 argument, or a following
488 conversion corresponds to a pointer to a
490 argument, or a following
492 conversion corresponds to a
494 argument, or a following
496 conversion corresponds to a pointer to
502 A following integer conversion corresponds to a
505 .I unsigned long long int
506 argument, or a following
508 conversion corresponds to a pointer to a
523 conversion corresponds to a
526 (C99 allows %LF, but SUSv2 does not.)
529 .\" ("quad". 4.4BSD and Linux libc5 only.
531 This is a synonym for
535 A following integer conversion corresponds to an
539 argument, or a following
541 conversion corresponds to a pointer to an
546 A following integer conversion corresponds to a
550 argument, or a following
552 conversion corresponds to a pointer to a
557 .\" with this meaning.
561 A following integer conversion corresponds to a
563 argument, or a following
565 conversion corresponds to a pointer to a
569 SUSv3 specifies all of the above.
570 SUSv2 specified only the length modifiers
598 .SS Conversion specifiers
599 A character that specifies the type of conversion to be applied.
600 The conversion specifiers and their meanings are:
605 argument is converted to signed decimal notation.
606 The precision, if any, gives the minimum number of digits
607 that must appear; if the converted value requires fewer digits, it is
608 padded on the left with zeros.
609 The default precision is 1.
610 When 0 is printed with an explicit precision 0, the output is empty.
612 .BR o ", " u ", " x ", " X
615 argument is converted to unsigned octal
619 or unsigned hexadecimal
628 conversions; the letters
633 The precision, if any, gives the minimum number of digits
634 that must appear; if the converted value requires fewer digits, it is
635 padded on the left with zeros.
636 The default precision is 1.
637 When 0 is printed with an explicit precision 0, the output is empty.
642 argument is rounded and converted in the style
643 .RB [\-]d \&. ddd e \(+-dd
644 where there is one digit before the decimal-point character and the number
645 of digits after it is equal to the precision; if the precision is missing,
646 it is taken as 6; if the precision is zero, no decimal-point character
650 conversion uses the letter
654 to introduce the exponent.
655 The exponent always contains at least two
656 digits; if the value is zero, the exponent is 00.
661 argument is rounded and converted to decimal notation in the style
663 where the number of digits after the decimal-point character is equal to
664 the precision specification.
665 If the precision is missing, it is taken as
666 6; if the precision is explicitly zero, no decimal-point character appears.
667 If a decimal point appears, at least one digit appears before it.
669 (SUSv2 does not know about
671 and says that character string representations for infinity and NaN
672 may be made available.
673 SUSv3 adds a specification for
675 The C99 standard specifies "[\-]inf" or "[\-]infinity"
676 for infinity, and a string starting with "nan" for NaN, in the case of
678 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of
685 argument is converted in style
696 The precision specifies the number of significant digits.
697 If the precision is missing, 6 digits are given; if the precision is zero,
701 is used if the exponent from its conversion is less than \-4 or greater
702 than or equal to the precision.
703 Trailing zeros are removed from the
704 fractional part of the result; a decimal point appears only if it is
705 followed by at least one digit.
708 (C99; not in SUSv2, but added in SUSv3)
713 argument is converted to hexadecimal notation (using the letters abcdef)
715 .RB [\-] 0x h \&. hhhh p \(+-;
718 conversion the prefix
720 the letters ABCDEF, and the exponent separator
723 There is one hexadecimal digit before the decimal point,
724 and the number of digits after it is equal to the precision.
725 The default precision suffices for an exact representation of the value
726 if an exact representation in base 2 exists
727 and otherwise is sufficiently large to distinguish values of type
729 The digit before the decimal point is unspecified for nonnormalized
730 numbers, and nonzero but otherwise unspecified for normalized numbers.
735 modifier is present, the
737 argument is converted to an
738 .IR "unsigned char" ,
739 and the resulting character is written.
742 modifier is present, the
744 (wide character) argument is converted to a multibyte sequence by a call
747 function, with a conversion state starting in the initial state, and the
748 resulting multibyte string is written.
753 modifier is present: the
755 argument is expected to be a pointer to an array of character type (pointer
757 Characters from the array are written up to (but not
758 including) a terminating null byte (\(aq\\0\(aq);
759 if a precision is specified, no more than the number specified
761 If a precision is given, no null byte need be present;
762 if the precision is not specified, or is greater than the size of the
763 array, the array must contain a terminating null byte.
767 modifier is present: the
768 .I "const wchar_t\ *"
769 argument is expected to be a pointer to an array of wide characters.
770 Wide characters from the array are converted to multibyte characters
771 (each by a call to the
773 function, with a conversion state starting in the initial state before
774 the first wide character), up to and including a terminating null
776 The resulting multibyte characters are written up to
777 (but not including) the terminating null byte.
779 specified, no more bytes than the number specified are written, but
780 no partial multibyte characters are written.
781 Note that the precision
782 determines the number of
784 written, not the number of
787 .IR "screen positions" .
788 The array must contain a terminating null wide character, unless a
789 precision is given and it is so small that the number of bytes written
790 exceeds it before the end of the array is reached.
793 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
799 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
807 pointer argument is printed in hexadecimal (as if by
813 The number of characters written so far is stored into the integer
814 pointed to by the corresponding argument.
815 That argument shall be an
817 or variant whose size matches the (optionally)
818 supplied integer length modifier.
819 No argument is converted.
820 (This specifier is not supported by the bionic C library.)
821 The behavior is undefined if the conversion specification includes
822 any flags, a field width, or a precision.
825 (Glibc extension; supported by uClibc and musl.)
827 .IR strerror(errno) .
828 No argument is required.
831 A \(aq%\(aq is written.
832 No argument is converted.
833 The complete conversion
834 specification is \(aq%%\(aq.
836 Upon successful return, these functions return the number of characters
837 printed (excluding the null byte used to end output to strings).
843 do not write more than
845 bytes (including the terminating null byte (\(aq\e0\(aq)).
846 If the output was truncated due to this limit, then the return value
847 is the number of characters (excluding the terminating null byte)
848 which would have been written to the final string if enough space
850 Thus, a return value of
852 or more means that the output was truncated.
853 (See also below under NOTES.)
855 If an output error is encountered, a negative value is returned.
857 For an explanation of the terms used in this section, see
863 Interface Attribute Value
876 T} Thread safety MT-Safe locale
886 POSIX.1-2001, POSIX.1-2008, C89, C99.
890 POSIX.1-2001, POSIX.1-2008, C99.
896 functions were originally GNU extensions that were later standardized
899 Concerning the return value of
901 SUSv2 and C99 contradict each other: when
905 then SUSv2 stipulates an unspecified return value less than 1,
908 to be NULL in this case, and gives the return value (as always)
909 as the number of characters that would have been written in case
910 the output string has been large enough.
911 POSIX.1-2001 and later align their specification of
915 .\" Linux libc4 knows about the five C standard flags.
916 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
917 .\" and the conversions
918 .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
919 .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
920 .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
921 .\" where \fBF\fP is a synonym for \fBf\fP.
922 .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
923 .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
924 .\" (This is bad, and caused serious bugs later, when
925 .\" support for \fB%D\fP disappeared.)
926 .\" No locale-dependent radix character,
927 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
929 .\" Linux libc5 knows about the five C standard flags and the \(aq flag,
930 .\" locale, "%m$" and "*m$".
931 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
932 .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
933 .\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
934 .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
935 .\" but adds the conversion character
938 .\" .IR strerror(errno) .
940 .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
942 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
943 and conversion characters \fBa\fP and \fBA\fP.
945 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
946 and the flag character \fBI\fP.
948 Some programs imprudently rely on code such as the following
950 sprintf(buf, "%s some further text", buf);
954 However, the standards explicitly note that the results are undefined
955 if source and destination buffers overlap when calling
961 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
962 Depending on the version of
964 used, and the compiler options employed, calls such as the above will
966 produce the expected results.
968 The glibc implementation of the functions
972 conforms to the C99 standard, that is, behaves as described above,
973 since glibc version 2.1.
974 Until glibc 2.0.6, they would return \-1
975 when the output was truncated.
977 .\" UNIX V7 defines the three routines
981 .\" and has the flag \-, the width or precision *, the length modifier l,
982 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
983 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
984 .\" #, + and <space> and no longer mentions D,O,U,X.
989 .\" and warns not to use D,O,U,X.
990 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
991 .\" and the conversions n, p, E, G, X (with current meaning)
992 .\" and deprecates D,O,U.
993 .\" 4.4BSD introduces the functions
996 .\" .BR vsnprintf (),
997 .\" and the length modifier q.
998 .\" FreeBSD also has functions
1001 .\" .BR vasprintf (),
1002 .\" that allocate a buffer large enough for
1004 .\" In glibc there are functions
1008 .\" that print to a file descriptor instead of a stream.
1014 assume an arbitrarily long string, callers must be careful not to overflow
1015 the actual space; this is often impossible to assure.
1016 Note that the length
1017 of the strings produced is locale-dependent and difficult to predict.
1027 .\" Linux libc4.[45] does not have a
1028 .\" .BR snprintf (),
1029 .\" but provides a libbsd that contains an
1033 .\" that is, one that ignores the
1036 .\" Thus, the use of
1038 .\" with early libc4 leads to serious security problems.
1042 often indicates a bug, since
1044 may contain a % character.
1047 comes from untrusted user input, it may contain \fB%n\fP, causing the
1049 call to write to memory and creating a security hole.
1051 .\" Some floating-point conversions under early libc4
1052 .\" caused memory leaks.
1056 to five decimal places:
1062 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
1066 To print a date and time in the form "Sunday, July 3, 10:02",
1071 are pointers to strings:
1076 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
1077 weekday, month, day, hour, min);
1081 Many countries use the day-month-year order.
1082 Hence, an internationalized version must be able to print
1083 the arguments in an order specified by the format:
1088 fprintf(stdout, format,
1089 weekday, month, day, hour, min);
1095 depends on locale, and may permute the arguments.
1100 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
1104 one might obtain "Sonntag, 3. Juli, 10:02".
1106 To allocate a sufficiently large string and print into it
1107 (code correct for both glibc 2.0 and glibc 2.1):
1115 make_message(const char *fmt, ...)
1121 /* Determine required size */
1124 size = vsnprintf(p, size, fmt, ap);
1130 size++; /* For '\\0' */
1136 size = vsnprintf(p, size, fmt, ap);
1147 If truncation occurs in glibc versions prior to 2.0.6, this is treated as an
1148 error instead of being handled gracefully.