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 , dprintf ,
40 .Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf, vdprintf
41 .Nd formatted output conversion
45 .Fd "#define _WITH_DPRINTF"
48 .Fn printf "const char * restrict format" ...
50 .Fn fprintf "FILE * restrict stream" "const char * restrict format" ...
52 .Fn sprintf "char * restrict str" "const char * restrict format" ...
54 .Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
56 .Fn asprintf "char **ret" "const char *format" ...
58 .Fn dprintf "int fd" "const char * restrict format" ...
61 .Fn vprintf "const char * restrict format" "va_list ap"
63 .Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap"
65 .Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap"
67 .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
69 .Fn vasprintf "char **ret" "const char *format" "va_list ap"
71 .Fn vdprintf "int fd" "const char * restrict format" "va_list ap"
75 family of functions produces output according to a
85 the standard output stream;
89 write output to the given output
94 write output to the given file descriptor;
100 write to the character string
106 dynamically allocate a new string with
109 These functions write the output under the control of a
111 string that specifies how subsequent arguments
112 (or arguments accessed via the variable-length argument facilities of
114 are converted for output.
123 to be a pointer to a buffer sufficiently large to hold the formatted string.
124 This pointer should be passed to
126 to release the allocated storage when it is no longer needed.
127 If sufficient space cannot be allocated,
131 will return \-1 and set
144 of the characters printed into the output string
147 character then gets the terminating
149 if the return value is greater than or equal to the
151 argument, the string was too short
152 and some of the printed characters were discarded.
153 The output is always null-terminated, unless
167 The format string is composed of zero or more directives:
172 which are copied unchanged to the output stream;
173 and conversion specifications, each of which results
174 in fetching zero or more subsequent arguments.
175 Each conversion specification is introduced by
179 The arguments must correspond properly (after type promotion)
180 with the conversion specifier.
183 the following appear in sequence:
186 An optional field, consisting of a decimal digit string followed by a
188 specifying the next argument to access.
189 If this field is not provided, the argument following the last
190 argument accessed will be used.
191 Arguments are numbered starting at
193 If unaccessed arguments in the format string are interspersed with ones that
194 are accessed the results will be indeterminate.
196 Zero or more of the following flags:
197 .Bl -tag -width ".So \ Sc (space)"
199 The value should be converted to an
202 .Cm c , d , i , n , p , s ,
205 conversions, this option has no effect.
208 conversions, the precision of the number is increased to force the first
209 character of the output string to a zero.
214 conversions, a non-zero result has the string
220 conversions) prepended to it.
222 .Cm a , A , e , E , f , F , g ,
225 conversions, the result will always contain a decimal point, even if no
226 digits follow it (normally, a decimal point appears in the results of
227 those conversions only if a digit follows).
232 conversions, trailing zeros are not removed from the result as they
234 .It So Cm 0 Sc (zero)
236 For all conversions except
238 the converted value is padded on the left with zeros rather than blanks.
239 If a precision is given with a numeric conversion
240 .Cm ( d , i , o , u , i , x ,
247 A negative field width flag;
248 the converted value is to be left adjusted on the field boundary.
251 conversions, the converted value is padded on the right with blanks,
252 rather than on the left with blanks or zeros.
258 .It So "\ " Sc (space)
259 A blank should be left before a positive number
260 produced by a signed conversion
261 .Cm ( a , A , d , e , E , f , F , g , G ,
265 A sign must always be placed before a
266 number produced by a signed conversion.
269 overrides a space if both are used.
270 .It So "'" Sc (apostrophe)
275 or the integral portion of a floating point conversion
279 should be grouped and separated by thousands using
280 the non-monetary separator returned by
284 An optional decimal digit string specifying a minimum field width.
285 If the converted value has fewer characters than the field width, it will
286 be padded with spaces on the left (or right, if the left-adjustment
287 flag has been given) to fill out
290 An optional precision, in the form of a period
293 optional digit string.
294 If the digit string is omitted, the precision is taken as zero.
295 This gives the minimum number of digits to appear for
296 .Cm d , i , o , u , x ,
299 conversions, the number of digits to appear after the decimal-point for
300 .Cm a , A , e , E , f ,
303 conversions, the maximum number of significant digits for
307 conversions, or the maximum number of characters to be printed from a
312 An optional length modifier, that specifies the size of the argument.
313 The following length modifiers are valid for the
314 .Cm d , i , n , o , u , x ,
318 .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
319 .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
320 .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
321 .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
322 .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
323 .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
324 .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
325 .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
326 .It Cm z Ta (see note) Ta Vt size_t Ta (see note)
327 .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
333 modifier, when applied to a
337 conversion, indicates that the argument is of an unsigned type
338 equivalent in size to a
342 modifier, when applied to a
346 conversion, indicates that the argument is of a signed type equivalent in
349 Similarly, when applied to an
351 conversion, it indicates that the argument is a pointer to a signed type
352 equivalent in size to a
355 The following length modifier is valid for the
356 .Cm a , A , e , E , f , F , g ,
360 .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
361 .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
362 .It Cm l No (ell) Ta Vt double
363 (ignored, same behavior as without it)
364 .It Cm L Ta Vt "long double"
367 The following length modifier is valid for the
372 .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
373 .It Sy Modifier Ta Cm c Ta Cm s
374 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
377 A character that specifies the type of conversion to be applied.
380 A field width or precision, or both, may be indicated by
383 or an asterisk followed by one or more decimal digits and a
389 argument supplies the field width or precision.
390 A negative field width is treated as a left adjustment flag followed by a
391 positive field width; a negative precision is treated as though it were
393 If a single format directive mixes positional
395 and non-positional arguments, the results are undefined.
397 The conversion specifiers and their meanings are:
398 .Bl -tag -width ".Cm diouxX"
402 (or appropriate variant) argument is converted to signed decimal
410 or unsigned hexadecimal
419 conversions; the letters
424 The precision, if any, gives the minimum number of digits that must
425 appear; if the converted value requires fewer digits, it is padded on
430 argument is converted to signed decimal, unsigned octal, or unsigned
431 decimal, as if the format had been
436 These conversion characters are deprecated, and will eventually disappear.
440 argument is rounded and converted in the style
442 .Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd
444 where there is one digit before the
445 decimal-point character
446 and the number of digits after it is equal to the precision;
447 if the precision is missing,
448 it is taken as 6; if the precision is
449 zero, no decimal-point character appears.
452 conversion uses the letter
456 to introduce the exponent.
457 The exponent always contains at least two digits; if the value is zero,
461 .Cm a , A , e , E , f , F , g ,
464 conversions, positive and negative infinity are represented as
468 respectively when using the lowercase conversion character, and
472 respectively when using the uppercase conversion character.
473 Similarly, NaN is represented as
475 when using the lowercase conversion, and
477 when using the uppercase conversion.
481 argument is rounded and converted to decimal notation in the style
483 .Oo \- Oc Ar ddd Li \&. Ar ddd ,
485 where the number of digits after the decimal-point character
486 is equal to the precision specification.
487 If the precision is missing, it is taken as 6; if the precision is
488 explicitly zero, no decimal-point character appears.
489 If a decimal point appears, at least one digit appears before it.
493 argument is converted in style
504 The precision specifies the number of significant digits.
505 If the precision is missing, 6 digits are given; if the precision is zero,
509 is used if the exponent from its conversion is less than \-4 or greater than
510 or equal to the precision.
511 Trailing zeros are removed from the fractional part of the result; a
512 decimal point appears only if it is followed by at least one digit.
516 argument is rounded and converted to hexadecimal notation in the style
518 .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d ,
520 where the number of digits after the hexadecimal-point character
521 is equal to the precision specification.
522 If the precision is missing, it is taken as enough to represent
523 the floating-point number exactly, and no rounding occurs.
524 If the precision is zero, no hexadecimal-point character appears.
527 is a literal character
529 and the exponent consists of a positive or negative sign
530 followed by a decimal number representing an exponent of 2.
533 conversion uses the prefix
541 to represent the hex digits, and the letter
545 to separate the mantissa and exponent.
547 Note that there may be multiple valid ways to represent floating-point
548 numbers in this hexadecimal format.
550 .Li 0x1.92p+1 , 0x3.24p+0 , 0x6.48p-1 ,
555 and later always prints finite non-zero numbers using
557 as the digit before the hexadecimal point.
558 Zeroes are always represented with a mantissa of 0 (preceded by a
560 if appropriate) and an exponent of
571 argument is converted to an
572 .Vt "unsigned char" ,
573 and the resulting character is written.
577 (ell) modifier is used, the
579 argument shall be converted to a
581 and the (potentially multi-byte) sequence representing the
582 single wide character is written, including any shift sequences.
583 If a shift sequence is used, the shift state is also restored
584 to the original state after the character.
594 argument is expected to be a pointer to an array of character type (pointer
596 Characters from the array are written up to (but not including)
600 if a precision is specified, no more than the number specified are
602 If a precision is given, no null character
603 need be present; if the precision is not specified, or is greater than
604 the size of the array, the array must contain a terminating
610 (ell) modifier is used, the
612 argument is expected to be a pointer to an array of wide characters
613 (pointer to a wide string).
614 For each wide character in the string, the (potentially multi-byte)
615 sequence representing the
616 wide character is written, including any shift sequences.
617 If any shift sequence is used, the shift state is also restored
618 to the original state after the string.
619 Wide characters from the array are written up to (but not including)
623 if a precision is specified, no more than the number of bytes specified are
624 written (including shift sequences).
625 Partial characters are never written.
626 If a precision is given, no null character
627 need be present; if the precision is not specified, or is greater than
628 the number of bytes required to render the multibyte representation of
629 the string, the array must contain a terminating wide
635 pointer argument is printed in hexadecimal (as if by
640 The number of characters written so far is stored into the
641 integer indicated by the
643 (or variant) pointer argument.
644 No argument is converted.
649 No argument is converted.
650 The complete conversion specification
656 character is defined in the program's locale (category
659 In no case does a non-existent or small field width cause truncation of
660 a numeric field; if the result of a conversion is wider than the field
662 field is expanded to contain the conversion result.
664 These functions return the number of characters printed
665 (not including the trailing
667 used to end output to strings),
672 which return the number of characters that would have been printed if the
675 (again, not including the final
677 These functions return a negative value if an error occurs.
679 To print a date and time in the form
680 .Dq Li "Sunday, July 3, 10:02" ,
685 are pointers to strings:
686 .Bd -literal -offset indent
688 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
689 weekday, month, day, hour, min);
693 to five decimal places:
694 .Bd -literal -offset indent
697 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
700 To allocate a 128 byte string and print into it:
701 .Bd -literal -offset indent
705 char *newfmt(const char *fmt, ...)
709 if ((p = malloc(128)) == NULL)
712 (void) vsnprintf(p, 128, fmt, ap);
718 Many application writers used the name
722 function was introduced in
724 so a prototype is not provided by default in order to avoid
725 compatibility problems.
726 Applications that wish to use the
728 function described herein should either request a strict
730 environment by defining the macro
732 to the value 200809 or greater, or by defining the macro
734 prior to the inclusion of
736 For compatibility with GNU libc, defining either
740 prior to the inclusion of
746 The conversion formats
751 are provided only for backward compatibility.
752 The effect of padding the
754 format with zeros (either by the
756 flag or by specifying a precision), and the benign effect (i.e., none)
763 conversions, as well as other
764 nonsensical combinations such as
766 are not standard; such combinations
769 In addition to the errors documented for the
773 family of functions may fail if:
776 An invalid wide character code was encountered.
778 Insufficient storage space is available.
784 or the return value would be too large to be represented by an
794 Subject to the caveats noted in the
809 With the same reservation, the
826 first appeared in the
829 These were implemented by
830 .An Peter Wemm Aq peter@FreeBSD.org
833 but were later replaced with a different implementation
837 .An Todd C. Miller Aq Todd.Miller@courtesan.com .
842 functions were added in
847 family of functions do not correctly handle multibyte characters in the
850 .Sh SECURITY CONSIDERATIONS
855 functions are easily misused in a manner which enables malicious users
856 to arbitrarily change a running program's functionality through
857 a buffer overflow attack.
862 assume an infinitely long string,
863 callers must be careful not to overflow the actual space;
864 this is often hard to assure.
865 For safety, programmers should use the
871 foo(const char *arbitrary_string, const char *and_another)
877 * This first sprintf is bad behavior. Do not use sprintf!
879 sprintf(onstack, "%s, %s", arbitrary_string, and_another);
882 * The following two lines demonstrate better use of
885 snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
895 family of functions are also easily misused in a manner
896 allowing malicious users to arbitrarily change a running program's
897 functionality by either causing the program
898 to print potentially sensitive data
899 .Dq "left on the stack" ,
900 or causing it to generate a memory fault or bus error
901 by dereferencing an invalid pointer.
904 can be used to write arbitrary data to potentially carefully-selected
906 Programmers are therefore strongly advised to never pass untrusted strings
909 argument, as an attacker can put format specifiers in the string
910 to mangle your stack,
911 leading to a possible security hole.
912 This holds true even if the string was built using a function like
914 as the resulting string may still contain user-supplied conversion specifiers
915 for later interpolation by
918 Always use the proper secure idiom:
920 .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"