| blob | 4fa1f11f3c25a5efa2be5cbb99f02f737c0e88c9 |
1 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
2 .\"
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.
8 .\"
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.
14 .\"
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.
19 .\"
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.
24 .\"
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/>.
28 .\" %%%LICENSE_END
29 .\"
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
33 .\"
34 .TH PRINTF 3 2021-03-22 "GNU" "Linux Programmer's Manual"
35 .SH NAME
36 printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf,
37 vsprintf, vsnprintf \- formatted output conversion
38 .SH SYNOPSIS
39 .nf
40 .B #include <stdio.h>
41 .PP
42 .BI "int printf(const char *restrict " format ", ...);"
43 .BI "int fprintf(FILE *restrict " stream ,
44 .BI " const char *restrict " format ", ...);"
45 .BI "int dprintf(int " fd ,
46 .BI " const char *restrict " format ", ...);"
47 .BI "int sprintf(char *restrict " str ,
48 .BI " const char *restrict " format ", ...);"
49 .BI "int snprintf(char *restrict " str ", size_t " size ,
50 .BI " const char *restrict " format ", ...);"
51 .PP
52 .B #include <stdarg.h>
53 .PP
54 .BI "int vprintf(const char *restrict " format ", va_list " ap );
55 .BI "int vfprintf(FILE *restrict " stream ,
56 .BI " const char *restrict " format ", va_list " ap );
57 .BI "int vdprintf(int " fd ,
58 .BI " const char *restrict " format ", va_list " ap );
59 .BI "int vsprintf(char *restrict " str ,
60 .BI " const char *restrict " format ", va_list " ap );
61 .BI "int vsnprintf(char *restrict " str ", size_t " size ,
62 .BI " const char *restrict " format ", va_list " ap );
63 .fi
64 .PP
65 .RS -4
66 Feature Test Macro Requirements for glibc (see
67 .BR feature_test_macros (7)):
68 .RE
69 .PP
70 .BR snprintf (),
71 .BR vsnprintf ():
72 .nf
73 _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
74 || /* Glibc <= 2.19: */ _BSD_SOURCE
75 .fi
76 .PP
77 .BR dprintf (),
78 .BR vdprintf ():
79 .nf
80 Since glibc 2.10:
81 _POSIX_C_SOURCE >= 200809L
82 Before glibc 2.10:
83 _GNU_SOURCE
84 .fi
85 .SH DESCRIPTION
86 The functions in the
87 .BR printf ()
88 family produce output according to a
89 .I format
90 as described below.
91 The functions
92 .BR printf ()
93 and
94 .BR vprintf ()
95 write output to
96 .IR stdout ,
97 the standard output stream;
98 .BR fprintf ()
99 and
100 .BR vfprintf ()
101 write output to the given output
102 .IR stream ;
103 .BR sprintf (),
104 .BR snprintf (),
105 .BR vsprintf (),
106 and
107 .BR vsnprintf ()
108 write to the character string
109 .IR str .
110 .PP
111 The function
112 .BR dprintf ()
113 is the same as
114 .BR fprintf ()
115 except that it outputs to a file descriptor,
116 .IR fd ,
117 instead of to a
118 .BR stdio (3)
119 stream.
120 .PP
121 The functions
122 .BR snprintf ()
123 and
124 .BR vsnprintf ()
125 write at most
126 .I size
127 bytes (including the terminating null byte (\(aq\e0\(aq)) to
128 .IR str .
129 .PP
130 The functions
131 .BR vprintf (),
132 .BR vfprintf (),
133 .BR vdprintf (),
134 .BR vsprintf (),
135 .BR vsnprintf ()
136 are equivalent to the functions
137 .BR printf (),
138 .BR fprintf (),
139 .BR dprintf (),
140 .BR sprintf (),
141 .BR snprintf (),
142 respectively, except that they are called with a
143 .I va_list
144 instead of a variable number of arguments.
145 These functions do not call the
146 .I va_end
147 macro.
148 Because they invoke the
149 .I va_arg
150 macro, the value of
151 .I ap
152 is undefined after the call.
153 See
154 .BR stdarg (3).
155 .PP
156 All of these functions write the output under the control of a
157 .I format
158 string that specifies how subsequent arguments (or arguments accessed via
159 the variable-length argument facilities of
160 .BR stdarg (3))
161 are converted for output.
162 .PP
163 C99 and POSIX.1-2001 specify that the results are undefined if a call to
164 .BR sprintf (),
165 .BR snprintf (),
166 .BR vsprintf (),
167 or
168 .BR vsnprintf ()
169 would cause copying to take place between objects that overlap
170 (e.g., if the target string array and one of the supplied input arguments
171 refer to the same buffer).
172 See NOTES.
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
177 characters (not
178 .BR % ),
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
183 the character
184 .BR % ,
185 and ends with a
186 .IR "conversion specifier" .
187 In between there may be (in this order) zero or more
188 .IR flags ,
189 an optional minimum
190 .IR "field width" ,
191 an optional
192 .I precision
193 and an optional
194 .IR "length modifier" .
195 .PP
196 The overall syntax of a conversion specification is:
197 .PP
198 .in +4n
199 .nf
200 %[$][flags][width][.precision][length modifier]conversion
201 .fi
202 .in
203 .PP
204 The arguments must correspond properly (after type promotion) with the
205 conversion specifier.
206 By default, the arguments are used in the order
207 given, where each \(aq*\(aq (see
208 .I "Field width"
209 and
210 .I Precision
211 below) and each conversion specifier asks for the next
212 argument (and it is an error if insufficiently many arguments are given).
213 One can also specify explicitly which argument is taken,
214 at each place where an argument is required, by writing "%m$" instead
215 of \(aq%\(aq and "*m$" instead of \(aq*\(aq,
216 where the decimal integer \fIm\fP denotes
217 the position in the argument list of the desired argument, indexed starting
218 from 1.
219 Thus,
220 .PP
221 .in +4n
222 .EX
223 printf("%*d", width, num);
224 .EE
225 .in
226 .PP
227 and
228 .PP
229 .in +4n
230 .EX
231 printf("%2$*1$d", width, num);
232 .EE
233 .in
234 .PP
235 are equivalent.
236 The second style allows repeated references to the
237 same argument.
238 The C99 standard does not include the style using \(aq$\(aq,
239 which comes from the Single UNIX Specification.
240 If the style using
241 \(aq$\(aq is used, it must be used throughout for all conversions taking an
242 argument and all width and precision arguments, but it may be mixed
243 with "%%" formats, which do not consume an argument.
244 There may be no
245 gaps in the numbers of arguments specified using \(aq$\(aq; for example, if
246 arguments 1 and 3 are specified, argument 2 must also be specified
247 somewhere in the format string.
248 .PP
249 For some numeric conversions a radix character ("decimal point") or
250 thousands' grouping character is used.
251 The actual character used
252 depends on the
253 .B LC_NUMERIC
254 part of the locale.
255 (See
256 .BR setlocale (3).)
257 The POSIX locale
258 uses \(aq.\(aq as radix character, and does not have a grouping character.
259 Thus,
260 .PP
261 .in +4n
262 .EX
263 printf("%\(aq.2f", 1234567.89);
264 .EE
265 .in
266 .PP
267 results in "1234567.89" in the POSIX locale, in "1234567,89" in the
268 nl_NL locale, and in "1.234.567,89" in the da_DK locale.
269 .SS Flag characters
270 The character % is followed by zero or more of the following flags:
271 .TP
272 .B #
273 The value should be converted to an "alternate form".
274 For
275 .B o
276 conversions, the first character of the output string is made zero
277 (by prefixing a 0 if it was not zero already).
278 For
279 .B x
280 and
281 .B X
282 conversions, a nonzero result has the string "0x" (or "0X" for
283 .B X
284 conversions) prepended to it.
285 For
286 .BR a ,
287 .BR A ,
288 .BR e ,
289 .BR E ,
290 .BR f ,
291 .BR F ,
292 .BR g ,
293 and
294 .B G
295 conversions, the result will always contain a decimal point, even if no
296 digits follow it (normally, a decimal point appears in the results of those
297 conversions only if a digit follows).
298 For
299 .B g
300 and
301 .B G
302 conversions, trailing zeros are not removed from the result as they would
303 otherwise be.
304 For other conversions, the result is undefined.
305 .TP
306 .B \&0
307 The value should be zero padded.
308 For
309 .BR d ,
310 .BR i ,
311 .BR o ,
312 .BR u ,
313 .BR x ,
314 .BR X ,
315 .BR a ,
316 .BR A ,
317 .BR e ,
318 .BR E ,
319 .BR f ,
320 .BR F ,
321 .BR g ,
322 and
323 .B G
324 conversions, the converted value is padded on the left with zeros rather
325 than blanks.
326 If the
327 .B \&0
328 and
329 .B \-
330 flags both appear, the
331 .B \&0
332 flag is ignored.
333 If a precision is given with a numeric conversion
334 .RB ( d ,
335 .BR i ,
336 .BR o ,
337 .BR u ,
338 .BR x ,
339 and
340 .BR X ),
341 the
342 .B \&0
343 flag is ignored.
344 For other conversions, the behavior is undefined.
345 .TP
346 .B \-
347 The converted value is to be left adjusted on the field boundary.
348 (The default is right justification.)
349 The converted value is padded on the right with blanks, rather
350 than on the left with blanks or zeros.
351 A
352 .B \-
353 overrides a
354 .B \&0
355 if both are given.
356 .TP
357 .B \(aq \(aq
358 (a space) A blank should be left before a positive number
359 (or empty string) produced by a signed conversion.
360 .TP
361 .B +
362 A sign (+ or \-) should always be placed before a number produced by a signed
363 conversion.
364 By default, a sign is used only for negative numbers.
365 A
366 .B +
367 overrides a space if both are used.
368 .PP
369 The five flag characters above are defined in the C99 standard.
370 The Single UNIX Specification specifies one further flag character.
371 .TP
372 .B \(aq
373 For decimal conversion
374 .RB ( i ,
375 .BR d ,
376 .BR u ,
377 .BR f ,
378 .BR F ,
379 .BR g ,
380 .BR G )
381 the output is to be grouped with thousands' grouping characters
382 if the locale information indicates any.
383 (See
384 .BR setlocale (3).)
385 Note that many versions of
386 .BR gcc (1)
387 cannot parse this option and will issue a warning.
388 (SUSv2 did not
389 include \fI%\(aqF\fP, but SUSv3 added it.)
390 .PP
391 glibc 2.2 adds one further flag character.
392 .TP
393 .B I
394 For decimal integer conversion
395 .RB ( i ,
396 .BR d ,
397 .BR u )
398 the output uses the locale's alternative output digits, if any.
399 For example, since glibc 2.2.3 this will give Arabic-Indic digits
400 in the Persian ("fa_IR") locale.
401 .\" outdigits keyword in locale file
402 .SS Field width
403 An optional decimal digit string (with nonzero first digit) specifying
404 a minimum field width.
405 If the converted value has fewer characters
406 than the field width, it will be padded with spaces on the left
407 (or right, if the left-adjustment flag has been given).
408 Instead of a decimal digit string one may write "*" or "*m$"
409 (for some decimal integer \fIm\fP) to specify that the field width
410 is given in the next argument, or in the \fIm\fP-th argument, respectively,
411 which must be of type
412 .IR int .
413 A negative field width is taken as a \(aq\-\(aq flag followed by a
414 positive field width.
415 In no case does a nonexistent or small field width cause truncation of a
416 field; if the result of a conversion is wider than the field width, the
417 field is expanded to contain the conversion result.
418 .SS Precision
419 An optional precision, in the form of a period (\(aq.\(aq) followed by an
420 optional decimal digit string.
421 Instead of a decimal digit string one may write "*" or "*m$"
422 (for some decimal integer \fIm\fP) to specify that the precision
423 is given in the next argument, or in the \fIm\fP-th argument, respectively,
424 which must be of type
425 .IR int .
426 If the precision is given as just \(aq.\(aq, the precision is taken to
427 be zero.
428 A negative precision is taken as if the precision were omitted.
429 This gives the minimum number of digits to appear for
430 .BR d ,
431 .BR i ,
432 .BR o ,
433 .BR u ,
434 .BR x ,
435 and
436 .B X
437 conversions, the number of digits to appear after the radix character for
438 .BR a ,
439 .BR A ,
440 .BR e ,
441 .BR E ,
442 .BR f ,
443 and
444 .B F
445 conversions, the maximum number of significant digits for
446 .B g
447 and
448 .B G
449 conversions, or the maximum number of characters to be printed from a
450 string for
451 .B s
452 and
453 .B S
454 conversions.
455 .SS Length modifier
456 Here, "integer conversion" stands for
457 .BR d ,
458 .BR i ,
459 .BR o ,
460 .BR u ,
461 .BR x ,
462 or
463 .B X
464 conversion.
465 .TP
466 .B hh
467 A following integer conversion corresponds to a
468 .I signed char
469 or
470 .I unsigned char
471 argument, or a following
472 .B n
473 conversion corresponds to a pointer to a
474 .I signed char
475 argument.
476 .TP
477 .B h
478 A following integer conversion corresponds to a
479 .I short
480 or
481 .I unsigned short
482 argument, or a following
483 .B n
484 conversion corresponds to a pointer to a
485 .I short
486 argument.
487 .TP
488 .B l
489 (ell) A following integer conversion corresponds to a
490 .I long
491 or
492 .I unsigned long
493 argument, or a following
494 .B n
495 conversion corresponds to a pointer to a
496 .I long
497 argument, or a following
498 .B c
499 conversion corresponds to a
500 .I wint_t
501 argument, or a following
502 .B s
503 conversion corresponds to a pointer to
504 .I wchar_t
505 argument.
506 .TP
507 .B ll
508 (ell-ell).
509 A following integer conversion corresponds to a
510 .I long long
511 or
512 .I unsigned long long
513 argument, or a following
514 .B n
515 conversion corresponds to a pointer to a
516 .I long long
517 argument.
518 .TP
519 .B q
520 A synonym for
521 .BR ll .
522 This is a nonstandard extension, derived from BSD;
523 avoid its use in new code.
524 .TP
525 .B L
526 A following
527 .BR a ,
528 .BR A ,
529 .BR e ,
530 .BR E ,
531 .BR f ,
532 .BR F ,
533 .BR g ,
534 or
535 .B G
536 conversion corresponds to a
537 .I long double
538 argument.
539 (C99 allows %LF, but SUSv2 does not.)
540 .TP
541 .B j
542 A following integer conversion corresponds to an
543 .I intmax_t
544 or
545 .I uintmax_t
546 argument, or a following
547 .B n
548 conversion corresponds to a pointer to an
549 .I intmax_t
550 argument.
551 .TP
552 .B z
553 A following integer conversion corresponds to a
554 .I size_t
555 or
556 .I ssize_t
557 argument, or a following
558 .B n
559 conversion corresponds to a pointer to a
560 .I size_t
561 argument.
562 .TP
563 .B Z
564 A nonstandard synonym for
565 .BR z
566 that predates the appearance of
567 .BR z .
568 Do not use in new code.
569 .TP
570 .B t
571 A following integer conversion corresponds to a
572 .I ptrdiff_t
573 argument, or a following
574 .B n
575 conversion corresponds to a pointer to a
576 .I ptrdiff_t
577 argument.
578 .PP
579 SUSv3 specifies all of the above,
580 except for those modifiers explicitly noted as being nonstandard extensions.
581 SUSv2 specified only the length modifiers
582 .B h
583 (in
584 .BR hd ,
585 .BR hi ,
586 .BR ho ,
587 .BR hx ,
588 .BR hX ,
589 .BR hn )
590 and
591 .B l
592 (in
593 .BR ld ,
594 .BR li ,
595 .BR lo ,
596 .BR lx ,
597 .BR lX ,
598 .BR ln ,
599 .BR lc ,
600 .BR ls )
601 and
602 .B L
603 (in
604 .BR Le ,
605 .BR LE ,
606 .BR Lf ,
607 .BR Lg ,
608 .BR LG ).
609 .PP
610 As a nonstandard extension, the GNU implementations treats
611 .B ll
612 and
613 .B L
614 as synonyms, so that one can, for example, write
615 .BR llg
616 (as a synonym for the standards-compliant
617 .BR Lg )
618 and
619 .BR Ld
620 (as a synonym for the standards compliant
621 .BR lld ).
622 Such usage is nonportable.
623 .\"
624 .SS Conversion specifiers
625 A character that specifies the type of conversion to be applied.
626 The conversion specifiers and their meanings are:
627 .TP
628 .BR d ", " i
629 The
630 .I int
631 argument is converted to signed decimal notation.
632 The precision, if any, gives the minimum number of digits
633 that must appear; if the converted value requires fewer digits, it is
634 padded on the left with zeros.
635 The default precision is 1.
636 When 0 is printed with an explicit precision 0, the output is empty.
637 .TP
638 .BR o ", " u ", " x ", " X
639 The
640 .I "unsigned int"
641 argument is converted to unsigned octal
642 .RB ( o ),
643 unsigned decimal
644 .RB ( u ),
645 or unsigned hexadecimal
646 .RB ( x
647 and
648 .BR X )
649 notation.
650 The letters
651 .B abcdef
652 are used for
653 .B x
654 conversions; the letters
655 .B ABCDEF
656 are used for
657 .B X
658 conversions.
659 The precision, if any, gives the minimum number of digits
660 that must appear; if the converted value requires fewer digits, it is
661 padded on the left with zeros.
662 The default precision is 1.
663 When 0 is printed with an explicit precision 0, the output is empty.
664 .TP
665 .BR e ", " E
666 The
667 .I double
668 argument is rounded and converted in the style
669 .RB [\-]d \&. ddd e \(+-dd
670 where there is one digit (which is nonzero if the argument is nonzero)
671 before the decimal-point character and the number
672 of digits after it is equal to the precision; if the precision is missing,
673 it is taken as 6; if the precision is zero, no decimal-point character
674 appears.
675 An
676 .B E
677 conversion uses the letter
678 .B E
679 (rather than
680 .BR e )
681 to introduce the exponent.
682 The exponent always contains at least two
683 digits; if the value is zero, the exponent is 00.
684 .TP
685 .BR f ", " F
686 The
687 .I double
688 argument is rounded and converted to decimal notation in the style
689 .RB [\-]ddd \&. ddd,
690 where the number of digits after the decimal-point character is equal to
691 the precision specification.
692 If the precision is missing, it is taken as
693 6; if the precision is explicitly zero, no decimal-point character appears.
694 If a decimal point appears, at least one digit appears before it.
695 .IP
696 (SUSv2 does not know about
697 .B F
698 and says that character string representations for infinity and NaN
699 may be made available.
700 SUSv3 adds a specification for
701 .BR F .
702 The C99 standard specifies "[\-]inf" or "[\-]infinity"
703 for infinity, and a string starting with "nan" for NaN, in the case of
704 .B f
705 conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of
706 .B F
707 conversion.)
708 .TP
709 .BR g ", " G
710 The
711 .I double
712 argument is converted in style
713 .B f
714 or
715 .B e
716 (or
717 .B F
718 or
719 .B E
720 for
721 .B G
722 conversions).
723 The precision specifies the number of significant digits.
724 If the precision is missing, 6 digits are given; if the precision is zero,
725 it is treated as 1.
726 Style
727 .B e
728 is used if the exponent from its conversion is less than \-4 or greater
729 than or equal to the precision.
730 Trailing zeros are removed from the
731 fractional part of the result; a decimal point appears only if it is
732 followed by at least one digit.
733 .TP
734 .BR a ", " A
735 (C99; not in SUSv2, but added in SUSv3)
736 For
737 .B a
738 conversion, the
739 .I double
740 argument is converted to hexadecimal notation (using the letters abcdef)
741 in the style
742 .RB [\-] 0x h \&. hhhh p \(+-d;
743 for
744 .B A
745 conversion the prefix
746 .BR 0X ,
747 the letters ABCDEF, and the exponent separator
748 .B P
749 is used.
750 There is one hexadecimal digit before the decimal point,
751 and the number of digits after it is equal to the precision.
752 The default precision suffices for an exact representation of the value
753 if an exact representation in base 2 exists
754 and otherwise is sufficiently large to distinguish values of type
755 .IR double .
756 The digit before the decimal point is unspecified for nonnormalized
757 numbers, and nonzero but otherwise unspecified for normalized numbers.
758 The exponent always contains at least one
759 digit; if the value is zero, the exponent is 0.
760 .TP
761 .B c
762 If no
763 .B l
764 modifier is present, the
765 .I int
766 argument is converted to an
767 .IR "unsigned char" ,
768 and the resulting character is written.
769 If an
770 .B l
771 modifier is present, the
772 .I wint_t
773 (wide character) argument is converted to a multibyte sequence by a call
774 to the
775 .BR wcrtomb (3)
776 function, with a conversion state starting in the initial state, and the
777 resulting multibyte string is written.
778 .TP
779 .B s
780 If no
781 .B l
782 modifier is present: the
783 .I "const char\ *"
784 argument is expected to be a pointer to an array of character type (pointer
785 to a string).
786 Characters from the array are written up to (but not
787 including) a terminating null byte (\(aq\e0\(aq);
788 if a precision is specified, no more than the number specified
789 are written.
790 If a precision is given, no null byte need be present;
791 if the precision is not specified, or is greater than the size of the
792 array, the array must contain a terminating null byte.
793 .IP
794 If an
795 .B l
796 modifier is present: the
797 .I "const wchar_t\ *"
798 argument is expected to be a pointer to an array of wide characters.
799 Wide characters from the array are converted to multibyte characters
800 (each by a call to the
801 .BR wcrtomb (3)
802 function, with a conversion state starting in the initial state before
803 the first wide character), up to and including a terminating null
804 wide character.
805 The resulting multibyte characters are written up to
806 (but not including) the terminating null byte.
807 If a precision is
808 specified, no more bytes than the number specified are written, but
809 no partial multibyte characters are written.
810 Note that the precision
811 determines the number of
812 .I bytes
813 written, not the number of
814 .I wide characters
815 or
816 .IR "screen positions" .
817 The array must contain a terminating null wide character, unless a
818 precision is given and it is so small that the number of bytes written
819 exceeds it before the end of the array is reached.
820 .TP
821 .B C
822 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
823 Synonym for
824 .BR lc .
825 Don't use.
826 .TP
827 .B S
828 (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
829 Synonym for
830 .BR ls .
831 Don't use.
832 .TP
833 .B p
834 The
835 .I "void\ *"
836 pointer argument is printed in hexadecimal (as if by
837 .B %#x
838 or
839 .BR %#lx ).
840 .TP
841 .B n
842 The number of characters written so far is stored into the integer
843 pointed to by the corresponding argument.
844 That argument shall be an
845 .IR "int\ *" ,
846 or variant whose size matches the (optionally)
847 supplied integer length modifier.
848 No argument is converted.
849 (This specifier is not supported by the bionic C library.)
850 The behavior is undefined if the conversion specification includes
851 any flags, a field width, or a precision.
852 .TP
853 .B m
854 (Glibc extension; supported by uClibc and musl.)
855 Print output of
856 .IR strerror(errno) .
857 No argument is required.
858 .TP
859 .B %
860 A \(aq%\(aq is written.
861 No argument is converted.
862 The complete conversion
863 specification is \(aq%%\(aq.
864 .SH RETURN VALUE
865 Upon successful return, these functions return the number of characters
866 printed (excluding the null byte used to end output to strings).
867 .PP
868 The functions
869 .BR snprintf ()
870 and
871 .BR vsnprintf ()
872 do not write more than
873 .I size
874 bytes (including the terminating null byte (\(aq\e0\(aq)).
875 If the output was truncated due to this limit, then the return value
876 is the number of characters (excluding the terminating null byte)
877 which would have been written to the final string if enough space
878 had been available.
879 Thus, a return value of
880 .I size
881 or more means that the output was truncated.
882 (See also below under NOTES.)
883 .PP
884 If an output error is encountered, a negative value is returned.
885 .SH ATTRIBUTES
886 For an explanation of the terms used in this section, see
887 .BR attributes (7).
888 .ad l
889 .nh
890 .TS
891 allbox;
892 lbx lb lb
893 l l l.
894 Interface Attribute Value
895 T{
896 .BR printf (),
897 .BR fprintf (),
898 .BR sprintf (),
899 .BR snprintf (),
900 .BR vprintf (),
901 .BR vfprintf (),
902 .BR vsprintf (),
903 .BR vsnprintf ()
904 T} Thread safety MT-Safe locale
905 .TE
906 .hy
907 .ad
908 .sp 1
909 .SH CONFORMING TO
910 .BR fprintf (),
911 .BR printf (),
912 .BR sprintf (),
913 .BR vprintf (),
914 .BR vfprintf (),
915 .BR vsprintf ():
916 POSIX.1-2001, POSIX.1-2008, C89, C99.
917 .PP
918 .BR snprintf (),
919 .BR vsnprintf ():
920 POSIX.1-2001, POSIX.1-2008, C99.
921 .PP
922 The
923 .BR dprintf ()
924 and
925 .BR vdprintf ()
926 functions were originally GNU extensions that were later standardized
927 in POSIX.1-2008.
928 .PP
929 Concerning the return value of
930 .BR snprintf (),
931 SUSv2 and C99 contradict each other: when
932 .BR snprintf ()
933 is called with
934 .IR size =0
935 then SUSv2 stipulates an unspecified return value less than 1,
936 while C99 allows
937 .I str
938 to be NULL in this case, and gives the return value (as always)
939 as the number of characters that would have been written in case
940 the output string has been large enough.
941 POSIX.1-2001 and later align their specification of
942 .BR snprintf ()
943 with C99.
944 .\" .PP
945 .\" Linux libc4 knows about the five C standard flags.
946 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
947 .\" and the conversions
948 .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
949 .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
950 .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
951 .\" where \fBF\fP is a synonym for \fBf\fP.
952 .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
953 .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
954 .\" (This is bad, and caused serious bugs later, when
955 .\" support for \fB%D\fP disappeared.)
956 .\" No locale-dependent radix character,
957 .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
958 .\" .PP
959 .\" Linux libc5 knows about the five C standard flags and the \(aq flag,
960 .\" locale, "%m$" and "*m$".
961 .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
962 .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
963 .\" both for \fIlong double\fP and for \fIlong long\fP (this is a bug).
964 .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
965 .\" but adds the conversion character
966 .\" .BR m ,
967 .\" which outputs
968 .\" .IR strerror(errno) .
969 .\" .PP
970 .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
971 .PP
972 glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
973 and conversion characters \fBa\fP and \fBA\fP.
974 .PP
975 glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
976 and the flag character \fBI\fP.
977 .SH NOTES
978 Some programs imprudently rely on code such as the following
979 .PP
980 sprintf(buf, "%s some further text", buf);
981 .PP
982 to append text to
983 .IR buf .
984 However, the standards explicitly note that the results are undefined
985 if source and destination buffers overlap when calling
986 .BR sprintf (),
987 .BR snprintf (),
988 .BR vsprintf (),
989 and
990 .BR vsnprintf ().
991 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
992 Depending on the version of
993 .BR gcc (1)
994 used, and the compiler options employed, calls such as the above will
995 .B not
996 produce the expected results.
997 .PP
998 The glibc implementation of the functions
999 .BR snprintf ()
1000 and
1001 .BR vsnprintf ()
1002 conforms to the C99 standard, that is, behaves as described above,
1003 since glibc version 2.1.
1004 Until glibc 2.0.6, they would return \-1
1005 when the output was truncated.
1006 .\" .SH HISTORY
1007 .\" UNIX V7 defines the three routines
1008 .\" .BR printf (),
1009 .\" .BR fprintf (),
1010 .\" .BR sprintf (),
1011 .\" and has the flag \-, the width or precision *, the length modifier l,
1012 .\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
1013 .\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
1014 .\" #, + and <space> and no longer mentions D,O,U,X.
1015 .\" 2.11BSD has
1016 .\" .BR vprintf (),
1017 .\" .BR vfprintf (),
1018 .\" .BR vsprintf (),
1019 .\" and warns not to use D,O,U,X.
1020 .\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
1021 .\" and the conversions n, p, E, G, X (with current meaning)
1022 .\" and deprecates D,O,U.
1023 .\" 4.4BSD introduces the functions
1024 .\" .BR snprintf ()
1025 .\" and
1026 .\" .BR vsnprintf (),
1027 .\" and the length modifier q.
1028 .\" FreeBSD also has functions
1029 .\" .BR asprintf ()
1030 .\" and
1031 .\" .BR vasprintf (),
1032 .\" that allocate a buffer large enough for
1033 .\" .BR sprintf ().
1034 .\" In glibc there are functions
1035 .\" .BR dprintf ()
1036 .\" and
1037 .\" .BR vdprintf ()
1038 .\" that print to a file descriptor instead of a stream.
1039 .SH BUGS
1040 Because
1041 .BR sprintf ()
1042 and
1043 .BR vsprintf ()
1044 assume an arbitrarily long string, callers must be careful not to overflow
1045 the actual space; this is often impossible to assure.
1046 Note that the length
1047 of the strings produced is locale-dependent and difficult to predict.
1048 Use
1049 .BR snprintf ()
1050 and
1051 .BR vsnprintf ()
1052 instead (or
1053 .BR asprintf (3)
1054 and
1055 .BR vasprintf (3)).
1056 .\" .PP
1057 .\" Linux libc4.[45] does not have a
1058 .\" .BR snprintf (),
1059 .\" but provides a libbsd that contains an
1060 .\" .BR snprintf ()
1061 .\" equivalent to
1062 .\" .BR sprintf (),
1063 .\" that is, one that ignores the
1064 .\" .I size
1065 .\" argument.
1066 .\" Thus, the use of
1067 .\" .BR snprintf ()
1068 .\" with early libc4 leads to serious security problems.
1069 .PP
1070 Code such as
1071 .BI printf( foo );
1072 often indicates a bug, since
1073 .I foo
1074 may contain a % character.
1075 If
1076 .I foo
1077 comes from untrusted user input, it may contain \fB%n\fP, causing the
1078 .BR printf ()
1079 call to write to memory and creating a security hole.
1080 .\" .PP
1081 .\" Some floating-point conversions under early libc4
1082 .\" caused memory leaks.
1083 .SH EXAMPLES
1084 To print
1085 .I Pi
1086 to five decimal places:
1087 .PP
1088 .in +4n
1089 .EX
1090 #include <math.h>
1091 #include <stdio.h>
1092 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
1093 .EE
1094 .in
1095 .PP
1096 To print a date and time in the form "Sunday, July 3, 10:02",
1097 where
1098 .I weekday
1099 and
1100 .I month
1101 are pointers to strings:
1102 .PP
1103 .in +4n
1104 .EX
1105 #include <stdio.h>
1106 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
1107 weekday, month, day, hour, min);
1108 .EE
1109 .in
1110 .PP
1111 Many countries use the day-month-year order.
1112 Hence, an internationalized version must be able to print
1113 the arguments in an order specified by the format:
1114 .PP
1115 .in +4n
1116 .EX
1117 #include <stdio.h>
1118 fprintf(stdout, format,
1119 weekday, month, day, hour, min);
1120 .EE
1121 .in
1122 .PP
1123 where
1124 .I format
1125 depends on locale, and may permute the arguments.
1126 With the value:
1127 .PP
1128 .in +4n
1129 .EX
1130 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
1131 .EE
1132 .in
1133 .PP
1134 one might obtain "Sonntag, 3. Juli, 10:02".
1135 .PP
1136 To allocate a sufficiently large string and print into it
1137 (code correct for both glibc 2.0 and glibc 2.1):
1138 .PP
1139 .EX
1140 #include <stdio.h>
1141 #include <stdlib.h>
1142 #include <stdarg.h>
1144 char *
1145 make_message(const char *fmt, ...)
1146 {
1147 int n = 0;
1148 size_t size = 0;
1149 char *p = NULL;
1150 va_list ap;
1152 /* Determine required size. */
1154 va_start(ap, fmt);
1155 n = vsnprintf(p, size, fmt, ap);
1156 va_end(ap);
1158 if (n < 0)
1159 return NULL;
1161 size = (size_t) n + 1; /* One extra byte for \(aq\e0\(aq */
1162 p = malloc(size);
1163 if (p == NULL)
1164 return NULL;
1166 va_start(ap, fmt);
1167 n = vsnprintf(p, size, fmt, ap);
1168 va_end(ap);
1170 if (n < 0) {
1171 free(p);
1172 return NULL;
1173 }
1175 return p;
1176 }
1177 .EE
1178 .PP
1179 If truncation occurs in glibc versions prior to 2.0.6, this is treated as an
1180 error instead of being handled gracefully.
1181 .SH SEE ALSO
1182 .BR printf (1),
1183 .BR asprintf (3),
1184 .BR puts (3),
1185 .BR scanf (3),
1186 .BR setlocale (3),
1187 .BR strfromd (3),
1188 .BR wcrtomb (3),
1189 .BR wprintf (3),
1190 .BR locale (5)