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 2014-07-08 "GNU" "Linux Programmer's Manual"
36 printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf,
37 vsnprintf \- formatted output conversion
41 .BI "int printf(const char *" format ", ...);"
43 .BI "int fprintf(FILE *" stream ", const char *" format ", ...);"
45 .BI "int sprintf(char *" str ", const char *" format ", ...);"
47 .BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);"
49 .B #include <stdarg.h>
51 .BI "int vprintf(const char *" format ", va_list " ap );
53 .BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap );
55 .BI "int vsprintf(char *" str ", const char *" format ", va_list " ap );
57 .BI "int vsnprintf(char *" str ", size_t " size ", const char *" format \
61 Feature Test Macro Requirements for glibc (see
62 .BR feature_test_macros (7)):
69 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
70 _POSIX_C_SOURCE\ >=\ 200112L;
79 family produce output according to a
88 the standard output stream;
92 write output to the given output
99 write to the character string
108 bytes (including the terminating null byte (\(aq\e0\(aq)) to
116 are equivalent to the functions
121 respectively, except that they are called with a
123 instead of a variable number of arguments.
124 These functions do not call the
127 Because they invoke the
131 is undefined after the call.
135 These eight functions write the output under the control of a
137 string that specifies how subsequent arguments (or arguments accessed via
138 the variable-length argument facilities of
140 are converted for output.
142 C99 and POSIX.1-2001 specify that the results are undefined if a call to
148 would cause copying to take place between objects that overlap
149 (e.g., if the target string array and one of the supplied input arguments
150 refer to the same buffer).
153 Upon successful return, these functions return the number of characters
154 printed (excluding the null byte used to end output to strings).
160 do not write more than
162 bytes (including the terminating null byte (\(aq\e0\(aq)).
163 If the output was truncated due to this limit, then the return value
164 is the number of characters (excluding the terminating null byte)
165 which would have been written to the final string if enough space
167 Thus, a return value of
169 or more means that the output was truncated.
170 (See also below under NOTES.)
172 If an output error is encountered, a negative value is returned.
173 .SS Format of the format string
174 The format string is a character string, beginning and ending
175 in its initial shift state, if any.
176 The format string is composed of zero or more directives: ordinary
179 which are copied unchanged to the output stream;
180 and conversion specifications, each of which results in fetching zero or
181 more subsequent arguments.
182 Each conversion specification is introduced by
186 .IR "conversion specifier" .
187 In between there may be (in this order) zero or more
194 .IR "length modifier" .
196 The arguments must correspond properly (after type promotion) with the
197 conversion specifier.
198 By default, the arguments are used in the order
199 given, where each \(aq*\(aq and each conversion specifier asks for the next
200 argument (and it is an error if insufficiently many arguments are given).
201 One can also specify explicitly which argument is taken,
202 at each place where an argument is required, by writing "%m$" instead
203 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
204 where the decimal integer m denotes
205 the position in the argument list of the desired argument, indexed starting
211 printf("%*d", width, num);
219 printf("%2$*1$d", width, num);
224 The second style allows repeated references to the
226 The C99 standard does not include the style using \(aq$\(aq,
227 which comes from the Single UNIX Specification.
229 \(aq$\(aq is used, it must be used throughout for all conversions taking an
230 argument and all width and precision arguments, but it may be mixed
231 with "%%" formats which do not consume an argument.
233 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
234 arguments 1 and 3 are specified, argument 2 must also be specified
235 somewhere in the format string.
237 For some numeric conversions a radix character ("decimal point") or
238 thousands' grouping character is used.
239 The actual character used
244 uses \(aq.\(aq as radix character, and does not have a grouping character.
249 printf("%\(aq.2f", 1234567.89);
253 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
254 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
255 .SS The flag characters
256 The character % is followed by zero or more of the following flags:
259 The value should be converted to an "alternate form".
262 conversions, the first character of the output string is made zero
263 (by prefixing a 0 if it was not zero already).
268 conversions, a nonzero result has the string "0x" (or "0X" for
270 conversions) prepended to it.
281 conversions, the result will always contain a decimal point, even if no
282 digits follow it (normally, a decimal point appears in the results of those
283 conversions only if a digit follows).
288 conversions, trailing zeros are not removed from the result as they would
290 For other conversions, the result is undefined.
293 The value should be zero padded.
310 conversions, the converted value is padded on the left with zeros rather
316 flags both appear, the
319 If a precision is given with a numeric conversion
330 For other conversions, the behavior is undefined.
333 The converted value is to be left adjusted on the field boundary.
334 (The default is right justification.)
335 The converted value is padded on the right with blanks, rather
336 than on the left with blanks or zeros.
344 (a space) A blank should be left before a positive number
345 (or empty string) produced by a signed conversion.
348 A sign (+ or \-) should always be placed before a number produced by a signed
350 By default a sign is used only for negative numbers.
353 overrides a space if both are used.
355 The five flag characters above are defined in the C99 standard.
356 The Single UNIX Specification specifies one further flag character.
359 For decimal conversion
367 the output is to be grouped with thousands' grouping characters
368 if the locale information indicates any.
369 Note that many versions of
371 cannot parse this option and will issue a warning.
373 include \fI%\(aqF\fP, but SUSv3 added it.)
375 glibc 2.2 adds one further flag character.
378 For decimal integer conversion
382 the output uses the locale's alternative output digits, if any.
383 For example, since glibc 2.2.3 this will give Arabic-Indic digits
384 in the Persian ("fa_IR") locale.
385 .\" outdigits keyword in locale file
387 An optional decimal digit string (with nonzero first digit) specifying
388 a minimum field width.
389 If the converted value has fewer characters
390 than the field width, it will be padded with spaces on the left
391 (or right, if the left-adjustment flag has been given).
392 Instead of a decimal digit string one may write "*" or "*m$"
393 (for some decimal integer \fIm\fP) to specify that the field width
394 is given in the next argument, or in the \fIm\fP-th argument, respectively,
395 which must be of type
397 A negative field width is taken as a \(aq\-\(aq flag followed by a
398 positive field width.
399 In no case does a nonexistent or small field width cause truncation of a
400 field; if the result of a conversion is wider than the field width, the
401 field is expanded to contain the conversion result.
403 An optional precision, in the form of a period (\(aq.\(aq) followed by an
404 optional decimal digit string.
405 Instead of a decimal digit string one may write "*" or "*m$"
406 (for some decimal integer m) to specify that the precision
407 is given in the next argument, or in the m-th argument, respectively,
408 which must be of type
410 If the precision is given as just \(aq.\(aq, the precision is taken to
412 A negative precision is taken as if the precision were omitted.
413 This gives the minimum number of digits to appear for
421 conversions, the number of digits to appear after the radix character for
429 conversions, the maximum number of significant digits for
433 conversions, or the maximum number of characters to be printed from a
439 .SS The length modifier
440 Here, "integer conversion" stands for
451 A following integer conversion corresponds to a
455 argument, or a following
457 conversion corresponds to a pointer to a
462 A following integer conversion corresponds to a
465 .I unsigned short int
466 argument, or a following
468 conversion corresponds to a pointer to a
473 (ell) A following integer conversion corresponds to a
477 argument, or a following
479 conversion corresponds to a pointer to a
481 argument, or a following
483 conversion corresponds to a
485 argument, or a following
487 conversion corresponds to a pointer to
493 A following integer conversion corresponds to a
496 .I unsigned long long int
497 argument, or a following
499 conversion corresponds to a pointer to a
514 conversion corresponds to a
517 (C99 allows %LF, but SUSv2 does not.)
520 .\" ("quad". 4.4BSD and Linux libc5 only.
522 This is a synonym for
526 A following integer conversion corresponds to an
530 argument, or a following
532 conversion corresponds to a pointer to an
537 A following integer conversion corresponds to a
541 argument, or a following
543 conversion corresponds to a pointer to a
548 .\" with this meaning.
552 A following integer conversion corresponds to a
554 argument, or a following
556 conversion corresponds to a pointer to a
560 SUSv3 specifies all of the above.
561 SUSv2 specified only the length modifiers
589 .SS The conversion specifier
590 A character that specifies the type of conversion to be applied.
591 The conversion specifiers and their meanings are:
596 argument is converted to signed decimal notation.
597 The precision, if any, gives the minimum number of digits
598 that must appear; if the converted value requires fewer digits, it is
599 padded on the left with zeros.
600 The default precision is 1.
601 When 0 is printed with an explicit precision 0, the output is empty.
603 .BR o ", " u ", " x ", " X
606 argument is converted to unsigned octal
610 or unsigned hexadecimal
619 conversions; the letters
624 The precision, if any, gives the minimum number of digits
625 that must appear; if the converted value requires fewer digits, it is
626 padded on the left with zeros.
627 The default precision is 1.
628 When 0 is printed with an explicit precision 0, the output is empty.
633 argument is rounded and converted in the style
634 .RB [\-]d \&. ddd e \(+-dd
635 where there is one digit before the decimal-point character and the number
636 of digits after it is equal to the precision; if the precision is missing,
637 it is taken as 6; if the precision is zero, no decimal-point character
641 conversion uses the letter
645 to introduce the exponent.
646 The exponent always contains at least two
647 digits; if the value is zero, the exponent is 00.
652 argument is rounded and converted to decimal notation in the style
654 where the number of digits after the decimal-point character is equal to
655 the precision specification.
656 If the precision is missing, it is taken as
657 6; if the precision is explicitly zero, no decimal-point character appears.
658 If a decimal point appears, at least one digit appears before it.
660 (SUSv2 does not know about
662 and says that character string representations for infinity and NaN
663 may be made available.
664 SUSv3 adds a specification for
666 The C99 standard specifies "[\-]inf" or "[\-]infinity"
667 for infinity, and a string starting with "nan" for NaN, in the case of
669 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN*" in the case of
676 argument is converted in style
687 The precision specifies the number of significant digits.
688 If the precision is missing, 6 digits are given; if the precision is zero,
692 is used if the exponent from its conversion is less than \-4 or greater
693 than or equal to the precision.
694 Trailing zeros are removed from the
695 fractional part of the result; a decimal point appears only if it is
696 followed by at least one digit.
699 (C99; not in SUSv2, but added in SUSv3)
704 argument is converted to hexadecimal notation (using the letters abcdef)
706 .RB [\-] 0x h \&. hhhh p \(+-;
709 conversion the prefix
711 the letters ABCDEF, and the exponent separator
714 There is one hexadecimal digit before the decimal point,
715 and the number of digits after it is equal to the precision.
716 The default precision suffices for an exact representation of the value
717 if an exact representation in base 2 exists
718 and otherwise is sufficiently large to distinguish values of type
720 The digit before the decimal point is unspecified for nonnormalized
721 numbers, and nonzero but otherwise unspecified for normalized numbers.
726 modifier is present, the
728 argument is converted to an
729 .IR "unsigned char" ,
730 and the resulting character is written.
733 modifier is present, the
735 (wide character) argument is converted to a multibyte sequence by a call
738 function, with a conversion state starting in the initial state, and the
739 resulting multibyte string is written.
744 modifier is present: The
746 argument is expected to be a pointer to an array of character type (pointer
748 Characters from the array are written up to (but not
749 including) a terminating null byte (\(aq\\0\(aq);
750 if a precision is specified, no more than the number specified
752 If a precision is given, no null byte need be present;
753 if the precision is not specified, or is greater than the size of the
754 array, the array must contain a terminating null byte.
758 modifier is present: The
759 .I "const wchar_t\ *"
760 argument is expected to be a pointer to an array of wide characters.
761 Wide characters from the array are converted to multibyte characters
762 (each by a call to the
764 function, with a conversion state starting in the initial state before
765 the first wide character), up to and including a terminating null
767 The resulting multibyte characters are written up to
768 (but not including) the terminating null byte.
770 specified, no more bytes than the number specified are written, but
771 no partial multibyte characters are written.
772 Note that the precision
773 determines the number of
775 written, not the number of
778 .IR "screen positions" .
779 The array must contain a terminating null wide character, unless a
780 precision is given and it is so small that the number of bytes written
781 exceeds it before the end of the array is reached.
784 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
790 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
798 pointer argument is printed in hexadecimal (as if by
804 The number of characters written so far is stored into the integer
805 pointed to by the corresponding argument.
806 That argument shall be an
808 or variant whose size matches the (optionally)
809 supplied integer length modifier.
810 No argument is converted.
811 The behavior is undefined if the conversion specification includes
812 any flags, a field width, or a precision.
817 .IR strerror(errno) .
818 No argument is required.
821 A \(aq%\(aq is written.
822 No argument is converted.
823 The complete conversion
824 specification is \(aq%%\(aq.
834 functions conform to C89 and C99.
839 functions conform to C99.
841 Concerning the return value of
843 SUSv2 and C99 contradict each other: when
847 then SUSv2 stipulates an unspecified return value less than 1,
850 to be NULL in this case, and gives the return value (as always)
851 as the number of characters that would have been written in case
852 the output string has been large enough.
853 SUSv3 and later align their specification of
857 .\" Linux libc4 knows about the five C standard flags.
858 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
859 .\" and the conversions
860 .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
861 .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
862 .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
863 .\" where \fBF\fP is a synonym for \fBf\fP.
864 .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
865 .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
866 .\" (This is bad, and caused serious bugs later, when
867 .\" support for \fB%D\fP disappeared.)
868 .\" No locale-dependent radix character,
869 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
871 .\" Linux libc5 knows about the five C standard flags and the \(aq flag,
872 .\" locale, "%m$" and "*m$".
873 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
874 .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
875 .\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
876 .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
877 .\" but adds the conversion character
880 .\" .IR strerror(errno) .
882 .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
884 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
885 and conversion characters \fBa\fP and \fBA\fP.
887 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
888 and the flag character \fBI\fP.
890 Some programs imprudently rely on code such as the following
892 sprintf(buf, "%s some further text", buf);
896 However, the standards explicitly note that the results are undefined
897 if source and destination buffers overlap when calling
903 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
904 Depending on the version of
906 used, and the compiler options employed, calls such as the above will
908 produce the expected results.
910 The glibc implementation of the functions
914 conforms to the C99 standard, that is, behaves as described above,
915 since glibc version 2.1.
916 Until glibc 2.0.6, they would return \-1
917 when the output was truncated.
919 .\" UNIX V7 defines the three routines
923 .\" and has the flag \-, the width or precision *, the length modifier l,
924 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
925 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
926 .\" #, + and <space> and no longer mentions D,O,U,X.
931 .\" and warns not to use D,O,U,X.
932 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
933 .\" and the conversions n, p, E, G, X (with current meaning)
934 .\" and deprecates D,O,U.
935 .\" 4.4BSD introduces the functions
938 .\" .BR vsnprintf (),
939 .\" and the length modifier q.
940 .\" FreeBSD also has functions
943 .\" .BR vasprintf (),
944 .\" that allocate a buffer large enough for
946 .\" In glibc there are functions
950 .\" that print to a file descriptor instead of a stream.
956 assume an arbitrarily long string, callers must be careful not to overflow
957 the actual space; this is often impossible to assure.
959 of the strings produced is locale-dependent and difficult to predict.
969 .\" Linux libc4.[45] does not have a
971 .\" but provides a libbsd that contains an
975 .\" that is, one that ignores the
980 .\" with early libc4 leads to serious security problems.
984 often indicates a bug, since
986 may contain a % character.
989 comes from untrusted user input, it may contain \fB%n\fP, causing the
991 call to write to memory and creating a security hole.
993 .\" Some floating-point conversions under early libc4
994 .\" caused memory leaks.
998 to five decimal places:
1004 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
1008 To print a date and time in the form "Sunday, July 3, 10:02",
1013 are pointers to strings:
1018 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
1019 weekday, month, day, hour, min);
1023 Many countries use the day-month-year order.
1024 Hence, an internationalized version must be able to print
1025 the arguments in an order specified by the format:
1030 fprintf(stdout, format,
1031 weekday, month, day, hour, min);
1037 depends on locale, and may permute the arguments.
1042 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
1046 one might obtain "Sonntag, 3. Juli, 10:02".
1048 To allocate a sufficiently large string and print into it
1049 (code correct for both glibc 2.0 and glibc 2.1):
1057 make_message(const char *fmt, ...)
1060 int size = 100; /* Guess we need no more than 100 bytes */
1070 /* Try to print in the allocated space */
1073 n = vsnprintf(p, size, fmt, ap);
1076 /* Check error code */
1083 /* If that worked, return the string */
1088 /* Else try again with more space */
1090 size = n + 1; /* Precisely what is needed */
1093 np = realloc(p, size);
1104 If truncation occurs in glibc versions prior to 2.0.6, this is treated as an
1105 error instead of being handled gracefully.