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 2007-11-26 "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 ", va_list " ap );
60 Feature Test Macro Requirements for glibc (see
61 .BR feature_test_macros (7)):
67 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE; or
73 family produce output according to a
82 the standard output stream;
86 write output to the given output
93 write to the character string
102 bytes (including the trailing null byte (\(aq\e0\(aq)) to
110 are equivalent to the functions
115 respectively, except that they are called with a
117 instead of a variable number of arguments.
118 These functions do not call the
121 Because they invoke the
125 is undefined after the call.
129 These eight functions write the output under the control of a
131 string that specifies how subsequent arguments (or arguments accessed via
132 the variable-length argument facilities of
134 are converted for output.
136 Upon successful return, these functions return the number of characters
137 printed (not including the
138 trailing \(aq\e0\(aq used to end output to strings).
144 do not write more than
146 bytes (including the trailing \(aq\e0\(aq).
147 If the output was truncated due to this limit then the return value
148 is the number of characters (not including the trailing \(aq\e0\(aq)
149 which would have been written to the final string if enough space
151 Thus, a return value of
153 or more means that the output was truncated.
154 (See also below under NOTES.)
156 If an output error is encountered, a negative value is returned.
157 .SS "Format of the format string"
158 The format string is a character string, beginning and ending
159 in its initial shift state, if any.
160 The format string is composed of zero or more directives: ordinary
163 which are copied unchanged to the output stream;
164 and conversion specifications, each of which results in fetching zero or
165 more subsequent arguments.
166 Each conversion specification is introduced by
170 .IR "conversion specifier" .
171 In between there may be (in this order) zero or more
178 .IR "length modifier" .
180 The arguments must correspond properly (after type promotion) with the
181 conversion specifier.
182 By default, the arguments are used in the order
183 given, where each \(aq*\(aq and each conversion specifier asks for the next
184 argument (and it is an error if insufficiently many arguments are given).
185 One can also specify explicitly which argument is taken,
186 at each place where an argument is required, by writing "%m$" instead
187 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
188 where the decimal integer m denotes
189 the position in the argument list of the desired argument, indexed starting
195 printf("%*d", width, num);
203 printf("%2$*1$d", width, num);
208 The second style allows repeated references to the
210 The C99 standard does not include the style using \(aq$\(aq,
211 which comes from the Single Unix Specification.
213 \(aq$\(aq is used, it must be used throughout for all conversions taking an
214 argument and all width and precision arguments, but it may be mixed
215 with "%%" formats which do not consume an argument.
217 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
218 arguments 1 and 3 are specified, argument 2 must also be specified
219 somewhere in the format string.
221 For some numeric conversions a radix character ("decimal point") or
222 thousands' grouping character is used.
223 The actual character used
228 uses \(aq.\(aq as radix character, and does not have a grouping character.
233 printf("%\(aq.2f", 1234567.89);
237 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
238 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
239 .SS "The flag characters"
240 The character % is followed by zero or more of the following flags:
243 The value should be converted to an "alternate form".
246 conversions, the first character of the output string is made zero
247 (by prefixing a 0 if it was not zero already).
252 conversions, a non-zero result has the string "0x" (or "0X" for
254 conversions) prepended to it.
265 conversions, the result will always contain a decimal point, even if no
266 digits follow it (normally, a decimal point appears in the results of those
267 conversions only if a digit follows).
272 conversions, trailing zeros are not removed from the result as they would
274 For other conversions, the result is undefined.
277 The value should be zero padded.
294 conversions, the converted value is padded on the left with zeros rather
300 flags both appear, the
303 If a precision is given with a numeric conversion
314 For other conversions, the behavior is undefined.
317 The converted value is to be left adjusted on the field boundary.
318 (The default is right justification.)
321 conversions, the converted value is padded on the right with blanks, rather
322 than on the left with blanks or zeros.
330 (a space) A blank should be left before a positive number
331 (or empty string) produced by a signed conversion.
334 A sign (+ or \-) should always be placed before a number produced by a signed
336 By default a sign is used only for negative numbers.
339 overrides a space if both are used.
341 The five flag characters above are defined in the C standard.
342 The SUSv2 specifies one further flag character.
345 For decimal conversion
353 the output is to be grouped with thousands' grouping characters
354 if the locale information indicates any.
355 Note that many versions of
357 cannot parse this option and will issue a warning.
359 include \fI%\(aqF\fP.
361 glibc 2.2 adds one further flag character.
364 For decimal integer conversion
368 the output uses the locale's alternative output digits, if any.
369 For example, since glibc 2.2.3 this will give Arabic-Indic digits
370 in the Persian ("fa_IR") locale.
371 .\" outdigits keyword in locale file
372 .SS "The field width"
373 An optional decimal digit string (with non-zero first digit) specifying
374 a minimum field width.
375 If the converted value has fewer characters
376 than the field width, it will be padded with spaces on the left
377 (or right, if the left-adjustment flag has been given).
378 Instead of a decimal digit string one may write "*" or "*m$"
379 (for some decimal integer \fIm\fP) to specify that the field width
380 is given in the next argument, or in the \fIm\fP-th argument, respectively,
381 which must be of type
383 A negative field width is taken as a \(aq\-\(aq flag followed by a
384 positive field width.
385 In no case does a nonexistent or small field width cause truncation of a
386 field; if the result of a conversion is wider than the field width, the
387 field is expanded to contain the conversion result.
389 An optional precision, in the form of a period (\(aq.\(aq) followed by an
390 optional decimal digit string.
391 Instead of a decimal digit string one may write "*" or "*m$"
392 (for some decimal integer m) to specify that the precision
393 is given in the next argument, or in the m-th argument, respectively,
394 which must be of type
396 If the precision is given as just \(aq.\(aq, or the precision is negative,
397 the precision is taken to be zero.
398 This gives the minimum number of digits to appear for
406 conversions, the number of digits to appear after the radix character for
414 conversions, the maximum number of significant digits for
418 conversions, or the maximum number of characters to be printed from a
424 .SS "The length modifier"
425 Here, "integer conversion" stands for
436 A following integer conversion corresponds to a
440 argument, or a following
442 conversion corresponds to a pointer to a
447 A following integer conversion corresponds to a
450 .I unsigned short int
451 argument, or a following
453 conversion corresponds to a pointer to a
458 (ell) A following integer conversion corresponds to a
462 argument, or a following
464 conversion corresponds to a pointer to a
466 argument, or a following
468 conversion corresponds to a
470 argument, or a following
472 conversion corresponds to a pointer to
478 A following integer conversion corresponds to a
481 .I unsigned long long int
482 argument, or a following
484 conversion corresponds to a pointer to a
499 conversion corresponds to a
502 (C99 allows %LF, but SUSv2 does not.)
505 ("quad". 4.4BSD and Linux libc5 only.
507 This is a synonym for
511 A following integer conversion corresponds to an
518 A following integer conversion corresponds to a
529 A following integer conversion corresponds to a
533 The SUSv2 only knows about the length modifiers
561 .SS "The conversion specifier"
562 A character that specifies the type of conversion to be applied.
563 The conversion specifiers and their meanings are:
568 argument is converted to signed decimal notation.
569 The precision, if any, gives the minimum number of digits
570 that must appear; if the converted value requires fewer digits, it is
571 padded on the left with zeros.
572 The default precision is 1.
573 When 0 is printed with an explicit precision 0, the output is empty.
578 argument is converted to unsigned octal
582 or unsigned hexadecimal
591 conversions; the letters
596 The precision, if any, gives the minimum number of digits
597 that must appear; if the converted value requires fewer digits, it is
598 padded on the left with zeros.
599 The default precision is 1.
600 When 0 is printed with an explicit precision 0, the output is empty.
605 argument is rounded and converted in the style
606 .if \w'\*(Pm'=0 .ds Pm \(+-
607 .RB [\-]d \&. ddd e \\*(Pmdd
608 where there is one digit before the decimal-point character and the number
609 of digits after it is equal to the precision; if the precision is missing,
610 it is taken as 6; if the precision is zero, no decimal-point character
614 conversion uses the letter
618 to introduce the exponent.
619 The exponent always contains at least two
620 digits; if the value is zero, the exponent is 00.
625 argument is rounded and converted to decimal notation in the style
627 where the number of digits after the decimal-point character is equal to
628 the precision specification.
629 If the precision is missing, it is taken as
630 6; if the precision is explicitly zero, no decimal-point character appears.
631 If a decimal point appears, at least one digit appears before it.
633 (The SUSv2 does not know about
635 and says that character string representations for infinity and NaN
636 may be made available.
637 The C99 standard specifies "[\-]inf" or "[\-]infinity"
638 for infinity, and a string starting with "nan" for NaN, in the case of
640 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN*" in the case of
647 argument is converted in style
658 The precision specifies the number of significant digits.
659 If the precision is missing, 6 digits are given; if the precision is zero,
663 is used if the exponent from its conversion is less than \-4 or greater
664 than or equal to the precision.
665 Trailing zeros are removed from the
666 fractional part of the result; a decimal point appears only if it is
667 followed by at least one digit.
670 (C99; not in SUSv2) For
674 argument is converted to hexadecimal notation (using the letters abcdef)
676 .RB [\-] 0x h \&. hhhh p \\*(Pmd;
679 conversion the prefix
681 the letters ABCDEF, and the exponent separator
684 There is one hexadecimal digit before the decimal point,
685 and the number of digits after it is equal to the precision.
686 The default precision suffices for an exact representation of the value
687 if an exact representation in base 2 exists
688 and otherwise is sufficiently large to distinguish values of type
690 The digit before the decimal point is unspecified for non-normalized
691 numbers, and non-zero but otherwise unspecified for normalized numbers.
696 modifier is present, the
698 argument is converted to an
699 .IR "unsigned char" ,
700 and the resulting character is written.
703 modifier is present, the
705 (wide character) argument is converted to a multibyte sequence by a call
708 function, with a conversion state starting in the initial state, and the
709 resulting multibyte string is written.
714 modifier is present: The
716 argument is expected to be a pointer to an array of character type (pointer
718 Characters from the array are written up to (but not
719 including) a terminating null byte (\(aq\\0\(aq);
720 if a precision is specified, no more than the number specified
722 If a precision is given, no null byte need be present;
723 if the precision is not specified, or is greater than the size of the
724 array, the array must contain a terminating null byte.
728 modifier is present: The
730 argument is expected to be a pointer to an array of wide characters.
731 Wide characters from the array are converted to multibyte characters
732 (each by a call to the
734 function, with a conversion state starting in the initial state before
735 the first wide character), up to and including a terminating null
737 The resulting multibyte characters are written up to
738 (but not including) the terminating null byte.
740 specified, no more bytes than the number specified are written, but
741 no partial multibyte characters are written.
742 Note that the precision
743 determines the number of
745 written, not the number of
748 .IR "screen positions" .
749 The array must contain a terminating null wide character, unless a
750 precision is given and it is so small that the number of bytes written
751 exceeds it before the end of the array is reached.
754 (Not in C99, but in SUSv2.)
760 (Not in C99, but in SUSv2.)
768 pointer argument is printed in hexadecimal (as if by
774 The number of characters written so far is stored into the integer
777 (or variant) pointer argument.
778 No argument is converted.
783 .IR strerror(errno) .
784 No argument is required.
787 A \(aq%\(aq is written.
788 No argument is converted.
789 The complete conversion
790 specification is \(aq%%\(aq.
800 functions conform to C89 and C99.
805 functions conform to C99.
807 Concerning the return value of
809 SUSv2 and C99 contradict each other: when
813 then SUSv2 stipulates an unspecified return value less than 1,
816 to be NULL in this case, and gives the return value (as always)
817 as the number of characters that would have been written in case
818 the output string has been large enough.
820 Linux libc4 knows about the five C standard flags.
821 It knows about the length modifiers h,l,L, and the conversions
822 cdeEfFgGinopsuxX, where F is a synonym for f.
823 Additionally, it accepts D,O,U as synonyms for ld,lo,lu.
824 (This is bad, and caused serious bugs later, when
825 support for %D disappeared.)
826 No locale-dependent radix character,
827 no thousands' separator, no NaN or infinity, no %m$ and *m$.
829 Linux libc5 knows about the five C standard flags and the \(aq flag,
831 It knows about the length modifiers h,l,L,Z,q, but accepts L and q
832 both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
833 It no longer recognizes FDOU, but adds the conversion character
836 .IR strerror(errno) .
838 glibc 2.0 adds conversion characters C and S.
840 glibc 2.1 adds length modifiers hh,j,t,z and conversion characters a,A.
842 glibc 2.2 adds the conversion character F with C99 semantics, and the
845 The glibc implementation of the functions
849 conforms to the C99 standard, that is, behaves as described above,
850 since glibc version 2.1.
851 Until glibc 2.0.6 they would return \-1
852 when the output was truncated.
854 .\" Unix V7 defines the three routines
858 .\" and has the flag \-, the width or precision *, the length modifier l,
859 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
860 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
861 .\" #, + and <space> and no longer mentions D,O,U,X.
866 .\" and warns not to use D,O,U,X.
867 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
868 .\" and the conversions n, p, E, G, X (with current meaning)
869 .\" and deprecates D,O,U.
870 .\" 4.4BSD introduces the functions
873 .\" .BR vsnprintf (),
874 .\" and the length modifier q.
875 .\" FreeBSD also has functions
878 .\" .BR vasprintf (),
879 .\" that allocate a buffer large enough for
881 .\" In glibc there are functions
885 .\" that print to a file descriptor instead of a stream.
891 assume an arbitrarily long string, callers must be careful not to overflow
892 the actual space; this is often impossible to assure.
894 of the strings produced is locale-dependent and difficult to predict.
904 Linux libc4.[45] does not have a
906 but provides a libbsd that contains an
910 that is, one that ignores the
915 with early libc4 leads to serious security problems.
919 often indicates a bug, since
921 may contain a % character.
924 comes from untrusted user input, it may contain %n, causing the
926 call to write to memory and creating a security hole.
928 .\" Some floating point conversions under early libc4
929 .\" caused memory leaks.
931 .if \w'\*(Pi'=0 .ds Pi pi
932 To print \*(Pi to five decimal places:
938 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
942 To print a date and time in the form "Sunday, July 3, 10:02",
947 are pointers to strings:
952 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
953 weekday, month, day, hour, min);
957 Many countries use the day-month-year order.
958 Hence, an internationalized version must be able to print
959 the arguments in an order specified by the format:
964 fprintf(stdout, format,
965 weekday, month, day, hour, min);
971 depends on locale, and may permute the arguments.
976 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
980 one might obtain "Sonntag, 3. Juli, 10:02".
982 To allocate a sufficiently large string and print into it
983 (code correct for both glibc 2.0 and glibc 2.1):
991 make_message(const char *fmt, ...)
993 /* Guess we need no more than 100 bytes. */
998 if ((p = malloc(size)) == NULL)
1002 /* Try to print in the allocated space. */
1004 n = vsnprintf(p, size, fmt, ap);
1006 /* If that worked, return the string. */
1007 if (n > \-1 && n < size)
1009 /* Else try again with more space. */
1010 if (n > \-1) /* glibc 2.1 */
1011 size = n+1; /* precisely what is needed */
1012 else /* glibc 2.0 */
1013 size *= 2; /* twice the old size */
1014 if ((np = realloc (p, size)) == NULL) {