1 .\" Copyright (c) 1990, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Chris Torek and the American National Standards Committee X3,
6 .\" on Information Processing Systems.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)printf.3 8.1 (Berkeley) 6/4/93
33 .\" $FreeBSD: head/lib/libc/stdio/printf.3 303524 2016-07-30 01:00:16Z bapt $
51 .Nd formatted output conversion
57 .Fn printf "const char * restrict format" ...
59 .Fn fprintf "FILE * restrict stream" "const char * restrict format" ...
61 .Fn sprintf "char * restrict str" "const char * restrict format" ...
63 .Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
65 .Fn asprintf "char **ret" "const char *format" ...
67 .Fn dprintf "int" "const char * restrict format" ...
70 .Fn vprintf "const char * restrict format" "va_list ap"
72 .Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap"
74 .Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap"
76 .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
78 .Fn vasprintf "char **ret" "const char *format" "va_list ap"
80 .Fn vdprintf "int fd" "const char * restrict format" "va_list ap"
84 family of functions produces output according to a
94 the standard output stream;
98 write output to the given output
103 write output to the given file descriptor;
109 write to the character string
115 dynamically allocate a new string with
118 These functions write the output under the control of a
120 string that specifies how subsequent arguments
121 (or arguments accessed via the variable-length argument facilities of
123 are converted for output.
132 to be a pointer to a buffer sufficiently large to hold the formatted string.
133 This pointer should be passed to
135 to release the allocated storage when it is no longer needed.
136 If sufficient space cannot be allocated,
140 will return \-1 and set
153 of the characters printed into the output string
156 character then gets the terminating
158 if the return value is greater than or equal to the
160 argument, the string was too short
161 and some of the printed characters were discarded.
162 The output is always null-terminated, unless
177 The format string is composed of zero or more directives:
182 which are copied unchanged to the output stream;
183 and conversion specifications, each of which results
184 in fetching zero or more subsequent arguments.
185 Each conversion specification is introduced by
189 The arguments must correspond properly (after type promotion)
190 with the conversion specifier.
193 the following appear in sequence:
196 An optional field, consisting of a decimal digit string followed by a
198 specifying the next argument to access.
199 If this field is not provided, the argument following the last
200 argument accessed will be used.
201 Arguments are numbered starting at
203 If unaccessed arguments in the format string are interspersed with ones that
204 are accessed the results will be indeterminate.
206 Zero or more of the following flags:
207 .Bl -tag -width ".So \ Sc (space)"
209 The value should be converted to an
212 .Cm c , d , i , n , p , s ,
215 conversions, this option has no effect.
218 conversions, the precision of the number is increased to force the first
219 character of the output string to a zero.
224 conversions, a non-zero result has the string
230 conversions) prepended to it.
232 .Cm a , A , e , E , f , F , g ,
235 conversions, the result will always contain a decimal point, even if no
236 digits follow it (normally, a decimal point appears in the results of
237 those conversions only if a digit follows).
242 conversions, trailing zeros are not removed from the result as they
244 .It So Cm 0 Sc (zero)
246 For all conversions except
248 the converted value is padded on the left with zeros rather than blanks.
249 If a precision is given with a numeric conversion
250 .Cm ( d , i , o , u , i , x ,
257 A negative field width flag;
258 the converted value is to be left adjusted on the field boundary.
261 conversions, the converted value is padded on the right with blanks,
262 rather than on the left with blanks or zeros.
268 .It So "\ " Sc (space)
269 A blank should be left before a positive number
270 produced by a signed conversion
271 .Cm ( a , A , d , e , E , f , F , g , G ,
275 A sign must always be placed before a
276 number produced by a signed conversion.
279 overrides a space if both are used.
280 .It So "'" Sc (apostrophe)
285 or the integral portion of a floating point conversion
289 should be grouped and separated by thousands using
290 the non-monetary separator returned by
294 An optional decimal digit string specifying a minimum field width.
295 If the converted value has fewer characters than the field width, it will
296 be padded with spaces on the left (or right, if the left-adjustment
297 flag has been given) to fill out
300 An optional precision, in the form of a period
303 optional digit string.
304 If the digit string is omitted, the precision is taken as zero.
305 This gives the minimum number of digits to appear for
306 .Cm d , i , o , u , x ,
309 conversions, the number of digits to appear after the decimal-point for
310 .Cm a , A , e , E , f ,
313 conversions, the maximum number of significant digits for
317 conversions, or the maximum number of characters to be printed from a
322 An optional length modifier, that specifies the size of the argument.
323 The following length modifiers are valid for the
324 .Cm d , i , n , o , u , x ,
328 .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
329 .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
330 .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
331 .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
332 .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
333 .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
334 .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
335 .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
336 .It Cm z Ta (see note) Ta Vt size_t Ta (see note)
337 .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
343 modifier, when applied to a
347 conversion, indicates that the argument is of an unsigned type
348 equivalent in size to a
352 modifier, when applied to a
356 conversion, indicates that the argument is of a signed type equivalent in
359 Similarly, when applied to an
361 conversion, it indicates that the argument is a pointer to a signed type
362 equivalent in size to a
365 The following length modifier is valid for the
366 .Cm a , A , e , E , f , F , g ,
370 .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
371 .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
372 .It Cm l No (ell) Ta Vt double
373 (ignored, same behavior as without it)
374 .It Cm L Ta Vt "long double"
377 The following length modifier is valid for the
382 .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
383 .It Sy Modifier Ta Cm c Ta Cm s
384 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
387 A character that specifies the type of conversion to be applied.
390 A field width or precision, or both, may be indicated by
393 or an asterisk followed by one or more decimal digits and a
399 argument supplies the field width or precision.
400 A negative field width is treated as a left adjustment flag followed by a
401 positive field width; a negative precision is treated as though it were
403 If a single format directive mixes positional
405 and non-positional arguments, the results are undefined.
407 The conversion specifiers and their meanings are:
408 .Bl -tag -width ".Cm diouxX"
412 (or appropriate variant) argument is converted to signed decimal
420 or unsigned hexadecimal
429 conversions; the letters
434 The precision, if any, gives the minimum number of digits that must
435 appear; if the converted value requires fewer digits, it is padded on
440 argument is converted to signed decimal, unsigned octal, or unsigned
441 decimal, as if the format had been
446 These conversion characters are deprecated, and will eventually disappear.
450 argument is rounded and converted in the style
452 .Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd
454 where there is one digit before the
455 decimal-point character
456 and the number of digits after it is equal to the precision;
457 if the precision is missing,
458 it is taken as 6; if the precision is
459 zero, no decimal-point character appears.
462 conversion uses the letter
466 to introduce the exponent.
467 The exponent always contains at least two digits; if the value is zero,
471 .Cm a , A , e , E , f , F , g ,
474 conversions, positive and negative infinity are represented as
478 respectively when using the lowercase conversion character, and
482 respectively when using the uppercase conversion character.
483 Similarly, NaN is represented as
485 when using the lowercase conversion, and
487 when using the uppercase conversion.
491 argument is rounded and converted to decimal notation in the style
493 .Oo \- Oc Ar ddd Li \&. Ar ddd ,
495 where the number of digits after the decimal-point character
496 is equal to the precision specification.
497 If the precision is missing, it is taken as 6; if the precision is
498 explicitly zero, no decimal-point character appears.
499 If a decimal point appears, at least one digit appears before it.
503 argument is converted in style
514 The precision specifies the number of significant digits.
515 If the precision is missing, 6 digits are given; if the precision is zero,
519 is used if the exponent from its conversion is less than \-4 or greater than
520 or equal to the precision.
521 Trailing zeros are removed from the fractional part of the result; a
522 decimal point appears only if it is followed by at least one digit.
526 argument is rounded and converted to hexadecimal notation in the style
528 .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d ,
530 where the number of digits after the hexadecimal-point character
531 is equal to the precision specification.
532 If the precision is missing, it is taken as enough to represent
533 the floating-point number exactly, and no rounding occurs.
534 If the precision is zero, no hexadecimal-point character appears.
537 is a literal character
539 and the exponent consists of a positive or negative sign
540 followed by a decimal number representing an exponent of 2.
543 conversion uses the prefix
551 to represent the hex digits, and the letter
555 to separate the mantissa and exponent.
557 Note that there may be multiple valid ways to represent floating-point
558 numbers in this hexadecimal format.
560 .Li 0x1.92p+1 , 0x3.24p+0 , 0x6.48p-1 ,
565 and later always prints finite non-zero numbers using
567 as the digit before the hexadecimal point.
568 Zeroes are always represented with a mantissa of 0 (preceded by a
570 if appropriate) and an exponent of
581 argument is converted to an
582 .Vt "unsigned char" ,
583 and the resulting character is written.
587 (ell) modifier is used, the
589 argument shall be converted to a
591 and the (potentially multi-byte) sequence representing the
592 single wide character is written, including any shift sequences.
593 If a shift sequence is used, the shift state is also restored
594 to the original state after the character.
604 argument is expected to be a pointer to an array of character type (pointer
606 Characters from the array are written up to (but not including)
610 if a precision is specified, no more than the number specified are
612 If a precision is given, no null character
613 need be present; if the precision is not specified, or is greater than
614 the size of the array, the array must contain a terminating
620 (ell) modifier is used, the
622 argument is expected to be a pointer to an array of wide characters
623 (pointer to a wide string).
624 For each wide character in the string, the (potentially multi-byte)
625 sequence representing the
626 wide character is written, including any shift sequences.
627 If any shift sequence is used, the shift state is also restored
628 to the original state after the string.
629 Wide characters from the array are written up to (but not including)
633 if a precision is specified, no more than the number of bytes specified are
634 written (including shift sequences).
635 Partial characters are never written.
636 If a precision is given, no null character
637 need be present; if the precision is not specified, or is greater than
638 the number of bytes required to render the multibyte representation of
639 the string, the array must contain a terminating wide
645 pointer argument is printed in hexadecimal (as if by
650 The number of characters written so far is stored into the
651 integer indicated by the
653 (or variant) pointer argument.
654 No argument is converted.
659 No argument is converted.
660 The complete conversion specification
666 character is defined in the program's locale (category
669 In no case does a non-existent or small field width cause truncation of
670 a numeric field; if the result of a conversion is wider than the field
672 field is expanded to contain the conversion result.
674 These functions return the number of characters printed
675 (not including the trailing
677 used to end output to strings),
682 which return the number of characters that would have been printed if the
685 (again, not including the final
687 These functions return a negative value if an error occurs.
689 To print a date and time in the form
690 .Dq Li "Sunday, July 3, 10:02" ,
695 are pointers to strings:
696 .Bd -literal -offset indent
698 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
699 weekday, month, day, hour, min);
703 to five decimal places:
704 .Bd -literal -offset indent
707 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
710 To allocate a 128 byte string and print into it:
711 .Bd -literal -offset indent
715 char *newfmt(const char *fmt, ...)
719 if ((p = malloc(128)) == NULL)
722 (void) vsnprintf(p, 128, fmt, ap);
728 The conversion formats
733 are provided only for backward compatibility.
734 The effect of padding the
736 format with zeros (either by the
738 flag or by specifying a precision), and the benign effect (i.e., none)
745 conversions, as well as other
746 nonsensical combinations such as
748 are not standard; such combinations
751 In addition to the errors documented for the
755 family of functions may fail if:
758 An invalid wide character code was encountered.
760 Insufficient storage space is available.
766 or the return value would be too large to be represented by an
776 Subject to the caveats noted in the
791 With the same reservation, the
808 first appeared in the
811 These were implemented by
812 .An Peter Wemm Aq Mt peter@FreeBSD.org
815 but were later replaced with a different implementation
819 .An Todd C. Miller Aq Mt Todd.Miller@courtesan.com .
824 functions were added in
829 family of functions do not correctly handle multibyte characters in the
832 .Sh SECURITY CONSIDERATIONS
837 functions are easily misused in a manner which enables malicious users
838 to arbitrarily change a running program's functionality through
839 a buffer overflow attack.
844 assume an infinitely long string,
845 callers must be careful not to overflow the actual space;
846 this is often hard to assure.
847 For safety, programmers should use the
853 foo(const char *arbitrary_string, const char *and_another)
859 * This first sprintf is bad behavior. Do not use sprintf!
861 sprintf(onstack, "%s, %s", arbitrary_string, and_another);
864 * The following two lines demonstrate better use of
867 snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
877 family of functions are also easily misused in a manner
878 allowing malicious users to arbitrarily change a running program's
879 functionality by either causing the program
880 to print potentially sensitive data
881 .Dq "left on the stack" ,
882 or causing it to generate a memory fault or bus error
883 by dereferencing an invalid pointer.
886 can be used to write arbitrary data to potentially carefully-selected
888 Programmers are therefore strongly advised to never pass untrusted strings
891 argument, as an attacker can put format specifiers in the string
892 to mangle your stack,
893 leading to a possible security hole.
894 This holds true even if the string was built using a function like
896 as the resulting string may still contain user-supplied conversion specifiers
897 for later interpolation by
900 Always use the proper secure idiom:
902 .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"