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 2008-07-12 "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)):
68 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE; or
74 family produce output according to a
83 the standard output stream;
87 write output to the given output
94 write to the character string
103 bytes (including the trailing null byte (\(aq\e0\(aq)) to
111 are equivalent to the functions
116 respectively, except that they are called with a
118 instead of a variable number of arguments.
119 These functions do not call the
122 Because they invoke the
126 is undefined after the call.
130 These eight functions write the output under the control of a
132 string that specifies how subsequent arguments (or arguments accessed via
133 the variable-length argument facilities of
135 are converted for output.
137 Upon successful return, these functions return the number of characters
138 printed (not including the
139 trailing \(aq\e0\(aq used to end output to strings).
145 do not write more than
147 bytes (including the trailing \(aq\e0\(aq).
148 If the output was truncated due to this limit then the return value
149 is the number of characters (not including the trailing \(aq\e0\(aq)
150 which would have been written to the final string if enough space
152 Thus, a return value of
154 or more means that the output was truncated.
155 (See also below under NOTES.)
157 If an output error is encountered, a negative value is returned.
158 .SS "Format of the format string"
159 The format string is a character string, beginning and ending
160 in its initial shift state, if any.
161 The format string is composed of zero or more directives: ordinary
164 which are copied unchanged to the output stream;
165 and conversion specifications, each of which results in fetching zero or
166 more subsequent arguments.
167 Each conversion specification is introduced by
171 .IR "conversion specifier" .
172 In between there may be (in this order) zero or more
179 .IR "length modifier" .
181 The arguments must correspond properly (after type promotion) with the
182 conversion specifier.
183 By default, the arguments are used in the order
184 given, where each \(aq*\(aq and each conversion specifier asks for the next
185 argument (and it is an error if insufficiently many arguments are given).
186 One can also specify explicitly which argument is taken,
187 at each place where an argument is required, by writing "%m$" instead
188 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
189 where the decimal integer m denotes
190 the position in the argument list of the desired argument, indexed starting
196 printf("%*d", width, num);
204 printf("%2$*1$d", width, num);
209 The second style allows repeated references to the
211 The C99 standard does not include the style using \(aq$\(aq,
212 which comes from the Single Unix Specification.
214 \(aq$\(aq is used, it must be used throughout for all conversions taking an
215 argument and all width and precision arguments, but it may be mixed
216 with "%%" formats which do not consume an argument.
218 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
219 arguments 1 and 3 are specified, argument 2 must also be specified
220 somewhere in the format string.
222 For some numeric conversions a radix character ("decimal point") or
223 thousands' grouping character is used.
224 The actual character used
229 uses \(aq.\(aq as radix character, and does not have a grouping character.
234 printf("%\(aq.2f", 1234567.89);
238 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
239 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
240 .SS "The flag characters"
241 The character % is followed by zero or more of the following flags:
244 The value should be converted to an "alternate form".
247 conversions, the first character of the output string is made zero
248 (by prefixing a 0 if it was not zero already).
253 conversions, a non-zero result has the string "0x" (or "0X" for
255 conversions) prepended to it.
266 conversions, the result will always contain a decimal point, even if no
267 digits follow it (normally, a decimal point appears in the results of those
268 conversions only if a digit follows).
273 conversions, trailing zeros are not removed from the result as they would
275 For other conversions, the result is undefined.
278 The value should be zero padded.
295 conversions, the converted value is padded on the left with zeros rather
301 flags both appear, the
304 If a precision is given with a numeric conversion
315 For other conversions, the behavior is undefined.
318 The converted value is to be left adjusted on the field boundary.
319 (The default is right justification.)
322 conversions, the converted value is padded on the right with blanks, rather
323 than on the left with blanks or zeros.
331 (a space) A blank should be left before a positive number
332 (or empty string) produced by a signed conversion.
335 A sign (+ or \-) should always be placed before a number produced by a signed
337 By default a sign is used only for negative numbers.
340 overrides a space if both are used.
342 The five flag characters above are defined in the C standard.
343 The SUSv2 specifies one further flag character.
346 For decimal conversion
354 the output is to be grouped with thousands' grouping characters
355 if the locale information indicates any.
356 Note that many versions of
358 cannot parse this option and will issue a warning.
360 include \fI%\(aqF\fP.
362 glibc 2.2 adds one further flag character.
365 For decimal integer conversion
369 the output uses the locale's alternative output digits, if any.
370 For example, since glibc 2.2.3 this will give Arabic-Indic digits
371 in the Persian ("fa_IR") locale.
372 .\" outdigits keyword in locale file
373 .SS "The field width"
374 An optional decimal digit string (with non-zero first digit) specifying
375 a minimum field width.
376 If the converted value has fewer characters
377 than the field width, it will be padded with spaces on the left
378 (or right, if the left-adjustment flag has been given).
379 Instead of a decimal digit string one may write "*" or "*m$"
380 (for some decimal integer \fIm\fP) to specify that the field width
381 is given in the next argument, or in the \fIm\fP-th argument, respectively,
382 which must be of type
384 A negative field width is taken as a \(aq\-\(aq flag followed by a
385 positive field width.
386 In no case does a nonexistent or small field width cause truncation of a
387 field; if the result of a conversion is wider than the field width, the
388 field is expanded to contain the conversion result.
390 An optional precision, in the form of a period (\(aq.\(aq) followed by an
391 optional decimal digit string.
392 Instead of a decimal digit string one may write "*" or "*m$"
393 (for some decimal integer m) to specify that the precision
394 is given in the next argument, or in the m-th argument, respectively,
395 which must be of type
397 If the precision is given as just \(aq.\(aq, or the precision is negative,
398 the precision is taken to be zero.
399 This gives the minimum number of digits to appear for
407 conversions, the number of digits to appear after the radix character for
415 conversions, the maximum number of significant digits for
419 conversions, or the maximum number of characters to be printed from a
425 .SS "The length modifier"
426 Here, "integer conversion" stands for
437 A following integer conversion corresponds to a
441 argument, or a following
443 conversion corresponds to a pointer to a
448 A following integer conversion corresponds to a
451 .I unsigned short int
452 argument, or a following
454 conversion corresponds to a pointer to a
459 (ell) A following integer conversion corresponds to a
463 argument, or a following
465 conversion corresponds to a pointer to a
467 argument, or a following
469 conversion corresponds to a
471 argument, or a following
473 conversion corresponds to a pointer to
479 A following integer conversion corresponds to a
482 .I unsigned long long int
483 argument, or a following
485 conversion corresponds to a pointer to a
500 conversion corresponds to a
503 (C99 allows %LF, but SUSv2 does not.)
506 ("quad". 4.4BSD and Linux libc5 only.
508 This is a synonym for
512 A following integer conversion corresponds to an
519 A following integer conversion corresponds to a
530 A following integer conversion corresponds to a
534 The SUSv2 only knows about the length modifiers
562 .SS "The conversion specifier"
563 A character that specifies the type of conversion to be applied.
564 The conversion specifiers and their meanings are:
569 argument is converted to signed decimal notation.
570 The precision, if any, gives the minimum number of digits
571 that must appear; if the converted value requires fewer digits, it is
572 padded on the left with zeros.
573 The default precision is 1.
574 When 0 is printed with an explicit precision 0, the output is empty.
576 .BR o ", " u ", " x ", " X
579 argument is converted to unsigned octal
583 or unsigned hexadecimal
592 conversions; the letters
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.
606 argument is rounded and converted in the style
607 .if \w'\*(Pm'=0 .ds Pm \(+-
608 .RB [\-]d \&. ddd e \\*(Pmdd
609 where there is one digit before the decimal-point character and the number
610 of digits after it is equal to the precision; if the precision is missing,
611 it is taken as 6; if the precision is zero, no decimal-point character
615 conversion uses the letter
619 to introduce the exponent.
620 The exponent always contains at least two
621 digits; if the value is zero, the exponent is 00.
626 argument is rounded and converted to decimal notation in the style
628 where the number of digits after the decimal-point character is equal to
629 the precision specification.
630 If the precision is missing, it is taken as
631 6; if the precision is explicitly zero, no decimal-point character appears.
632 If a decimal point appears, at least one digit appears before it.
634 (The SUSv2 does not know about
636 and says that character string representations for infinity and NaN
637 may be made available.
638 The C99 standard specifies "[\-]inf" or "[\-]infinity"
639 for infinity, and a string starting with "nan" for NaN, in the case of
641 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN*" in the case of
648 argument is converted in style
659 The precision specifies the number of significant digits.
660 If the precision is missing, 6 digits are given; if the precision is zero,
664 is used if the exponent from its conversion is less than \-4 or greater
665 than or equal to the precision.
666 Trailing zeros are removed from the
667 fractional part of the result; a decimal point appears only if it is
668 followed by at least one digit.
671 (C99; not in SUSv2) For
675 argument is converted to hexadecimal notation (using the letters abcdef)
677 .RB [\-] 0x h \&. hhhh p \\*(Pmd;
680 conversion the prefix
682 the letters ABCDEF, and the exponent separator
685 There is one hexadecimal digit before the decimal point,
686 and the number of digits after it is equal to the precision.
687 The default precision suffices for an exact representation of the value
688 if an exact representation in base 2 exists
689 and otherwise is sufficiently large to distinguish values of type
691 The digit before the decimal point is unspecified for non-normalized
692 numbers, and non-zero but otherwise unspecified for normalized numbers.
697 modifier is present, the
699 argument is converted to an
700 .IR "unsigned char" ,
701 and the resulting character is written.
704 modifier is present, the
706 (wide character) argument is converted to a multibyte sequence by a call
709 function, with a conversion state starting in the initial state, and the
710 resulting multibyte string is written.
715 modifier is present: The
717 argument is expected to be a pointer to an array of character type (pointer
719 Characters from the array are written up to (but not
720 including) a terminating null byte (\(aq\\0\(aq);
721 if a precision is specified, no more than the number specified
723 If a precision is given, no null byte need be present;
724 if the precision is not specified, or is greater than the size of the
725 array, the array must contain a terminating null byte.
729 modifier is present: The
731 argument is expected to be a pointer to an array of wide characters.
732 Wide characters from the array are converted to multibyte characters
733 (each by a call to the
735 function, with a conversion state starting in the initial state before
736 the first wide character), up to and including a terminating null
738 The resulting multibyte characters are written up to
739 (but not including) the terminating null byte.
741 specified, no more bytes than the number specified are written, but
742 no partial multibyte characters are written.
743 Note that the precision
744 determines the number of
746 written, not the number of
749 .IR "screen positions" .
750 The array must contain a terminating null wide character, unless a
751 precision is given and it is so small that the number of bytes written
752 exceeds it before the end of the array is reached.
755 (Not in C99, but in SUSv2.)
761 (Not in C99, but in SUSv2.)
769 pointer argument is printed in hexadecimal (as if by
775 The number of characters written so far is stored into the integer
778 (or variant) pointer argument.
779 No argument is converted.
784 .IR strerror(errno) .
785 No argument is required.
788 A \(aq%\(aq is written.
789 No argument is converted.
790 The complete conversion
791 specification is \(aq%%\(aq.
801 functions conform to C89 and C99.
806 functions conform to C99.
808 Concerning the return value of
810 SUSv2 and C99 contradict each other: when
814 then SUSv2 stipulates an unspecified return value less than 1,
817 to be NULL in this case, and gives the return value (as always)
818 as the number of characters that would have been written in case
819 the output string has been large enough.
821 Linux libc4 knows about the five C standard flags.
822 It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
824 \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
825 \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
826 \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
827 where \fBF\fP is a synonym for \fBf\fP.
828 Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
829 for \fBld\fP, \fBlo\fP, and \fBlu\fP.
830 (This is bad, and caused serious bugs later, when
831 support for \fB%D\fP disappeared.)
832 No locale-dependent radix character,
833 no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
835 Linux libc5 knows about the five C standard flags and the \(aq flag,
836 locale, "%m$" and "*m$".
837 It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
838 \fBZ\fP, iand \fBq\fP, but accepts \fBL\fP and \fBq\fP
839 both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
840 It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
841 but adds the conversion character
844 .IR strerror(errno) .
846 glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
848 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
849 and conversion characters \fBa\fP and\fBA\fP.
851 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
852 and the flag character \fBI\fP.
854 The glibc implementation of the functions
858 conforms to the C99 standard, that is, behaves as described above,
859 since glibc version 2.1.
860 Until glibc 2.0.6 they would return \-1
861 when the output was truncated.
863 .\" Unix V7 defines the three routines
867 .\" and has the flag \-, the width or precision *, the length modifier l,
868 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
869 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
870 .\" #, + and <space> and no longer mentions D,O,U,X.
875 .\" and warns not to use D,O,U,X.
876 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
877 .\" and the conversions n, p, E, G, X (with current meaning)
878 .\" and deprecates D,O,U.
879 .\" 4.4BSD introduces the functions
882 .\" .BR vsnprintf (),
883 .\" and the length modifier q.
884 .\" FreeBSD also has functions
887 .\" .BR vasprintf (),
888 .\" that allocate a buffer large enough for
890 .\" In glibc there are functions
894 .\" that print to a file descriptor instead of a stream.
900 assume an arbitrarily long string, callers must be careful not to overflow
901 the actual space; this is often impossible to assure.
903 of the strings produced is locale-dependent and difficult to predict.
913 Linux libc4.[45] does not have a
915 but provides a libbsd that contains an
919 that is, one that ignores the
924 with early libc4 leads to serious security problems.
928 often indicates a bug, since
930 may contain a % character.
933 comes from untrusted user input, it may contain \fB%n\fP, causing the
935 call to write to memory and creating a security hole.
937 .\" Some floating point conversions under early libc4
938 .\" caused memory leaks.
940 .if \w'\*(Pi'=0 .ds Pi pi
941 To print \*(Pi to five decimal places:
947 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
951 To print a date and time in the form "Sunday, July 3, 10:02",
956 are pointers to strings:
961 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
962 weekday, month, day, hour, min);
966 Many countries use the day-month-year order.
967 Hence, an internationalized version must be able to print
968 the arguments in an order specified by the format:
973 fprintf(stdout, format,
974 weekday, month, day, hour, min);
980 depends on locale, and may permute the arguments.
985 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
989 one might obtain "Sonntag, 3. Juli, 10:02".
991 To allocate a sufficiently large string and print into it
992 (code correct for both glibc 2.0 and glibc 2.1):
1000 make_message(const char *fmt, ...)
1002 /* Guess we need no more than 100 bytes. */
1007 if ((p = malloc(size)) == NULL)
1011 /* Try to print in the allocated space. */
1013 n = vsnprintf(p, size, fmt, ap);
1015 /* If that worked, return the string. */
1016 if (n > \-1 && n < size)
1018 /* Else try again with more space. */
1019 if (n > \-1) /* glibc 2.1 */
1020 size = n+1; /* precisely what is needed */
1021 else /* glibc 2.0 */
1022 size *= 2; /* twice the old size */
1023 if ((np = realloc (p, size)) == NULL) {