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 .\" 4. 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
39 .Nm printf , fprintf , sprintf , snprintf , asprintf ,
40 .Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf
41 .Nd formatted output conversion
47 .Fn printf "const char * restrict format" ...
49 .Fn fprintf "FILE * restrict stream" "const char * restrict format" ...
51 .Fn sprintf "char * restrict str" "const char * restrict format" ...
53 .Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
55 .Fn asprintf "char **ret" "const char *format" ...
58 .Fn vprintf "const char * restrict format" "va_list ap"
60 .Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap"
62 .Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap"
64 .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
66 .Fn vasprintf "char **ret" "const char *format" "va_list ap"
70 family of functions produces output according to a
80 the standard output stream;
84 write output to the given output
91 write to the character string
97 dynamically allocate a new string with
100 These functions write the output under the control of a
102 string that specifies how subsequent arguments
103 (or arguments accessed via the variable-length argument facilities of
105 are converted for output.
107 These functions return the number of characters printed
108 (not including the trailing
110 used to end output to strings) or a negative value if an output error occurs,
115 which return the number of characters that would have been printed if the
118 (again, not including the final
128 to be a pointer to a buffer sufficiently large to hold the formatted string.
129 This pointer should be passed to
131 to release the allocated storage when it is no longer needed.
132 If sufficient space cannot be allocated,
136 will return \-1 and set
149 of the characters printed into the output string
152 character then gets the terminating
154 if the return value is greater than or equal to the
156 argument, the string was too short
157 and some of the printed characters were discarded.
158 The output is always null-terminated.
165 effectively assume an infinite
168 The format string is composed of zero or more directives:
173 which are copied unchanged to the output stream;
174 and conversion specifications, each of which results
175 in fetching zero or more subsequent arguments.
176 Each conversion specification is introduced by
180 The arguments must correspond properly (after type promotion)
181 with the conversion specifier.
184 the following appear in sequence:
187 An optional field, consisting of a decimal digit string followed by a
189 specifying the next argument to access.
190 If this field is not provided, the argument following the last
191 argument accessed will be used.
192 Arguments are numbered starting at
194 If unaccessed arguments in the format string are interspersed with ones that
195 are accessed the results will be indeterminate.
197 Zero or more of the following flags:
198 .Bl -tag -width ".So \ Sc (space)"
200 The value should be converted to an
203 .Cm c , d , i , n , p , s ,
206 conversions, this option has no effect.
209 conversions, the precision of the number is increased to force the first
210 character of the output string to a zero (except if a zero value is printed
211 with an explicit precision of zero).
216 conversions, a non-zero result has the string
222 conversions) prepended to it.
224 .Cm a , A , e , E , f , F , g ,
227 conversions, the result will always contain a decimal point, even if no
228 digits follow it (normally, a decimal point appears in the results of
229 those conversions only if a digit follows).
234 conversions, trailing zeros are not removed from the result as they
236 .It So Cm 0 Sc (zero)
238 For all conversions except
240 the converted value is padded on the left with zeros rather than blanks.
241 If a precision is given with a numeric conversion
242 .Cm ( d , i , o , u , i , x ,
249 A negative field width flag;
250 the converted value is to be left adjusted on the field boundary.
253 conversions, the converted value is padded on the right with blanks,
254 rather than on the left with blanks or zeros.
260 .It So "\ " Sc (space)
261 A blank should be left before a positive number
262 produced by a signed conversion
263 .Cm ( a , A , d , e , E , f , F , g , G ,
267 A sign must always be placed before a
268 number produced by a signed conversion.
271 overrides a space if both are used.
277 or the integral portion of a floating point conversion
281 should be grouped and separated by thousands using
282 the non-monetary separator returned by
286 An optional decimal digit string specifying a minimum field width.
287 If the converted value has fewer characters than the field width, it will
288 be padded with spaces on the left (or right, if the left-adjustment
289 flag has been given) to fill out
292 An optional precision, in the form of a period
295 optional digit string.
296 If the digit string is omitted, the precision is taken as zero.
297 This gives the minimum number of digits to appear for
298 .Cm d , i , o , u , x ,
301 conversions, the number of digits to appear after the decimal-point for
302 .Cm a , A , e , E , f ,
305 conversions, the maximum number of significant digits for
309 conversions, or the maximum number of characters to be printed from a
314 An optional length modifier, that specifies the size of the argument.
315 The following length modifiers are valid for the
316 .Cm d , i , n , o , u , x ,
320 .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
321 .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
322 .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
323 .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
324 .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
325 .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
326 .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
327 .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
328 .It Cm z Ta (see note) Ta Vt size_t Ta (see note)
329 .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
335 modifier, when applied to a
339 conversion, indicates that the argument is of an unsigned type
340 equivalent in size to a
344 modifier, when applied to a
348 conversion, indicates that the argument is of a signed type equivalent in
351 Similarly, when applied to an
353 conversion, it indicates that the argument is a pointer to a signed type
354 equivalent in size to a
357 The following length modifier is valid for the
358 .Cm a , A , e , E , f , F , g ,
362 .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
363 .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
364 .It Cm l No (ell) Ta Vt double
365 (ignored, same behavior as without it)
366 .It Cm L Ta Vt "long double"
369 The following length modifier is valid for the
374 .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
375 .It Sy Modifier Ta Cm c Ta Cm s
376 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
379 A character that specifies the type of conversion to be applied.
382 A field width or precision, or both, may be indicated by
385 or an asterisk followed by one or more decimal digits and a
391 argument supplies the field width or precision.
392 A negative field width is treated as a left adjustment flag followed by a
393 positive field width; a negative precision is treated as though it were
395 If a single format directive mixes positional
397 and non-positional arguments, the results are undefined.
399 The conversion specifiers and their meanings are:
400 .Bl -tag -width ".Cm diouxX"
404 (or appropriate variant) argument is converted to signed decimal
412 or unsigned hexadecimal
421 conversions; the letters
426 The precision, if any, gives the minimum number of digits that must
427 appear; if the converted value requires fewer digits, it is padded on
432 argument is converted to signed decimal, unsigned octal, or unsigned
433 decimal, as if the format had been
438 These conversion characters are deprecated, and will eventually disappear.
442 argument is rounded and converted in the style
444 .Oo \- Oc Ar d Li \&. Ar ddd Li e \\*[Pm] Ar dd
446 where there is one digit before the
447 decimal-point character
448 and the number of digits after it is equal to the precision;
449 if the precision is missing,
450 it is taken as 6; if the precision is
451 zero, no decimal-point character appears.
454 conversion uses the letter
458 to introduce the exponent.
459 The exponent always contains at least two digits; if the value is zero,
463 .Cm a , A , e , E , f , F , g ,
466 conversions, positive and negative infinity are represented as
470 respectively when using the lowercase conversion character, and
474 respectively when using the uppercase conversion character.
475 Similarly, NaN is represented as
477 when using the lowercase conversion, and
479 when using the uppercase conversion.
483 argument is rounded and converted to decimal notation in the style
485 .Oo \- Oc Ar ddd Li \&. Ar ddd ,
487 where the number of digits after the decimal-point character
488 is equal to the precision specification.
489 If the precision is missing, it is taken as 6; if the precision is
490 explicitly zero, no decimal-point character appears.
491 If a decimal point appears, at least one digit appears before it.
495 argument is converted in style
506 The precision specifies the number of significant digits.
507 If the precision is missing, 6 digits are given; if the precision is zero,
511 is used if the exponent from its conversion is less than \-4 or greater than
512 or equal to the precision.
513 Trailing zeros are removed from the fractional part of the result; a
514 decimal point appears only if it is followed by at least one digit.
518 argument is rounded and converted to hexadecimal notation in the style
520 .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \\*[Pm] Oc Ar d ,
522 where the number of digits after the hexadecimal-point character
523 is equal to the precision specification.
524 If the precision is missing, it is taken as enough to represent
525 the floating-point number exactly, and no rounding occurs.
526 If the precision is zero, no hexadecimal-point character appears.
529 is a literal character
531 and the exponent consists of a positive or negative sign
532 followed by a decimal number representing an exponent of 2.
535 conversion uses the prefix
543 to represent the hex digits, and the letter
547 to separate the mantissa and exponent.
549 Note that there may be multiple valid ways to represent floating-point
550 numbers in this hexadecimal format.
552 .Li 0x1.92p+1 , 0x3.24p+0 , 0x6.48p-1 ,
557 and later always prints finite non-zero numbers using
559 as the digit before the hexadecimal point.
560 Zeroes are always represented with a mantissa of 0 (preceded by a
562 if appropriate) and an exponent of
573 argument is converted to an
574 .Vt "unsigned char" ,
575 and the resulting character is written.
579 (ell) modifier is used, the
581 argument shall be converted to a
583 and the (potentially multi-byte) sequence representing the
584 single wide character is written, including any shift sequences.
585 If a shift sequence is used, the shift state is also restored
586 to the original state after the character.
596 argument is expected to be a pointer to an array of character type (pointer
598 Characters from the array are written up to (but not including)
602 if a precision is specified, no more than the number specified are
604 If a precision is given, no null character
605 need be present; if the precision is not specified, or is greater than
606 the size of the array, the array must contain a terminating
612 (ell) modifier is used, the
614 argument is expected to be a pointer to an array of wide characters
615 (pointer to a wide string).
616 For each wide character in the string, the (potentially multi-byte)
617 sequence representing the
618 wide character is written, including any shift sequences.
619 If any shift sequence is used, the shift state is also restored
620 to the original state after the string.
621 Wide characters from the array are written up to (but not including)
625 if a precision is specified, no more than the number of bytes specified are
626 written (including shift sequences).
627 Partial characters are never written.
628 If a precision is given, no null character
629 need be present; if the precision is not specified, or is greater than
630 the number of bytes required to render the multibyte representation of
631 the string, the array must contain a terminating wide
637 pointer argument is printed in hexadecimal (as if by
642 The number of characters written so far is stored into the
643 integer indicated by the
645 (or variant) pointer argument.
646 No argument is converted.
651 No argument is converted.
652 The complete conversion specification
658 character is defined in the program's locale (category
661 In no case does a non-existent or small field width cause truncation of
662 a numeric field; if the result of a conversion is wider than the field
664 field is expanded to contain the conversion result.
666 To print a date and time in the form
667 .Dq Li "Sunday, July 3, 10:02" ,
672 are pointers to strings:
673 .Bd -literal -offset indent
675 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
676 weekday, month, day, hour, min);
680 to five decimal places:
681 .Bd -literal -offset indent
684 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
687 To allocate a 128 byte string and print into it:
688 .Bd -literal -offset indent
692 char *newfmt(const char *fmt, ...)
696 if ((p = malloc(128)) == NULL)
699 (void) vsnprintf(p, 128, fmt, ap);
704 .Sh SECURITY CONSIDERATIONS
709 functions are easily misused in a manner which enables malicious users
710 to arbitrarily change a running program's functionality through
711 a buffer overflow attack.
716 assume an infinitely long string,
717 callers must be careful not to overflow the actual space;
718 this is often hard to assure.
719 For safety, programmers should use the
725 foo(const char *arbitrary_string, const char *and_another)
731 * This first sprintf is bad behavior. Do not use sprintf!
733 sprintf(onstack, "%s, %s", arbitrary_string, and_another);
736 * The following two lines demonstrate better use of
739 snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
749 family of functions are also easily misused in a manner
750 allowing malicious users to arbitrarily change a running program's
751 functionality by either causing the program
752 to print potentially sensitive data
753 .Dq "left on the stack" ,
754 or causing it to generate a memory fault or bus error
755 by dereferencing an invalid pointer.
758 can be used to write arbitrary data to potentially carefully-selected
760 Programmers are therefore strongly advised to never pass untrusted strings
763 argument, as an attacker can put format specifiers in the string
764 to mangle your stack,
765 leading to a possible security hole.
766 This holds true even if the string was built using a function like
768 as the resulting string may still contain user-supplied conversion specifiers
769 for later interpolation by
772 Always use the proper secure idiom:
774 .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"
776 In addition to the errors documented for the
780 family of functions may fail if:
783 An invalid wide character code was encountered.
785 Insufficient storage space is available.
794 Subject to the caveats noted in the
809 With the same reservation, the
820 first appeared in the
823 These were implemented by
824 .An Peter Wemm Aq peter@FreeBSD.org
827 but were later replaced with a different implementation
829 .An Todd C. Miller Aq Todd.Miller@courtesan.com
833 The conversion formats
838 are provided only for backward compatibility.
839 The effect of padding the
841 format with zeros (either by the
843 flag or by specifying a precision), and the benign effect (i.e., none)
850 conversions, as well as other
851 nonsensical combinations such as
853 are not standard; such combinations
858 family of functions do not correctly handle multibyte characters in the