1 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
3 .\" This is free documentation; you can redistribute it and/or
4 .\" modify it under the terms of the GNU General Public License as
5 .\" published by the Free Software Foundation; either version 2 of
6 .\" the License, or (at your option) any later version.
8 .\" The GNU General Public License's references to "object code"
9 .\" and "executables" are to be interpreted as the output of any
10 .\" document formatting or typesetting system, including
11 .\" intermediate and printed output.
13 .\" This manual is distributed in the hope that it will be useful,
14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 .\" GNU General Public License for more details.
18 .\" You should have received a copy of the GNU General Public
19 .\" License along with this manual; if not, write to the Free
20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
24 .\" Earlier versions of this page influenced the present text.
25 .\" It was derived from a Berkeley page with version
26 .\" @(#)printf.3 6.14 (Berkeley) 7/30/91
27 .\" converted for Linux by faith@cs.unc.edu, updated by
28 .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
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 2010-09-20 "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 trailing 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 (not including the
155 trailing \(aq\e0\(aq used to end output to strings).
161 do not write more than
163 bytes (including the trailing \(aq\e0\(aq).
164 If the output was truncated due to this limit then the return value
165 is the number of characters (not including the trailing \(aq\e0\(aq)
166 which would have been written to the final string if enough space
168 Thus, a return value of
170 or more means that the output was truncated.
171 (See also below under NOTES.)
173 If an output error is encountered, a negative value is returned.
174 .SS "Format of the format string"
175 The format string is a character string, beginning and ending
176 in its initial shift state, if any.
177 The format string is composed of zero or more directives: ordinary
180 which are copied unchanged to the output stream;
181 and conversion specifications, each of which results in fetching zero or
182 more subsequent arguments.
183 Each conversion specification is introduced by
187 .IR "conversion specifier" .
188 In between there may be (in this order) zero or more
195 .IR "length modifier" .
197 The arguments must correspond properly (after type promotion) with the
198 conversion specifier.
199 By default, the arguments are used in the order
200 given, where each \(aq*\(aq and each conversion specifier asks for the next
201 argument (and it is an error if insufficiently many arguments are given).
202 One can also specify explicitly which argument is taken,
203 at each place where an argument is required, by writing "%m$" instead
204 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
205 where the decimal integer m denotes
206 the position in the argument list of the desired argument, indexed starting
212 printf("%*d", width, num);
220 printf("%2$*1$d", width, num);
225 The second style allows repeated references to the
227 The C99 standard does not include the style using \(aq$\(aq,
228 which comes from the Single UNIX Specification.
230 \(aq$\(aq is used, it must be used throughout for all conversions taking an
231 argument and all width and precision arguments, but it may be mixed
232 with "%%" formats which do not consume an argument.
234 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
235 arguments 1 and 3 are specified, argument 2 must also be specified
236 somewhere in the format string.
238 For some numeric conversions a radix character ("decimal point") or
239 thousands' grouping character is used.
240 The actual character used
245 uses \(aq.\(aq as radix character, and does not have a grouping character.
250 printf("%\(aq.2f", 1234567.89);
254 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
255 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
256 .SS "The flag characters"
257 The character % is followed by zero or more of the following flags:
260 The value should be converted to an "alternate form".
263 conversions, the first character of the output string is made zero
264 (by prefixing a 0 if it was not zero already).
269 conversions, a nonzero result has the string "0x" (or "0X" for
271 conversions) prepended to it.
282 conversions, the result will always contain a decimal point, even if no
283 digits follow it (normally, a decimal point appears in the results of those
284 conversions only if a digit follows).
289 conversions, trailing zeros are not removed from the result as they would
291 For other conversions, the result is undefined.
294 The value should be zero padded.
311 conversions, the converted value is padded on the left with zeros rather
317 flags both appear, the
320 If a precision is given with a numeric conversion
331 For other conversions, the behavior is undefined.
334 The converted value is to be left adjusted on the field boundary.
335 (The default is right justification.)
338 conversions, the converted value is padded on the right with blanks, rather
339 than on the left with blanks or zeros.
347 (a space) A blank should be left before a positive number
348 (or empty string) produced by a signed conversion.
351 A sign (+ or \-) should always be placed before a number produced by a signed
353 By default a sign is used only for negative numbers.
356 overrides a space if both are used.
358 The five flag characters above are defined in the C standard.
359 The SUSv2 specifies one further flag character.
362 For decimal conversion
370 the output is to be grouped with thousands' grouping characters
371 if the locale information indicates any.
372 Note that many versions of
374 cannot parse this option and will issue a warning.
376 include \fI%\(aqF\fP.
378 glibc 2.2 adds one further flag character.
381 For decimal integer conversion
385 the output uses the locale's alternative output digits, if any.
386 For example, since glibc 2.2.3 this will give Arabic-Indic digits
387 in the Persian ("fa_IR") locale.
388 .\" outdigits keyword in locale file
389 .SS "The field width"
390 An optional decimal digit string (with nonzero first digit) specifying
391 a minimum field width.
392 If the converted value has fewer characters
393 than the field width, it will be padded with spaces on the left
394 (or right, if the left-adjustment flag has been given).
395 Instead of a decimal digit string one may write "*" or "*m$"
396 (for some decimal integer \fIm\fP) to specify that the field width
397 is given in the next argument, or in the \fIm\fP-th argument, respectively,
398 which must be of type
400 A negative field width is taken as a \(aq\-\(aq flag followed by a
401 positive field width.
402 In no case does a nonexistent or small field width cause truncation of a
403 field; if the result of a conversion is wider than the field width, the
404 field is expanded to contain the conversion result.
406 An optional precision, in the form of a period (\(aq.\(aq) followed by an
407 optional decimal digit string.
408 Instead of a decimal digit string one may write "*" or "*m$"
409 (for some decimal integer m) to specify that the precision
410 is given in the next argument, or in the m-th argument, respectively,
411 which must be of type
413 If the precision is given as just \(aq.\(aq, or the precision is negative,
414 the precision is taken to be zero.
415 This gives the minimum number of digits to appear for
423 conversions, the number of digits to appear after the radix character for
431 conversions, the maximum number of significant digits for
435 conversions, or the maximum number of characters to be printed from a
441 .SS "The length modifier"
442 Here, "integer conversion" stands for
453 A following integer conversion corresponds to a
457 argument, or a following
459 conversion corresponds to a pointer to a
464 A following integer conversion corresponds to a
467 .I unsigned short int
468 argument, or a following
470 conversion corresponds to a pointer to a
475 (ell) A following integer conversion corresponds to a
479 argument, or a following
481 conversion corresponds to a pointer to a
483 argument, or a following
485 conversion corresponds to a
487 argument, or a following
489 conversion corresponds to a pointer to
495 A following integer conversion corresponds to a
498 .I unsigned long long int
499 argument, or a following
501 conversion corresponds to a pointer to a
516 conversion corresponds to a
519 (C99 allows %LF, but SUSv2 does not.)
522 ("quad". 4.4BSD and Linux libc5 only.
524 This is a synonym for
528 A following integer conversion corresponds to an
535 A following integer conversion corresponds to a
546 A following integer conversion corresponds to a
550 The SUSv2 only knows about the length modifiers
578 .SS "The conversion specifier"
579 A character that specifies the type of conversion to be applied.
580 The conversion specifiers and their meanings are:
585 argument is converted to signed decimal notation.
586 The precision, if any, gives the minimum number of digits
587 that must appear; if the converted value requires fewer digits, it is
588 padded on the left with zeros.
589 The default precision is 1.
590 When 0 is printed with an explicit precision 0, the output is empty.
592 .BR o ", " u ", " x ", " X
595 argument is converted to unsigned octal
599 or unsigned hexadecimal
608 conversions; the letters
613 The precision, if any, gives the minimum number of digits
614 that must appear; if the converted value requires fewer digits, it is
615 padded on the left with zeros.
616 The default precision is 1.
617 When 0 is printed with an explicit precision 0, the output is empty.
622 argument is rounded and converted in the style
623 .if \w'\*(Pm'=0 .ds Pm \(+-
624 .RB [\-]d \&. ddd e \\*(Pmdd
625 where there is one digit before the decimal-point character and the number
626 of digits after it is equal to the precision; if the precision is missing,
627 it is taken as 6; if the precision is zero, no decimal-point character
631 conversion uses the letter
635 to introduce the exponent.
636 The exponent always contains at least two
637 digits; if the value is zero, the exponent is 00.
642 argument is rounded and converted to decimal notation in the style
644 where the number of digits after the decimal-point character is equal to
645 the precision specification.
646 If the precision is missing, it is taken as
647 6; if the precision is explicitly zero, no decimal-point character appears.
648 If a decimal point appears, at least one digit appears before it.
650 (The SUSv2 does not know about
652 and says that character string representations for infinity and NaN
653 may be made available.
654 The C99 standard specifies "[\-]inf" or "[\-]infinity"
655 for infinity, and a string starting with "nan" for NaN, in the case of
657 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN*" in the case of
664 argument is converted in style
675 The precision specifies the number of significant digits.
676 If the precision is missing, 6 digits are given; if the precision is zero,
680 is used if the exponent from its conversion is less than \-4 or greater
681 than or equal to the precision.
682 Trailing zeros are removed from the
683 fractional part of the result; a decimal point appears only if it is
684 followed by at least one digit.
687 (C99; not in SUSv2) For
691 argument is converted to hexadecimal notation (using the letters abcdef)
693 .RB [\-] 0x h \&. hhhh p \\*(Pmd;
696 conversion the prefix
698 the letters ABCDEF, and the exponent separator
701 There is one hexadecimal digit before the decimal point,
702 and the number of digits after it is equal to the precision.
703 The default precision suffices for an exact representation of the value
704 if an exact representation in base 2 exists
705 and otherwise is sufficiently large to distinguish values of type
707 The digit before the decimal point is unspecified for nonnormalized
708 numbers, and nonzero but otherwise unspecified for normalized numbers.
713 modifier is present, the
715 argument is converted to an
716 .IR "unsigned char" ,
717 and the resulting character is written.
720 modifier is present, the
722 (wide character) argument is converted to a multibyte sequence by a call
725 function, with a conversion state starting in the initial state, and the
726 resulting multibyte string is written.
731 modifier is present: The
733 argument is expected to be a pointer to an array of character type (pointer
735 Characters from the array are written up to (but not
736 including) a terminating null byte (\(aq\\0\(aq);
737 if a precision is specified, no more than the number specified
739 If a precision is given, no null byte need be present;
740 if the precision is not specified, or is greater than the size of the
741 array, the array must contain a terminating null byte.
745 modifier is present: The
747 argument is expected to be a pointer to an array of wide characters.
748 Wide characters from the array are converted to multibyte characters
749 (each by a call to the
751 function, with a conversion state starting in the initial state before
752 the first wide character), up to and including a terminating null
754 The resulting multibyte characters are written up to
755 (but not including) the terminating null byte.
757 specified, no more bytes than the number specified are written, but
758 no partial multibyte characters are written.
759 Note that the precision
760 determines the number of
762 written, not the number of
765 .IR "screen positions" .
766 The array must contain a terminating null wide character, unless a
767 precision is given and it is so small that the number of bytes written
768 exceeds it before the end of the array is reached.
771 (Not in C99, but in SUSv2.)
777 (Not in C99, but in SUSv2.)
785 pointer argument is printed in hexadecimal (as if by
791 The number of characters written so far is stored into the integer
794 (or variant) pointer argument.
795 No argument is converted.
800 .IR strerror(errno) .
801 No argument is required.
804 A \(aq%\(aq is written.
805 No argument is converted.
806 The complete conversion
807 specification is \(aq%%\(aq.
817 functions conform to C89 and C99.
822 functions conform to C99.
824 Concerning the return value of
826 SUSv2 and C99 contradict each other: when
830 then SUSv2 stipulates an unspecified return value less than 1,
833 to be NULL in this case, and gives the return value (as always)
834 as the number of characters that would have been written in case
835 the output string has been large enough.
837 Linux libc4 knows about the five C standard flags.
838 It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
840 \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
841 \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
842 \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
843 where \fBF\fP is a synonym for \fBf\fP.
844 Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
845 for \fBld\fP, \fBlo\fP, and \fBlu\fP.
846 (This is bad, and caused serious bugs later, when
847 support for \fB%D\fP disappeared.)
848 No locale-dependent radix character,
849 no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
851 Linux libc5 knows about the five C standard flags and the \(aq flag,
852 locale, "%m$" and "*m$".
853 It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
854 \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
855 both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
856 It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
857 but adds the conversion character
860 .IR strerror(errno) .
862 glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
864 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
865 and conversion characters \fBa\fP and \fBA\fP.
867 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
868 and the flag character \fBI\fP.
870 Some programs imprudently rely on code such as the following
872 sprintf(buf, "%s some further text", buf);
876 However, the standards explicitly note that the results are undefined
877 if source and destination buffers overlap when calling
883 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
884 Depending on the version of
886 used, and the compiler options employed, calls such as the above will
888 produce the expected results.
890 The glibc implementation of the functions
894 conforms to the C99 standard, that is, behaves as described above,
895 since glibc version 2.1.
896 Until glibc 2.0.6 they would return \-1
897 when the output was truncated.
899 .\" UNIX V7 defines the three routines
903 .\" and has the flag \-, the width or precision *, the length modifier l,
904 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
905 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
906 .\" #, + and <space> and no longer mentions D,O,U,X.
911 .\" and warns not to use D,O,U,X.
912 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
913 .\" and the conversions n, p, E, G, X (with current meaning)
914 .\" and deprecates D,O,U.
915 .\" 4.4BSD introduces the functions
918 .\" .BR vsnprintf (),
919 .\" and the length modifier q.
920 .\" FreeBSD also has functions
923 .\" .BR vasprintf (),
924 .\" that allocate a buffer large enough for
926 .\" In glibc there are functions
930 .\" that print to a file descriptor instead of a stream.
936 assume an arbitrarily long string, callers must be careful not to overflow
937 the actual space; this is often impossible to assure.
939 of the strings produced is locale-dependent and difficult to predict.
949 Linux libc4.[45] does not have a
951 but provides a libbsd that contains an
955 that is, one that ignores the
960 with early libc4 leads to serious security problems.
964 often indicates a bug, since
966 may contain a % character.
969 comes from untrusted user input, it may contain \fB%n\fP, causing the
971 call to write to memory and creating a security hole.
973 .\" Some floating-point conversions under early libc4
974 .\" caused memory leaks.
976 .if \w'\*(Pi'=0 .ds Pi pi
977 To print \*(Pi to five decimal places:
983 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
987 To print a date and time in the form "Sunday, July 3, 10:02",
992 are pointers to strings:
997 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
998 weekday, month, day, hour, min);
1002 Many countries use the day-month-year order.
1003 Hence, an internationalized version must be able to print
1004 the arguments in an order specified by the format:
1009 fprintf(stdout, format,
1010 weekday, month, day, hour, min);
1016 depends on locale, and may permute the arguments.
1021 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
1025 one might obtain "Sonntag, 3. Juli, 10:02".
1027 To allocate a sufficiently large string and print into it
1028 (code correct for both glibc 2.0 and glibc 2.1):
1036 make_message(const char *fmt, ...)
1038 /* Guess we need no more than 100 bytes. */
1043 if ((p = malloc(size)) == NULL)
1047 /* Try to print in the allocated space. */
1049 n = vsnprintf(p, size, fmt, ap);
1051 /* If that worked, return the string. */
1052 if (n > \-1 && n < size)
1054 /* Else try again with more space. */
1055 if (n > \-1) /* glibc 2.1 */
1056 size = n+1; /* precisely what is needed */
1057 else /* glibc 2.0 */
1058 size *= 2; /* twice the old size */
1059 if ((np = realloc (p, size)) == NULL) {