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
39 .Nm printf , fprintf , sprintf , snprintf , asprintf , dprintf ,
40 .Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf, vdprintf
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" ...
57 .Fn dprintf "int fd" "const char * restrict format" ...
60 .Fn vprintf "const char * restrict format" "va_list ap"
62 .Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap"
64 .Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap"
66 .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
68 .Fn vasprintf "char **ret" "const char *format" "va_list ap"
70 .Fn vdprintf "int fd" "const char * restrict format" "va_list ap"
74 family of functions produces output according to a
84 the standard output stream;
88 write output to the given output
93 write output to the given file descriptor;
99 write to the character string
105 dynamically allocate a new string with
108 These functions write the output under the control of a
110 string that specifies how subsequent arguments
111 (or arguments accessed via the variable-length argument facilities of
113 are converted for output.
122 to be a pointer to a buffer sufficiently large to hold the formatted string.
123 This pointer should be passed to
125 to release the allocated storage when it is no longer needed.
126 If sufficient space cannot be allocated,
130 will return \-1 and set
143 of the characters printed into the output string
146 character then gets the terminating
148 if the return value is greater than or equal to the
150 argument, the string was too short
151 and some of the printed characters were discarded.
152 The output is always null-terminated, unless
166 The format string is composed of zero or more directives:
171 which are copied unchanged to the output stream;
172 and conversion specifications, each of which results
173 in fetching zero or more subsequent arguments.
174 Each conversion specification is introduced by
178 The arguments must correspond properly (after type promotion)
179 with the conversion specifier.
182 the following appear in sequence:
185 An optional field, consisting of a decimal digit string followed by a
187 specifying the next argument to access.
188 If this field is not provided, the argument following the last
189 argument accessed will be used.
190 Arguments are numbered starting at
192 If unaccessed arguments in the format string are interspersed with ones that
193 are accessed the results will be indeterminate.
195 Zero or more of the following flags:
196 .Bl -tag -width ".So \ Sc (space)"
198 The value should be converted to an
201 .Cm c , d , i , n , p , s ,
204 conversions, this option has no effect.
207 conversions, the precision of the number is increased to force the first
208 character of the output string to a zero.
213 conversions, a non-zero result has the string
219 conversions) prepended to it.
221 .Cm a , A , e , E , f , F , g ,
224 conversions, the result will always contain a decimal point, even if no
225 digits follow it (normally, a decimal point appears in the results of
226 those conversions only if a digit follows).
231 conversions, trailing zeros are not removed from the result as they
233 .It So Cm 0 Sc (zero)
235 For all conversions except
237 the converted value is padded on the left with zeros rather than blanks.
238 If a precision is given with a numeric conversion
239 .Cm ( d , i , o , u , i , x ,
246 A negative field width flag;
247 the converted value is to be left adjusted on the field boundary.
250 conversions, the converted value is padded on the right with blanks,
251 rather than on the left with blanks or zeros.
257 .It So "\ " Sc (space)
258 A blank should be left before a positive number
259 produced by a signed conversion
260 .Cm ( a , A , d , e , E , f , F , g , G ,
264 A sign must always be placed before a
265 number produced by a signed conversion.
268 overrides a space if both are used.
269 .It So "'" Sc (apostrophe)
274 or the integral portion of a floating point conversion
278 should be grouped and separated by thousands using
279 the non-monetary separator returned by
283 An optional decimal digit string specifying a minimum field width.
284 If the converted value has fewer characters than the field width, it will
285 be padded with spaces on the left (or right, if the left-adjustment
286 flag has been given) to fill out
289 An optional precision, in the form of a period
292 optional digit string.
293 If the digit string is omitted, the precision is taken as zero.
294 This gives the minimum number of digits to appear for
295 .Cm d , i , o , u , x ,
298 conversions, the number of digits to appear after the decimal-point for
299 .Cm a , A , e , E , f ,
302 conversions, the maximum number of significant digits for
306 conversions, or the maximum number of characters to be printed from a
311 An optional length modifier, that specifies the size of the argument.
312 The following length modifiers are valid for the
313 .Cm d , i , n , o , u , x ,
317 .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
318 .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
319 .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
320 .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
321 .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
322 .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
323 .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
324 .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
325 .It Cm z Ta (see note) Ta Vt size_t Ta (see note)
326 .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
332 modifier, when applied to a
336 conversion, indicates that the argument is of an unsigned type
337 equivalent in size to a
341 modifier, when applied to a
345 conversion, indicates that the argument is of a signed type equivalent in
348 Similarly, when applied to an
350 conversion, it indicates that the argument is a pointer to a signed type
351 equivalent in size to a
354 The following length modifier is valid for the
355 .Cm a , A , e , E , f , F , g ,
359 .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
360 .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
361 .It Cm l No (ell) Ta Vt double
362 (ignored, same behavior as without it)
363 .It Cm L Ta Vt "long double"
366 The following length modifier is valid for the
371 .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
372 .It Sy Modifier Ta Cm c Ta Cm s
373 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
376 A character that specifies the type of conversion to be applied.
379 A field width or precision, or both, may be indicated by
382 or an asterisk followed by one or more decimal digits and a
388 argument supplies the field width or precision.
389 A negative field width is treated as a left adjustment flag followed by a
390 positive field width; a negative precision is treated as though it were
392 If a single format directive mixes positional
394 and non-positional arguments, the results are undefined.
396 The conversion specifiers and their meanings are:
397 .Bl -tag -width ".Cm diouxX"
401 (or appropriate variant) argument is converted to signed decimal
409 or unsigned hexadecimal
418 conversions; the letters
423 The precision, if any, gives the minimum number of digits that must
424 appear; if the converted value requires fewer digits, it is padded on
429 argument is converted to signed decimal, unsigned octal, or unsigned
430 decimal, as if the format had been
435 These conversion characters are deprecated, and will eventually disappear.
439 argument is rounded and converted in the style
441 .Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd
443 where there is one digit before the
444 decimal-point character
445 and the number of digits after it is equal to the precision;
446 if the precision is missing,
447 it is taken as 6; if the precision is
448 zero, no decimal-point character appears.
451 conversion uses the letter
455 to introduce the exponent.
456 The exponent always contains at least two digits; if the value is zero,
460 .Cm a , A , e , E , f , F , g ,
463 conversions, positive and negative infinity are represented as
467 respectively when using the lowercase conversion character, and
471 respectively when using the uppercase conversion character.
472 Similarly, NaN is represented as
474 when using the lowercase conversion, and
476 when using the uppercase conversion.
480 argument is rounded and converted to decimal notation in the style
482 .Oo \- Oc Ar ddd Li \&. Ar ddd ,
484 where the number of digits after the decimal-point character
485 is equal to the precision specification.
486 If the precision is missing, it is taken as 6; if the precision is
487 explicitly zero, no decimal-point character appears.
488 If a decimal point appears, at least one digit appears before it.
492 argument is converted in style
503 The precision specifies the number of significant digits.
504 If the precision is missing, 6 digits are given; if the precision is zero,
508 is used if the exponent from its conversion is less than \-4 or greater than
509 or equal to the precision.
510 Trailing zeros are removed from the fractional part of the result; a
511 decimal point appears only if it is followed by at least one digit.
515 argument is rounded and converted to hexadecimal notation in the style
517 .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d ,
519 where the number of digits after the hexadecimal-point character
520 is equal to the precision specification.
521 If the precision is missing, it is taken as enough to represent
522 the floating-point number exactly, and no rounding occurs.
523 If the precision is zero, no hexadecimal-point character appears.
526 is a literal character
528 and the exponent consists of a positive or negative sign
529 followed by a decimal number representing an exponent of 2.
532 conversion uses the prefix
540 to represent the hex digits, and the letter
544 to separate the mantissa and exponent.
546 Note that there may be multiple valid ways to represent floating-point
547 numbers in this hexadecimal format.
549 .Li 0x1.92p+1 , 0x3.24p+0 , 0x6.48p-1 ,
554 and later always prints finite non-zero numbers using
556 as the digit before the hexadecimal point.
557 Zeroes are always represented with a mantissa of 0 (preceded by a
559 if appropriate) and an exponent of
570 argument is converted to an
571 .Vt "unsigned char" ,
572 and the resulting character is written.
576 (ell) modifier is used, the
578 argument shall be converted to a
580 and the (potentially multi-byte) sequence representing the
581 single wide character is written, including any shift sequences.
582 If a shift sequence is used, the shift state is also restored
583 to the original state after the character.
593 argument is expected to be a pointer to an array of character type (pointer
595 Characters from the array are written up to (but not including)
599 if a precision is specified, no more than the number specified are
601 If a precision is given, no null character
602 need be present; if the precision is not specified, or is greater than
603 the size of the array, the array must contain a terminating
609 (ell) modifier is used, the
611 argument is expected to be a pointer to an array of wide characters
612 (pointer to a wide string).
613 For each wide character in the string, the (potentially multi-byte)
614 sequence representing the
615 wide character is written, including any shift sequences.
616 If any shift sequence is used, the shift state is also restored
617 to the original state after the string.
618 Wide characters from the array are written up to (but not including)
622 if a precision is specified, no more than the number of bytes specified are
623 written (including shift sequences).
624 Partial characters are never written.
625 If a precision is given, no null character
626 need be present; if the precision is not specified, or is greater than
627 the number of bytes required to render the multibyte representation of
628 the string, the array must contain a terminating wide
634 pointer argument is printed in hexadecimal (as if by
639 The number of characters written so far is stored into the
640 integer indicated by the
642 (or variant) pointer argument.
643 No argument is converted.
648 No argument is converted.
649 The complete conversion specification
655 character is defined in the program's locale (category
658 In no case does a non-existent or small field width cause truncation of
659 a numeric field; if the result of a conversion is wider than the field
661 field is expanded to contain the conversion result.
663 These functions return the number of characters printed
664 (not including the trailing
666 used to end output to strings),
671 which return the number of characters that would have been printed if the
674 (again, not including the final
676 These functions return a negative value if an error occurs.
678 To print a date and time in the form
679 .Dq Li "Sunday, July 3, 10:02" ,
684 are pointers to strings:
685 .Bd -literal -offset indent
687 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
688 weekday, month, day, hour, min);
692 to five decimal places:
693 .Bd -literal -offset indent
696 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
699 To allocate a 128 byte string and print into it:
700 .Bd -literal -offset indent
704 char *newfmt(const char *fmt, ...)
708 if ((p = malloc(128)) == NULL)
711 (void) vsnprintf(p, 128, fmt, ap);
717 The conversion formats
722 are provided only for backward compatibility.
723 The effect of padding the
725 format with zeros (either by the
727 flag or by specifying a precision), and the benign effect (i.e., none)
734 conversions, as well as other
735 nonsensical combinations such as
737 are not standard; such combinations
740 In addition to the errors documented for the
744 family of functions may fail if:
747 An invalid wide character code was encountered.
749 Insufficient storage space is available.
755 or the return value would be too large to be represented by an
765 Subject to the caveats noted in the
780 With the same reservation, the
797 first appeared in the
800 These were implemented by
801 .An Peter Wemm Aq Mt peter@FreeBSD.org
804 but were later replaced with a different implementation
808 .An Todd C. Miller Aq Mt Todd.Miller@courtesan.com .
813 functions were added in
818 family of functions do not correctly handle multibyte characters in the
821 .Sh SECURITY CONSIDERATIONS
826 functions are easily misused in a manner which enables malicious users
827 to arbitrarily change a running program's functionality through
828 a buffer overflow attack.
833 assume an infinitely long string,
834 callers must be careful not to overflow the actual space;
835 this is often hard to assure.
836 For safety, programmers should use the
842 foo(const char *arbitrary_string, const char *and_another)
848 * This first sprintf is bad behavior. Do not use sprintf!
850 sprintf(onstack, "%s, %s", arbitrary_string, and_another);
853 * The following two lines demonstrate better use of
856 snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
866 family of functions are also easily misused in a manner
867 allowing malicious users to arbitrarily change a running program's
868 functionality by either causing the program
869 to print potentially sensitive data
870 .Dq "left on the stack" ,
871 or causing it to generate a memory fault or bus error
872 by dereferencing an invalid pointer.
875 can be used to write arbitrary data to potentially carefully-selected
877 Programmers are therefore strongly advised to never pass untrusted strings
880 argument, as an attacker can put format specifiers in the string
881 to mangle your stack,
882 leading to a possible security hole.
883 This holds true even if the string was built using a function like
885 as the resulting string may still contain user-supplied conversion specifiers
886 for later interpolation by
889 Always use the proper secure idiom:
891 .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"