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, see
20 .\" <http://www.gnu.org/licenses/>.
23 .\" Earlier versions of this page influenced the present text.
24 .\" It was derived from a Berkeley page with version
25 .\" @(#)printf.3 6.14 (Berkeley) 7/30/91
26 .\" converted for Linux by faith@cs.unc.edu, updated by
27 .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
29 .\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99.
30 .\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes
31 .\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes
33 .TH PRINTF 3 2013-03-05 "GNU" "Linux Programmer's Manual"
35 printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf,
36 vsnprintf \- formatted output conversion
40 .BI "int printf(const char *" format ", ...);"
42 .BI "int fprintf(FILE *" stream ", const char *" format ", ...);"
44 .BI "int sprintf(char *" str ", const char *" format ", ...);"
46 .BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);"
48 .B #include <stdarg.h>
50 .BI "int vprintf(const char *" format ", va_list " ap );
52 .BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap );
54 .BI "int vsprintf(char *" str ", const char *" format ", va_list " ap );
56 .BI "int vsnprintf(char *" str ", size_t " size ", const char *" format \
60 Feature Test Macro Requirements for glibc (see
61 .BR feature_test_macros (7)):
68 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
69 _POSIX_C_SOURCE\ >=\ 200112L;
78 family produce output according to a
87 the standard output stream;
91 write output to the given output
98 write to the character string
107 bytes (including the terminating null byte (\(aq\e0\(aq)) to
115 are equivalent to the functions
120 respectively, except that they are called with a
122 instead of a variable number of arguments.
123 These functions do not call the
126 Because they invoke the
130 is undefined after the call.
134 These eight functions write the output under the control of a
136 string that specifies how subsequent arguments (or arguments accessed via
137 the variable-length argument facilities of
139 are converted for output.
141 C99 and POSIX.1-2001 specify that the results are undefined if a call to
147 would cause copying to take place between objects that overlap
148 (e.g., if the target string array and one of the supplied input arguments
149 refer to the same buffer).
152 Upon successful return, these functions return the number of characters
153 printed (excluding the null byte used to end output to strings).
159 do not write more than
161 bytes (including the terminating null byte (\(aq\e0\(aq)).
162 If the output was truncated due to this limit then the return value
163 is the number of characters (excluding the terminating null byte)
164 which would have been written to the final string if enough space
166 Thus, a return value of
168 or more means that the output was truncated.
169 (See also below under NOTES.)
171 If an output error is encountered, a negative value is returned.
172 .SS Format of the format string
173 The format string is a character string, beginning and ending
174 in its initial shift state, if any.
175 The format string is composed of zero or more directives: ordinary
178 which are copied unchanged to the output stream;
179 and conversion specifications, each of which results in fetching zero or
180 more subsequent arguments.
181 Each conversion specification is introduced by
185 .IR "conversion specifier" .
186 In between there may be (in this order) zero or more
193 .IR "length modifier" .
195 The arguments must correspond properly (after type promotion) with the
196 conversion specifier.
197 By default, the arguments are used in the order
198 given, where each \(aq*\(aq and each conversion specifier asks for the next
199 argument (and it is an error if insufficiently many arguments are given).
200 One can also specify explicitly which argument is taken,
201 at each place where an argument is required, by writing "%m$" instead
202 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
203 where the decimal integer m denotes
204 the position in the argument list of the desired argument, indexed starting
210 printf("%*d", width, num);
218 printf("%2$*1$d", width, num);
223 The second style allows repeated references to the
225 The C99 standard does not include the style using \(aq$\(aq,
226 which comes from the Single UNIX Specification.
228 \(aq$\(aq is used, it must be used throughout for all conversions taking an
229 argument and all width and precision arguments, but it may be mixed
230 with "%%" formats which do not consume an argument.
232 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
233 arguments 1 and 3 are specified, argument 2 must also be specified
234 somewhere in the format string.
236 For some numeric conversions a radix character ("decimal point") or
237 thousands' grouping character is used.
238 The actual character used
243 uses \(aq.\(aq as radix character, and does not have a grouping character.
248 printf("%\(aq.2f", 1234567.89);
252 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
253 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
254 .SS The flag characters
255 The character % is followed by zero or more of the following flags:
258 The value should be converted to an "alternate form".
261 conversions, the first character of the output string is made zero
262 (by prefixing a 0 if it was not zero already).
267 conversions, a nonzero result has the string "0x" (or "0X" for
269 conversions) prepended to it.
280 conversions, the result will always contain a decimal point, even if no
281 digits follow it (normally, a decimal point appears in the results of those
282 conversions only if a digit follows).
287 conversions, trailing zeros are not removed from the result as they would
289 For other conversions, the result is undefined.
292 The value should be zero padded.
309 conversions, the converted value is padded on the left with zeros rather
315 flags both appear, the
318 If a precision is given with a numeric conversion
329 For other conversions, the behavior is undefined.
332 The converted value is to be left adjusted on the field boundary.
333 (The default is right justification.)
336 conversions, the converted value is padded on the right with blanks, rather
337 than on the left with blanks or zeros.
345 (a space) A blank should be left before a positive number
346 (or empty string) produced by a signed conversion.
349 A sign (+ or \-) should always be placed before a number produced by a signed
351 By default a sign is used only for negative numbers.
354 overrides a space if both are used.
356 The five flag characters above are defined in the C standard.
357 The SUSv2 specifies one further flag character.
360 For decimal conversion
368 the output is to be grouped with thousands' grouping characters
369 if the locale information indicates any.
370 Note that many versions of
372 cannot parse this option and will issue a warning.
374 include \fI%\(aqF\fP.
376 glibc 2.2 adds one further flag character.
379 For decimal integer conversion
383 the output uses the locale's alternative output digits, if any.
384 For example, since glibc 2.2.3 this will give Arabic-Indic digits
385 in the Persian ("fa_IR") locale.
386 .\" outdigits keyword in locale file
388 An optional decimal digit string (with nonzero first digit) specifying
389 a minimum field width.
390 If the converted value has fewer characters
391 than the field width, it will be padded with spaces on the left
392 (or right, if the left-adjustment flag has been given).
393 Instead of a decimal digit string one may write "*" or "*m$"
394 (for some decimal integer \fIm\fP) to specify that the field width
395 is given in the next argument, or in the \fIm\fP-th argument, respectively,
396 which must be of type
398 A negative field width is taken as a \(aq\-\(aq flag followed by a
399 positive field width.
400 In no case does a nonexistent or small field width cause truncation of a
401 field; if the result of a conversion is wider than the field width, the
402 field is expanded to contain the conversion result.
404 An optional precision, in the form of a period (\(aq.\(aq) followed by an
405 optional decimal digit string.
406 Instead of a decimal digit string one may write "*" or "*m$"
407 (for some decimal integer m) to specify that the precision
408 is given in the next argument, or in the m-th argument, respectively,
409 which must be of type
411 If the precision is given as just \(aq.\(aq, or the precision is negative,
412 the precision is taken to be zero.
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
533 A following integer conversion corresponds to a
544 A following integer conversion corresponds to a
548 The SUSv2 only knows about the length modifiers
576 .SS The conversion specifier
577 A character that specifies the type of conversion to be applied.
578 The conversion specifiers and their meanings are:
583 argument is converted to signed decimal notation.
584 The precision, if any, gives the minimum number of digits
585 that must appear; if the converted value requires fewer digits, it is
586 padded on the left with zeros.
587 The default precision is 1.
588 When 0 is printed with an explicit precision 0, the output is empty.
590 .BR o ", " u ", " x ", " X
593 argument is converted to unsigned octal
597 or unsigned hexadecimal
606 conversions; the letters
611 The precision, if any, gives the minimum number of digits
612 that must appear; if the converted value requires fewer digits, it is
613 padded on the left with zeros.
614 The default precision is 1.
615 When 0 is printed with an explicit precision 0, the output is empty.
620 argument is rounded and converted in the style
621 .RB [\-]d \&. ddd e \(+-dd
622 where there is one digit before the decimal-point character and the number
623 of digits after it is equal to the precision; if the precision is missing,
624 it is taken as 6; if the precision is zero, no decimal-point character
628 conversion uses the letter
632 to introduce the exponent.
633 The exponent always contains at least two
634 digits; if the value is zero, the exponent is 00.
639 argument is rounded and converted to decimal notation in the style
641 where the number of digits after the decimal-point character is equal to
642 the precision specification.
643 If the precision is missing, it is taken as
644 6; if the precision is explicitly zero, no decimal-point character appears.
645 If a decimal point appears, at least one digit appears before it.
647 (The SUSv2 does not know about
649 and says that character string representations for infinity and NaN
650 may be made available.
651 The C99 standard specifies "[\-]inf" or "[\-]infinity"
652 for infinity, and a string starting with "nan" for NaN, in the case of
654 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN*" in the case of
661 argument is converted in style
672 The precision specifies the number of significant digits.
673 If the precision is missing, 6 digits are given; if the precision is zero,
677 is used if the exponent from its conversion is less than \-4 or greater
678 than or equal to the precision.
679 Trailing zeros are removed from the
680 fractional part of the result; a decimal point appears only if it is
681 followed by at least one digit.
684 (C99; not in SUSv2) For
688 argument is converted to hexadecimal notation (using the letters abcdef)
690 .RB [\-] 0x h \&. hhhh p \(+-;
693 conversion the prefix
695 the letters ABCDEF, and the exponent separator
698 There is one hexadecimal digit before the decimal point,
699 and the number of digits after it is equal to the precision.
700 The default precision suffices for an exact representation of the value
701 if an exact representation in base 2 exists
702 and otherwise is sufficiently large to distinguish values of type
704 The digit before the decimal point is unspecified for nonnormalized
705 numbers, and nonzero but otherwise unspecified for normalized numbers.
710 modifier is present, the
712 argument is converted to an
713 .IR "unsigned char" ,
714 and the resulting character is written.
717 modifier is present, the
719 (wide character) argument is converted to a multibyte sequence by a call
722 function, with a conversion state starting in the initial state, and the
723 resulting multibyte string is written.
728 modifier is present: The
730 argument is expected to be a pointer to an array of character type (pointer
732 Characters from the array are written up to (but not
733 including) a terminating null byte (\(aq\\0\(aq);
734 if a precision is specified, no more than the number specified
736 If a precision is given, no null byte need be present;
737 if the precision is not specified, or is greater than the size of the
738 array, the array must contain a terminating null byte.
742 modifier is present: The
744 argument is expected to be a pointer to an array of wide characters.
745 Wide characters from the array are converted to multibyte characters
746 (each by a call to the
748 function, with a conversion state starting in the initial state before
749 the first wide character), up to and including a terminating null
751 The resulting multibyte characters are written up to
752 (but not including) the terminating null byte.
754 specified, no more bytes than the number specified are written, but
755 no partial multibyte characters are written.
756 Note that the precision
757 determines the number of
759 written, not the number of
762 .IR "screen positions" .
763 The array must contain a terminating null wide character, unless a
764 precision is given and it is so small that the number of bytes written
765 exceeds it before the end of the array is reached.
768 (Not in C99, but in SUSv2.)
774 (Not in C99, but in SUSv2.)
782 pointer argument is printed in hexadecimal (as if by
788 The number of characters written so far is stored into the integer
791 (or variant) pointer argument.
792 No argument is converted.
797 .IR strerror(errno) .
798 No argument is required.
801 A \(aq%\(aq is written.
802 No argument is converted.
803 The complete conversion
804 specification is \(aq%%\(aq.
814 functions conform to C89 and C99.
819 functions conform to C99.
821 Concerning the return value of
823 SUSv2 and C99 contradict each other: when
827 then SUSv2 stipulates an unspecified return value less than 1,
830 to be NULL in this case, and gives the return value (as always)
831 as the number of characters that would have been written in case
832 the output string has been large enough.
834 Linux libc4 knows about the five C standard flags.
835 It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
837 \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
838 \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
839 \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
840 where \fBF\fP is a synonym for \fBf\fP.
841 Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
842 for \fBld\fP, \fBlo\fP, and \fBlu\fP.
843 (This is bad, and caused serious bugs later, when
844 support for \fB%D\fP disappeared.)
845 No locale-dependent radix character,
846 no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
848 Linux libc5 knows about the five C standard flags and the \(aq flag,
849 locale, "%m$" and "*m$".
850 It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
851 \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
852 both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
853 It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
854 but adds the conversion character
857 .IR strerror(errno) .
859 glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
861 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
862 and conversion characters \fBa\fP and \fBA\fP.
864 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
865 and the flag character \fBI\fP.
867 Some programs imprudently rely on code such as the following
869 sprintf(buf, "%s some further text", buf);
873 However, the standards explicitly note that the results are undefined
874 if source and destination buffers overlap when calling
880 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
881 Depending on the version of
883 used, and the compiler options employed, calls such as the above will
885 produce the expected results.
887 The glibc implementation of the functions
891 conforms to the C99 standard, that is, behaves as described above,
892 since glibc version 2.1.
893 Until glibc 2.0.6 they would return \-1
894 when the output was truncated.
896 .\" UNIX V7 defines the three routines
900 .\" and has the flag \-, the width or precision *, the length modifier l,
901 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
902 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
903 .\" #, + and <space> and no longer mentions D,O,U,X.
908 .\" and warns not to use D,O,U,X.
909 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
910 .\" and the conversions n, p, E, G, X (with current meaning)
911 .\" and deprecates D,O,U.
912 .\" 4.4BSD introduces the functions
915 .\" .BR vsnprintf (),
916 .\" and the length modifier q.
917 .\" FreeBSD also has functions
920 .\" .BR vasprintf (),
921 .\" that allocate a buffer large enough for
923 .\" In glibc there are functions
927 .\" that print to a file descriptor instead of a stream.
933 assume an arbitrarily long string, callers must be careful not to overflow
934 the actual space; this is often impossible to assure.
936 of the strings produced is locale-dependent and difficult to predict.
946 Linux libc4.[45] does not have a
948 but provides a libbsd that contains an
952 that is, one that ignores the
957 with early libc4 leads to serious security problems.
961 often indicates a bug, since
963 may contain a % character.
966 comes from untrusted user input, it may contain \fB%n\fP, causing the
968 call to write to memory and creating a security hole.
970 .\" Some floating-point conversions under early libc4
971 .\" caused memory leaks.
975 to five decimal places:
981 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
985 To print a date and time in the form "Sunday, July 3, 10:02",
990 are pointers to strings:
995 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
996 weekday, month, day, hour, min);
1000 Many countries use the day-month-year order.
1001 Hence, an internationalized version must be able to print
1002 the arguments in an order specified by the format:
1007 fprintf(stdout, format,
1008 weekday, month, day, hour, min);
1014 depends on locale, and may permute the arguments.
1019 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
1023 one might obtain "Sonntag, 3. Juli, 10:02".
1025 To allocate a sufficiently large string and print into it
1026 (code correct for both glibc 2.0 and glibc 2.1):
1028 If truncation occurs in glibc versions prior to 2.0.6, this is treated as an
1029 error instead of being handled gracefully.
1037 make_message(const char *fmt, ...)
1040 int size = 100; /* Guess we need no more than 100 bytes */
1044 if ((p = malloc(size)) == NULL)
1049 /* Try to print in the allocated space */
1052 n = vsnprintf(p, size, fmt, ap);
1055 /* Check error code */
1060 /* If that worked, return the string */
1065 /* Else try again with more space */
1067 size = n + 1; /* Precisely what is needed */
1070 if ((np = realloc (p, size)) == NULL) {