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 2015-04-19 "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 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
74 _POSIX_C_SOURCE\ >=\ 200112L;
86 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
96 family produce output according to a
105 the standard output stream;
109 write output to the given output
116 write to the character string
123 except that it outputs to a file descriptor,
135 bytes (including the terminating null byte (\(aq\e0\(aq)) to
144 are equivalent to the functions
150 respectively, except that they are called with a
152 instead of a variable number of arguments.
153 These functions do not call the
156 Because they invoke the
160 is undefined after the call.
164 All of these functions write the output under the control of a
166 string that specifies how subsequent arguments (or arguments accessed via
167 the variable-length argument facilities of
169 are converted for output.
171 C99 and POSIX.1-2001 specify that the results are undefined if a call to
177 would cause copying to take place between objects that overlap
178 (e.g., if the target string array and one of the supplied input arguments
179 refer to the same buffer).
181 .SS Format of the format string
182 The format string is a character string, beginning and ending
183 in its initial shift state, if any.
184 The format string is composed of zero or more directives: ordinary
187 which are copied unchanged to the output stream;
188 and conversion specifications, each of which results in fetching zero or
189 more subsequent arguments.
190 Each conversion specification is introduced by
194 .IR "conversion specifier" .
195 In between there may be (in this order) zero or more
202 .IR "length modifier" .
204 The arguments must correspond properly (after type promotion) with the
205 conversion specifier.
206 By default, the arguments are used in the order
207 given, where each \(aq*\(aq and each conversion specifier asks for the next
208 argument (and it is an error if insufficiently many arguments are given).
209 One can also specify explicitly which argument is taken,
210 at each place where an argument is required, by writing "%m$" instead
211 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
212 where the decimal integer \fIm\fP denotes
213 the position in the argument list of the desired argument, indexed starting
219 printf("%*d", width, num);
227 printf("%2$*1$d", width, num);
232 The second style allows repeated references to the
234 The C99 standard does not include the style using \(aq$\(aq,
235 which comes from the Single UNIX Specification.
237 \(aq$\(aq is used, it must be used throughout for all conversions taking an
238 argument and all width and precision arguments, but it may be mixed
239 with "%%" formats which do not consume an argument.
241 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
242 arguments 1 and 3 are specified, argument 2 must also be specified
243 somewhere in the format string.
245 For some numeric conversions a radix character ("decimal point") or
246 thousands' grouping character is used.
247 The actual character used
252 uses \(aq.\(aq as radix character, and does not have a grouping character.
257 printf("%\(aq.2f", 1234567.89);
261 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
262 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
264 The character % is followed by zero or more of the following flags:
267 The value should be converted to an "alternate form".
270 conversions, the first character of the output string is made zero
271 (by prefixing a 0 if it was not zero already).
276 conversions, a nonzero result has the string "0x" (or "0X" for
278 conversions) prepended to it.
289 conversions, the result will always contain a decimal point, even if no
290 digits follow it (normally, a decimal point appears in the results of those
291 conversions only if a digit follows).
296 conversions, trailing zeros are not removed from the result as they would
298 For other conversions, the result is undefined.
301 The value should be zero padded.
318 conversions, the converted value is padded on the left with zeros rather
324 flags both appear, the
327 If a precision is given with a numeric conversion
338 For other conversions, the behavior is undefined.
341 The converted value is to be left adjusted on the field boundary.
342 (The default is right justification.)
343 The converted value is padded on the right with blanks, rather
344 than on the left with blanks or zeros.
352 (a space) A blank should be left before a positive number
353 (or empty string) produced by a signed conversion.
356 A sign (+ or \-) should always be placed before a number produced by a signed
358 By default, a sign is used only for negative numbers.
361 overrides a space if both are used.
363 The five flag characters above are defined in the C99 standard.
364 The Single UNIX Specification specifies one further flag character.
367 For decimal conversion
375 the output is to be grouped with thousands' grouping characters
376 if the locale information indicates any.
377 Note that many versions of
379 cannot parse this option and will issue a warning.
381 include \fI%\(aqF\fP, but SUSv3 added it.)
383 glibc 2.2 adds one further flag character.
386 For decimal integer conversion
390 the output uses the locale's alternative output digits, if any.
391 For example, since glibc 2.2.3 this will give Arabic-Indic digits
392 in the Persian ("fa_IR") locale.
393 .\" outdigits keyword in locale file
395 An optional decimal digit string (with nonzero first digit) specifying
396 a minimum field width.
397 If the converted value has fewer characters
398 than the field width, it will be padded with spaces on the left
399 (or right, if the left-adjustment flag has been given).
400 Instead of a decimal digit string one may write "*" or "*m$"
401 (for some decimal integer \fIm\fP) to specify that the field width
402 is given in the next argument, or in the \fIm\fP-th argument, respectively,
403 which must be of type
405 A negative field width is taken as a \(aq\-\(aq flag followed by a
406 positive field width.
407 In no case does a nonexistent or small field width cause truncation of a
408 field; if the result of a conversion is wider than the field width, the
409 field is expanded to contain the conversion result.
411 An optional precision, in the form of a period (\(aq.\(aq) followed by an
412 optional decimal digit string.
413 Instead of a decimal digit string one may write "*" or "*m$"
414 (for some decimal integer \fIm\fP) to specify that the precision
415 is given in the next argument, or in the \fIm\fP-th argument, respectively,
416 which must be of type
418 If the precision is given as just \(aq.\(aq, the precision is taken to
420 A negative precision is taken as if the precision were omitted.
421 This gives the minimum number of digits to appear for
429 conversions, the number of digits to appear after the radix character for
437 conversions, the maximum number of significant digits for
441 conversions, or the maximum number of characters to be printed from a
448 Here, "integer conversion" stands for
459 A following integer conversion corresponds to a
463 argument, or a following
465 conversion corresponds to a pointer to a
470 A following integer conversion corresponds to a
473 .I unsigned short int
474 argument, or a following
476 conversion corresponds to a pointer to a
481 (ell) A following integer conversion corresponds to a
485 argument, or a following
487 conversion corresponds to a pointer to a
489 argument, or a following
491 conversion corresponds to a
493 argument, or a following
495 conversion corresponds to a pointer to
501 A following integer conversion corresponds to a
504 .I unsigned long long int
505 argument, or a following
507 conversion corresponds to a pointer to a
522 conversion corresponds to a
525 (C99 allows %LF, but SUSv2 does not.)
528 .\" ("quad". 4.4BSD and Linux libc5 only.
530 This is a synonym for
534 A following integer conversion corresponds to an
538 argument, or a following
540 conversion corresponds to a pointer to an
545 A following integer conversion corresponds to a
549 argument, or a following
551 conversion corresponds to a pointer to a
556 .\" with this meaning.
560 A following integer conversion corresponds to a
562 argument, or a following
564 conversion corresponds to a pointer to a
568 SUSv3 specifies all of the above.
569 SUSv2 specified only the length modifiers
597 .SS Conversion specifiers
598 A character that specifies the type of conversion to be applied.
599 The conversion specifiers and their meanings are:
604 argument is converted to signed decimal notation.
605 The precision, if any, gives the minimum number of digits
606 that must appear; if the converted value requires fewer digits, it is
607 padded on the left with zeros.
608 The default precision is 1.
609 When 0 is printed with an explicit precision 0, the output is empty.
611 .BR o ", " u ", " x ", " X
614 argument is converted to unsigned octal
618 or unsigned hexadecimal
627 conversions; the letters
632 The precision, if any, gives the minimum number of digits
633 that must appear; if the converted value requires fewer digits, it is
634 padded on the left with zeros.
635 The default precision is 1.
636 When 0 is printed with an explicit precision 0, the output is empty.
641 argument is rounded and converted in the style
642 .RB [\-]d \&. ddd e \(+-dd
643 where there is one digit before the decimal-point character and the number
644 of digits after it is equal to the precision; if the precision is missing,
645 it is taken as 6; if the precision is zero, no decimal-point character
649 conversion uses the letter
653 to introduce the exponent.
654 The exponent always contains at least two
655 digits; if the value is zero, the exponent is 00.
660 argument is rounded and converted to decimal notation in the style
662 where the number of digits after the decimal-point character is equal to
663 the precision specification.
664 If the precision is missing, it is taken as
665 6; if the precision is explicitly zero, no decimal-point character appears.
666 If a decimal point appears, at least one digit appears before it.
668 (SUSv2 does not know about
670 and says that character string representations for infinity and NaN
671 may be made available.
672 SUSv3 adds a specification for
674 The C99 standard specifies "[\-]inf" or "[\-]infinity"
675 for infinity, and a string starting with "nan" for NaN, in the case of
677 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN*" in the case of
684 argument is converted in style
695 The precision specifies the number of significant digits.
696 If the precision is missing, 6 digits are given; if the precision is zero,
700 is used if the exponent from its conversion is less than \-4 or greater
701 than or equal to the precision.
702 Trailing zeros are removed from the
703 fractional part of the result; a decimal point appears only if it is
704 followed by at least one digit.
707 (C99; not in SUSv2, but added in SUSv3)
712 argument is converted to hexadecimal notation (using the letters abcdef)
714 .RB [\-] 0x h \&. hhhh p \(+-;
717 conversion the prefix
719 the letters ABCDEF, and the exponent separator
722 There is one hexadecimal digit before the decimal point,
723 and the number of digits after it is equal to the precision.
724 The default precision suffices for an exact representation of the value
725 if an exact representation in base 2 exists
726 and otherwise is sufficiently large to distinguish values of type
728 The digit before the decimal point is unspecified for nonnormalized
729 numbers, and nonzero but otherwise unspecified for normalized numbers.
734 modifier is present, the
736 argument is converted to an
737 .IR "unsigned char" ,
738 and the resulting character is written.
741 modifier is present, the
743 (wide character) argument is converted to a multibyte sequence by a call
746 function, with a conversion state starting in the initial state, and the
747 resulting multibyte string is written.
752 modifier is present: The
754 argument is expected to be a pointer to an array of character type (pointer
756 Characters from the array are written up to (but not
757 including) a terminating null byte (\(aq\\0\(aq);
758 if a precision is specified, no more than the number specified
760 If a precision is given, no null byte need be present;
761 if the precision is not specified, or is greater than the size of the
762 array, the array must contain a terminating null byte.
766 modifier is present: The
767 .I "const wchar_t\ *"
768 argument is expected to be a pointer to an array of wide characters.
769 Wide characters from the array are converted to multibyte characters
770 (each by a call to the
772 function, with a conversion state starting in the initial state before
773 the first wide character), up to and including a terminating null
775 The resulting multibyte characters are written up to
776 (but not including) the terminating null byte.
778 specified, no more bytes than the number specified are written, but
779 no partial multibyte characters are written.
780 Note that the precision
781 determines the number of
783 written, not the number of
786 .IR "screen positions" .
787 The array must contain a terminating null wide character, unless a
788 precision is given and it is so small that the number of bytes written
789 exceeds it before the end of the array is reached.
792 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
798 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
806 pointer argument is printed in hexadecimal (as if by
812 The number of characters written so far is stored into the integer
813 pointed to by the corresponding argument.
814 That argument shall be an
816 or variant whose size matches the (optionally)
817 supplied integer length modifier.
818 No argument is converted.
819 The behavior is undefined if the conversion specification includes
820 any flags, a field width, or a precision.
825 .IR strerror(errno) .
826 No argument is required.
829 A \(aq%\(aq is written.
830 No argument is converted.
831 The complete conversion
832 specification is \(aq%%\(aq.
834 Upon successful return, these functions return the number of characters
835 printed (excluding the null byte used to end output to strings).
841 do not write more than
843 bytes (including the terminating null byte (\(aq\e0\(aq)).
844 If the output was truncated due to this limit, then the return value
845 is the number of characters (excluding the terminating null byte)
846 which would have been written to the final string if enough space
848 Thus, a return value of
850 or more means that the output was truncated.
851 (See also below under NOTES.)
853 If an output error is encountered, a negative value is returned.
855 For an explanation of the terms used in this section, see
861 Interface Attribute Value
874 T} Thread safety MT-Safe locale
886 functions conform to C89 and C99.
892 functions conform to C99.
898 functions were originally GNU extensions that were later standardized
901 Concerning the return value of
903 SUSv2 and C99 contradict each other: when
907 then SUSv2 stipulates an unspecified return value less than 1,
910 to be NULL in this case, and gives the return value (as always)
911 as the number of characters that would have been written in case
912 the output string has been large enough.
913 SUSv3 and later align their specification of
917 .\" Linux libc4 knows about the five C standard flags.
918 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
919 .\" and the conversions
920 .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
921 .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
922 .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
923 .\" where \fBF\fP is a synonym for \fBf\fP.
924 .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
925 .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
926 .\" (This is bad, and caused serious bugs later, when
927 .\" support for \fB%D\fP disappeared.)
928 .\" No locale-dependent radix character,
929 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
931 .\" Linux libc5 knows about the five C standard flags and the \(aq flag,
932 .\" locale, "%m$" and "*m$".
933 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
934 .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
935 .\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
936 .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
937 .\" but adds the conversion character
940 .\" .IR strerror(errno) .
942 .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
944 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
945 and conversion characters \fBa\fP and \fBA\fP.
947 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
948 and the flag character \fBI\fP.
950 Some programs imprudently rely on code such as the following
952 sprintf(buf, "%s some further text", buf);
956 However, the standards explicitly note that the results are undefined
957 if source and destination buffers overlap when calling
963 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
964 Depending on the version of
966 used, and the compiler options employed, calls such as the above will
968 produce the expected results.
970 The glibc implementation of the functions
974 conforms to the C99 standard, that is, behaves as described above,
975 since glibc version 2.1.
976 Until glibc 2.0.6, they would return \-1
977 when the output was truncated.
979 .\" UNIX V7 defines the three routines
983 .\" and has the flag \-, the width or precision *, the length modifier l,
984 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
985 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
986 .\" #, + and <space> and no longer mentions D,O,U,X.
991 .\" and warns not to use D,O,U,X.
992 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
993 .\" and the conversions n, p, E, G, X (with current meaning)
994 .\" and deprecates D,O,U.
995 .\" 4.4BSD introduces the functions
998 .\" .BR vsnprintf (),
999 .\" and the length modifier q.
1000 .\" FreeBSD also has functions
1003 .\" .BR vasprintf (),
1004 .\" that allocate a buffer large enough for
1006 .\" In glibc there are functions
1010 .\" that print to a file descriptor instead of a stream.
1016 assume an arbitrarily long string, callers must be careful not to overflow
1017 the actual space; this is often impossible to assure.
1018 Note that the length
1019 of the strings produced is locale-dependent and difficult to predict.
1029 .\" Linux libc4.[45] does not have a
1030 .\" .BR snprintf (),
1031 .\" but provides a libbsd that contains an
1035 .\" that is, one that ignores the
1038 .\" Thus, the use of
1040 .\" with early libc4 leads to serious security problems.
1044 often indicates a bug, since
1046 may contain a % character.
1049 comes from untrusted user input, it may contain \fB%n\fP, causing the
1051 call to write to memory and creating a security hole.
1053 .\" Some floating-point conversions under early libc4
1054 .\" caused memory leaks.
1058 to five decimal places:
1064 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
1068 To print a date and time in the form "Sunday, July 3, 10:02",
1073 are pointers to strings:
1078 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
1079 weekday, month, day, hour, min);
1083 Many countries use the day-month-year order.
1084 Hence, an internationalized version must be able to print
1085 the arguments in an order specified by the format:
1090 fprintf(stdout, format,
1091 weekday, month, day, hour, min);
1097 depends on locale, and may permute the arguments.
1102 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
1106 one might obtain "Sonntag, 3. Juli, 10:02".
1108 To allocate a sufficiently large string and print into it
1109 (code correct for both glibc 2.0 and glibc 2.1):
1117 make_message(const char *fmt, ...)
1123 /* Determine required size */
1126 size = vsnprintf(p, size, fmt, ap);
1132 size++; /* For '\\0' */
1138 size = vsnprintf(p, size, fmt, ap);
1149 If truncation occurs in glibc versions prior to 2.0.6, this is treated as an
1150 error instead of being handled gracefully.