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. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed by the University of
19 .\" California, Berkeley and its contributors.
20 .\" 4. Neither the name of the University nor the names of its contributors
21 .\" may be used to endorse or promote products derived from this software
22 .\" without specific prior written permission.
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .\" @(#)printf.3 8.1 (Berkeley) 6/4/93
43 .Nm printf , fprintf , sprintf , snprintf , asprintf ,
44 .Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf
45 .Nd formatted output conversion
51 .Fn printf "const char *format" ...
53 .Fn fprintf "FILE *stream" "const char *format" ...
55 .Fn sprintf "char *str" "const char *format" ...
57 .Fn snprintf "char *str" "size_t size" "const char *format" ...
59 .Fn asprintf "char **ret" "const char *format" ...
62 .Fn vprintf "const char *format" "va_list ap"
64 .Fn vfprintf "FILE *stream" "const char *format" "va_list ap"
66 .Fn vsprintf "char *str" "const char *format" "va_list ap"
68 .Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap"
70 .Fn vasprintf "char **ret" "const char *format" "va_list ap"
74 family of functions produces output according to a
82 the standard output stream;
86 write output to the given output
93 write to the character string
99 dynamically allocate a new string with
102 These functions write the output under the control of a
104 string that specifies how subsequent arguments
105 (or arguments accessed via the variable-length argument facilities of
107 are converted for output.
109 These functions return the number of characters printed
110 (not including the trailing
112 used to end output to strings),
117 which return the number of characters that would have been printed if the
120 (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
147 of the characters printed into the output string
150 character then gets the terminating
152 if the return value is greater than or equal to the
154 argument, the string was too short
155 and some of the printed characters were discarded.
156 The output is always null-terminated.
161 effectively assume an infinite
164 The format string is composed of zero or more directives:
169 which are copied unchanged to the output stream;
170 and conversion specifications, each of which results
171 in fetching zero or more subsequent arguments.
172 Each conversion specification is introduced by
176 The arguments must correspond properly (after type promotion)
177 with the conversion specifier.
180 the following appear in sequence:
183 An optional field, consisting of a decimal digit string followed by a
185 specifying the next argument to access.
186 If this field is not provided, the argument following the last
187 argument accessed will be used.
188 Arguments are numbered starting at
190 If unaccessed arguments in the format string are interspersed with ones that
191 are accessed the results will be indeterminate.
193 Zero or more of the following flags:
194 .Bl -tag -width ".So \ Sc (space)"
196 The value should be converted to an
199 .Cm c , d , i , n , p , s ,
202 conversions, this option has no effect.
205 conversions, the precision of the number is increased to force the first
206 character of the output string to a zero (except if a zero value is printed
207 with an explicit precision of zero).
212 conversions, a non-zero result has the string
218 conversions) prepended to it.
220 .Cm a , A , e , E , f , F , g ,
223 conversions, the result will always contain a decimal point, even if no
224 digits follow it (normally, a decimal point appears in the results of
225 those conversions only if a digit follows).
230 conversions, trailing zeros are not removed from the result as they
232 .It So Cm 0 Sc (zero)
234 For all conversions except
236 the converted value is padded on the left with zeros rather than blanks.
237 If a precision is given with a numeric conversion
238 .Cm ( d , i , o , u , i , x ,
245 A negative field width flag;
246 the converted value is to be left adjusted on the field boundary.
249 conversions, the converted value is padded on the right with blanks,
250 rather than on the left with blanks or zeros.
256 .It So "\ " Sc (space)
257 A blank should be left before a positive number
258 produced by a signed conversion
259 .Cm ( a , A , d , e , E , f , F , g , G ,
263 A sign must always be placed before a
264 number produced by a signed conversion.
267 overrides a space if both are used.
273 or the integral portion of a floating point conversion
277 should be grouped and separated by thousands using
278 the non-monetary seperator returned by
282 An optional decimal digit string specifying a minimum field width.
283 If the converted value has fewer characters than the field width, it will
284 be padded with spaces on the left (or right, if the left-adjustment
285 flag has been given) to fill out
288 An optional precision, in the form of a period
291 optional digit string.
292 If the digit string is omitted, the precision is taken as zero.
293 This gives the minimum number of digits to appear for
294 .Cm d , i , o , u , x ,
297 conversions, the number of digits to appear after the decimal-point for
298 .Cm a , A , e , E , f ,
301 conversions, the maximum number of significant digits for
305 conversions, or the maximum number of characters to be printed from a
310 An optional length modifier, that specifies the size of the argument.
311 The following length modifiers are valid for the
312 .Cm d , i , n , o , u , x ,
316 .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
317 .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
318 .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
319 .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
320 .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
321 .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
322 .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
323 .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
324 .It Cm z Ta (see note) Ta Vt size_t Ta (see note)
325 .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
331 modifier, when applied to a
335 conversion, indicates that the argument is of an unsigned type
336 equivalent in size to a
340 modifier, when applied to a
344 conversion, indicates that the argument is of a signed type equivalent in
347 Similarly, when applied to an
349 conversion, it indicates that the argument is a pointer to a signed type
350 equivalent in size to a
353 The following length modifier is valid for the
354 .Cm a , A , e , E , f , F , g ,
358 .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
359 .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
360 .It Cm L Ta Vt "long double"
363 The following length modifier is valid for the
368 .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
369 .It Sy Modifier Ta Cm c Ta Cm s
370 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
373 A character that specifies the type of conversion to be applied.
376 A field width or precision, or both, may be indicated by
379 or an asterisk followed by one or more decimal digits and a
385 argument supplies the field width or precision.
386 A negative field width is treated as a left adjustment flag followed by a
387 positive field width; a negative precision is treated as though it were
389 If a single format directive mixes positional
391 and non-positional arguments, the results are undefined.
393 The conversion specifiers and their meanings are:
394 .Bl -tag -width ".Cm diouxX"
398 (or appropriate variant) argument is converted to signed decimal
406 or unsigned hexadecimal
415 conversions; the letters
420 The precision, if any, gives the minimum number of digits that must
421 appear; if the converted value requires fewer digits, it is padded on
426 argument is converted to signed decimal, unsigned octal, or unsigned
427 decimal, as if the format had been
432 These conversion characters are deprecated, and will eventually disappear.
436 argument is rounded and converted in the style
438 .Oo \- Oc Ar d Li \&. Ar ddd Li e \\*[Pm] Ar dd
440 where there is one digit before the
441 decimal-point character
442 and the number of digits after it is equal to the precision;
443 if the precision is missing,
444 it is taken as 6; if the precision is
445 zero, no decimal-point character appears.
448 conversion uses the letter
452 to introduce the exponent.
453 The exponent always contains at least two digits; if the value is zero,
457 .Cm a , A , e , E , f , F , g ,
460 conversions, positive and negative infinity are represented as
464 respectively when using the lowercase conversion character, and
468 respectively when using the uppercase conversion character.
469 Similarly, NaN is represented as
471 when using the lowercase conversion, and
473 when using the uppercase conversion.
477 argument is rounded and converted to decimal notation in the style
479 .Oo \- Oc Ar ddd Li \&. Ar ddd ,
481 where the number of digits after the decimal-point character
482 is equal to the precision specification.
483 If the precision is missing, it is taken as 6; if the precision is
484 explicitly zero, no decimal-point character appears.
485 If a decimal point appears, at least one digit appears before it.
489 argument is converted in style
500 The precision specifies the number of significant digits.
501 If the precision is missing, 6 digits are given; if the precision is zero,
505 is used if the exponent from its conversion is less than \-4 or greater than
506 or equal to the precision.
507 Trailing zeros are removed from the fractional part of the result; a
508 decimal point appears only if it is followed by at least one digit.
512 argument is converted to hexadecimal notation in the style
514 .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \\*[Pm] Oc Ar d ,
516 where the number of digits after the hexadecimal-point character
517 is equal to the precision specification.
518 If the precision is missing, it is taken as enough to exactly
519 represent the floating-point number; if the precision is
520 explicitly zero, no hexadecimal-point character appears.
521 This is an exact coversion of the mantissa+exponent internal
522 floating point representation; the
524 .Oo \- Oc Li 0x Ar h Li \&. Ar hhh
526 portion represents exactly the mantissa; only denormalized
527 mantissas have a zero value to the left of the hexadecimal
531 is a literal character
533 the exponent is preceded by a positive or negative sign
534 and is represented in decimal, using only enough characters
535 to represent the exponent.
538 conversion uses the prefix
546 to represent the hex digits, and the letter
550 to seperate the mantissa and exponent.
560 argument is converted to an
561 .Vt "unsigned char" ,
562 and the resulting character is written.
566 (ell) modifier is used, the
568 argument shall be converted to a
570 and the (potentially multi-byte) sequence representing the
571 single wide character is written, including any shift sequences.
572 If a shift sequence is used, the shift state is also restored
573 to the original state after the character.
583 argument is expected to be a pointer to an array of character type (pointer
585 Characters from the array are written up to (but not including)
589 if a precision is specified, no more than the number specified are
591 If a precision is given, no null character
592 need be present; if the precision is not specified, or is greater than
593 the size of the array, the array must contain a terminating
599 (ell) modifier is used, the
601 argument is expected to be a pointer to an array of wide characters
602 (pointer to a wide string).
603 For each wide character in the string, the (potentially multi-byte)
604 sequence representing the
605 wide character is written, including any shift sequences.
606 If any shift sequence is used, the shift state is also restored
607 to the original state after the string.
608 Wide characters from the array are written up to (but not including)
612 if a precision is specified, no more than the number of bytes specified are
613 written (including shift sequences).
614 Partial characters are never written.
615 If a precision is given, no null character
616 need be present; if the precision is not specified, or is greater than
617 the number of bytes required to render the multibyte representation of
618 the string, the array must contain a terminating wide
624 pointer argument is printed in hexadecimal (as if by
629 The number of characters written so far is stored into the
630 integer indicated by the
632 (or variant) pointer argument.
633 No argument is converted.
638 No argument is converted.
639 The complete conversion specification
645 character is defined in the program's locale (category
648 In no case does a non-existent or small field width cause truncation of
649 a numeric field; if the result of a conversion is wider than the field
651 field is expanded to contain the conversion result.
653 To print a date and time in the form
654 .Dq Li "Sunday, July 3, 10:02" ,
659 are pointers to strings:
660 .Bd -literal -offset indent
662 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
663 weekday, month, day, hour, min);
667 to five decimal places:
668 .Bd -literal -offset indent
671 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
674 To allocate a 128 byte string and print into it:
675 .Bd -literal -offset indent
679 char *newfmt(const char *fmt, ...)
683 if ((p = malloc(128)) == NULL)
686 (void) vsnprintf(p, 128, fmt, ap);
691 .Sh SECURITY CONSIDERATIONS
696 functions are easily misused in a manner which enables malicious users
697 to arbitrarily change a running program's functionality through
698 a buffer overflow attack.
708 .%T "The FreeBSD Security Architecture"
709 .%J "/usr/share/doc/{to be determined}"
736 first appeared in the
739 These were implemented by
740 .An Peter Wemm Aq peter@FreeBSD.org
743 but were later replaced with a different implementation
745 .An Todd C. Miller Aq Todd.Miller@courtesan.com
749 The conversion formats
754 are provided only for backward compatibility.
755 The effect of padding the
757 format with zeros (either by the
759 flag or by specifying a precision), and the benign effect (i.e., none)
766 conversions, as well as other
767 nonsensical combinations such as
769 are not standard; such combinations
776 assume an infinitely long string,
777 callers must be careful not to overflow the actual space;
778 this is often hard to assure.
779 For safety, programmers should use the
782 Unfortunately, this interface was only defined in
786 can be used to write arbitrary data to the stack.
787 Programmers are therefore strongly advised to never pass untrusted strings
792 Never pass a string with user-supplied data as a format without using
794 An attacker can put format specifiers in the string to mangle your stack,
795 leading to a possible security hole.
796 This holds true even if the string was built using a function like
798 as the resulting string may still contain user-supplied conversion specifiers
799 for later interpolation by
802 Always use the proper secure idiom:
804 .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"
808 family of functions currently lack the ability to use the
810 flag in conjunction with the
812 conversion specifier.
817 conversion specifiers have not yet been implemented.
820 (ell) modifier for the
824 conversion specifiers, for wide characters and strings, have not yet
828 modifier for floating point formats simply round the
832 providing no additional precision.