| blob | a3b709b07a35072f041ff0516400e172160fdbe0 |
1 .\" $NetBSD: printf.3,v 1.64 2014/09/29 14:58:33 christos Exp $
2 .\"
3 .\" Copyright (c) 1990, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to Berkeley by
7 .\" Chris Torek and the American National Standards Committee X3,
8 .\" on Information Processing Systems.
9 .\"
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
12 .\" are met:
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\"
34 .\" @(#)printf.3 8.1 (Berkeley) 6/4/93
35 .\"
36 .Dd September 29, 2014
37 .Dt PRINTF 3
38 .Os
39 .Sh NAME
40 .Nm printf ,
41 .Nm fprintf ,
42 .Nm dprintf
43 .Nm sprintf ,
44 .Nm snprintf ,
45 .Nm snprintf_ss ,
46 .Nm asprintf ,
47 .Nm vprintf ,
48 .Nm vfprintf ,
49 .Nm vsprintf ,
50 .Nm vdprintf ,
51 .Nm vsnprintf ,
52 .Nm vsnprintf_ss ,
53 .Nm vasprintf
54 .Nd formatted output conversion
55 .Sh LIBRARY
56 .Lb libc
57 .Sh SYNOPSIS
58 .In stdio.h
59 .Ft int
60 .Fn printf "const char * restrict format" ...
61 .Ft int
62 .Fn fprintf "FILE * restrict stream" "const char * restrict format" ...
63 .Ft int
64 .Fn dprintf "int fd" "const char * restrict format" ...
65 .Ft int
66 .Fn sprintf "char * restrict str" "const char * restrict format" ...
67 .Ft int
68 .Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
69 .Ft int
70 .Fn snprintf_ss "char * restrict str" "size_t size" "const char * restrict format" ...
71 .Ft int
72 .Fn asprintf "char ** restrict ret" "const char * restrict format" ...
73 .In stdarg.h
74 .Ft int
75 .Fn vprintf "const char * restrict format" "va_list ap"
76 .Ft int
77 .Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap"
78 .Ft int
79 .Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap"
80 .Ft int
81 .Fn vdprintf "int fd" "const char * restrict format" "va_list ap"
82 .Ft int
83 .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
84 .Ft int
85 .Fn vsnprintf_ss "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
86 .Ft int
87 .Fn vasprintf "char ** restrict ret" "const char * restrict format" "va_list ap"
88 .Sh DESCRIPTION
89 The
90 .Fn printf
91 family of functions produces output according to a
92 .Fa format
93 as described below.
94 The
95 .Fn printf
96 and
97 .Fn vprintf
98 functions
99 write output to
100 .Em stdout ,
101 the standard output stream;
102 .Fn fprintf
103 and
104 .Fn vfprintf
105 write output to the given output
106 .Fa stream ;
107 .Fn dprintf
108 and
109 .Fn vdprintf
110 write output to the given file descriptor
111 .Fa fd ;
112 .Fn sprintf ,
113 .Fn snprintf ,
114 .Fn snprintf_ss ,
115 .Fn vsprintf ,
116 .Fn vsnprintf ,
117 and
118 .Fn vsnprintf_ss
119 write to the character string
120 .Fa str ;
121 and
122 .Fn asprintf
123 and
124 .Fn vasprintf
125 write to a dynamically allocated string that is stored in
126 .Fa ret .
127 .Pp
128 These functions write the output under the control of a
129 .Fa format
130 string that specifies how subsequent arguments
131 (or arguments accessed via the variable-length argument facilities of
132 .Xr stdarg 3 )
133 are converted for output.
134 .Pp
135 .Fn snprintf_ss
136 and
137 .Fn vsnprintf_ss
138 are signal-safe standalone versions that do not handle
139 floating point formats, positional arguments, and wide characters.
140 .Pp
141 .Fn asprintf
142 and
143 .Fn vasprintf
144 return a pointer to a buffer sufficiently large to hold the
145 string in the
146 .Fa ret
147 argument.
148 This pointer should be passed to
149 .Xr free 3
150 to release the allocated storage when it is no longer needed.
151 If sufficient space cannot be allocated, these functions
152 will return \-1 and set
153 .Fa ret
154 to be a
155 .Dv NULL
156 pointer.
157 Please note that these functions are not standardized, and not all
158 implementations can be assumed to set the
159 .Fa ret
160 argument to
161 .Dv NULL
162 on error.
163 It is more portable to check for a return value of \-1 instead.
164 .Pp
165 .Fn snprintf ,
166 .Fn vsnprintf ,
167 and
168 .Fn vsnprintf_ss
169 will write at most
170 .Fa size Ns \-1
171 of the characters printed into the output string
172 (the
173 .Fa size Ns 'th
174 character then gets the terminating
175 .Ql \e0 ) ;
176 if the return value is greater than or equal to the
177 .Fa size
178 argument, the string was too short
179 and some of the printed characters were discarded.
180 If
181 .Fa size
182 is zero, nothing is written and
183 .Fa str
184 may be a
185 .Dv NULL
186 pointer.
187 .Pp
188 .Fn sprintf
189 and
190 .Fn vsprintf
191 effectively assume an infinite
192 .Fa size .
193 .Pp
194 The format string is composed of zero or more directives:
195 ordinary
196 .\" multibyte
197 characters (not
198 .Cm % ) ,
199 which are copied unchanged to the output stream;
200 and conversion specifications, each of which results
201 in fetching zero or more subsequent arguments.
202 Each conversion specification is introduced by
203 the character
204 .Cm % .
205 The arguments must correspond properly (after type promotion)
206 with the conversion specifier.
207 After the
208 .Cm % ,
209 the following appear in sequence:
210 .Bl -bullet
211 .It
212 An optional field, consisting of a decimal digit string followed by a
213 .Cm $ ,
214 specifying the next argument to access.
215 If this field is not provided, the argument following the last
216 argument accessed will be used.
217 Arguments are numbered starting at
218 .Cm 1 .
219 If unaccessed arguments in the format string are interspersed with ones that
220 are accessed the results will be indeterminate.
221 .It
222 Zero or more of the following flags:
223 .Bl -tag -width ".So \ Sc (space)"
224 .It Sq Cm #
225 The value should be converted to an
226 .Dq alternate form .
227 For
228 .Cm c ,
229 .Cm d ,
230 .Cm i ,
231 .Cm n ,
232 .Cm p ,
233 .Cm s ,
234 and
235 .Cm u
236 conversions, this option has no effect.
237 For
238 .Cm o
239 conversions, the precision of the number is increased to force the first
240 character of the output string to a zero (except if a zero value is printed
241 with an explicit precision of zero).
242 For
243 .Cm x
244 and
245 .Cm X
246 conversions, a non-zero result has the string
247 .Ql 0x
248 (or
249 .Ql 0X
250 for
251 .Cm X
252 conversions) prepended to it.
253 For
254 .Cm a ,
255 .Cm A ,
256 .Cm e ,
257 .Cm E ,
258 .Cm f ,
259 .Cm F ,
260 .Cm g ,
261 and
262 .Cm G
263 conversions, the result will always contain a decimal point, even if no
264 digits follow it (normally, a decimal point appears in the results of
265 those conversions only if a digit follows).
266 For
267 .Cm g
268 and
269 .Cm G
270 conversions, trailing zeros are not removed from the result as they
271 would otherwise be.
272 .It So Cm 0 Sc (zero)
273 Zero padding.
274 For all conversions except
275 .Cm n ,
276 the converted value is padded on the left with zeros rather than blanks.
277 If a precision is given with a numeric conversion
278 .Pf ( Cm d ,
279 .Cm i ,
280 .Cm o ,
281 .Cm u ,
282 .Cm i ,
283 .Cm x ,
284 and
285 .Cm X ) ,
286 the
287 .Cm 0
288 flag is ignored.
289 .It Sq Cm \-
290 A negative field width flag;
291 the converted value is to be left adjusted on the field boundary.
292 Except for
293 .Cm n
294 conversions, the converted value is padded on the right with blanks,
295 rather than on the left with blanks or zeros.
296 A
297 .Sq Cm \-
298 overrides a
299 .Sq Cm \&0
300 if both are given.
301 .It So "\ " Sc (space)
302 A blank should be left before a positive number
303 produced by a signed conversion
304 .Pf ( Cm a ,
305 .Cm A
306 .Cm d ,
307 .Cm e ,
308 .Cm E ,
309 .Cm f ,
310 .Cm F ,
311 .Cm g ,
312 .Cm G ,
313 or
314 .Cm i ) .
315 .It Sq Cm +
316 A sign must always be placed before a
317 number produced by a signed conversion.
318 A
319 .Sq Cm +
320 overrides a space if both are used.
321 .It Sq Cm '
322 Decimal conversions
323 .Cm ( d , u ,
324 or
325 .Cm i )
326 or the integral portion of a floating point conversion
327 .Cm ( f
328 or
329 .Cm F )
330 should be grouped and separated by thousands using
331 the non-monetary separator returned by
332 .Xr localeconv 3 .
333 .El
334 .It
335 An optional decimal digit string specifying a minimum field width.
336 If the converted value has fewer characters than the field width, it will
337 be padded with spaces on the left (or right, if the left-adjustment
338 flag has been given) to fill out the field width.
339 .It
340 An optional precision, in the form of a period
341 .Sq Cm \&.
342 followed by an optional digit string.
343 If the digit string is omitted, the precision is taken as zero.
344 This gives the minimum number of digits to appear for
345 .Cm d ,
346 .Cm i ,
347 .Cm o ,
348 .Cm u ,
349 .Cm x ,
350 and
351 .Cm X
352 conversions, the number of digits to appear after the decimal-point for
353 .Cm a ,
354 .Cm A ,
355 .Cm e ,
356 .Cm E ,
357 .Cm f ,
358 and
359 .Cm F
360 conversions, the maximum number of significant digits for
361 .Cm g
362 and
363 .Cm G
364 conversions, or the maximum number of characters to be printed from a
365 string for
366 .Cm s
367 conversions.
368 .It
369 An optional length modifier, that specifies the size of the argument.
370 The following length modifiers are valid for the
371 .Cm d , i , n , o , u , x ,
372 or
373 .Cm X
374 conversion:
375 .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
376 .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
377 .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
378 .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
379 .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
380 .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
381 .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
382 .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
383 .It Cm z Ta (see note) Ta Vt size_t Ta (see note)
384 .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
385 .El
386 .Pp
387 Note:
388 the
389 .Cm t
390 modifier, when applied to a
391 .Cm o , u , x ,
392 or
393 .Cm X
394 conversion, indicates that the argument is of an unsigned type
395 equivalent in size to a
396 .Vt ptrdiff_t .
397 The
398 .Cm z
399 modifier, when applied to a
400 .Cm d
401 or
402 .Cm i
403 conversion, indicates that the argument is of a signed type equivalent in
404 size to a
405 .Vt size_t .
406 Similarly, when applied to an
407 .Cm n
408 conversion, it indicates that the argument is a pointer to a signed type
409 equivalent in size to a
410 .Vt size_t .
411 .Pp
412 Note:
413 if the standard integer types described in
414 .Xr stdint 3
415 are used, it is recommended that the predefined format string specifier
416 macros are used when possible.
417 These are further described in
418 .Xr inttypes 3 .
419 .Pp
420 The following length modifier is valid for the
421 .Cm a ,
422 .Cm A ,
423 .Cm e ,
424 .Cm E ,
425 .Cm f ,
426 .Cm F ,
427 .Cm g ,
428 or
429 .Cm G
430 conversion:
431 .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
432 .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
433 .It Cm l No (ell) Ta Vt double
434 (ignored, same behavior as without it)
435 .It Cm L Ta Vt "long double"
436 .El
437 .Pp
438 The following length modifier is valid for the
439 .Cm c
440 or
441 .Cm s
442 conversion:
443 .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
444 .It Sy Modifier Ta Cm c Ta Cm s
445 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
446 .El
447 .It
448 A character that specifies the type of conversion to be applied.
449 .El
450 .Pp
451 A field width or precision, or both, may be indicated by
452 an asterisk
453 .Ql *
454 or an asterisk followed by one or more decimal digits and a
455 .Ql $
456 instead of a
457 digit string.
458 In this case, an
459 .Vt int
460 argument supplies the field width or precision.
461 A negative field width is treated as a left adjustment flag followed by a
462 positive field width; a negative precision is treated as though it were
463 missing.
464 If a single format directive mixes positional
465 .Pq Li nn$
466 and non-positional arguments, the results are undefined.
467 .Pp
468 The conversion specifiers and their meanings are:
469 .Bl -tag -width ".Cm diouxX"
470 .It Cm diouxX
471 The
472 .Vt int
473 (or appropriate variant) argument is converted to signed decimal
474 .Pf ( Cm d
475 and
476 .Cm i ) ,
477 unsigned octal
478 .Pq Cm o ,
479 unsigned decimal
480 .Pq Cm u ,
481 or unsigned hexadecimal
482 .Pf ( Cm x
483 and
484 .Cm X )
485 notation.
486 The letters
487 .Dq Li abcdef
488 are used for
489 .Cm x
490 conversions; the letters
491 .Dq Li ABCDEF
492 are used for
493 .Cm X
494 conversions.
495 The precision, if any, gives the minimum number of digits that must
496 appear; if the converted value requires fewer digits, it is padded on
497 the left with zeros.
498 .It Cm DOU
499 The
500 .Vt long int
501 argument is converted to signed decimal, unsigned octal, or unsigned
502 decimal, as if the format had been
503 .Cm ld ,
504 .Cm lo ,
505 or
506 .Cm lu
507 respectively.
508 These conversion characters are deprecated, and will eventually disappear.
509 .It Cm eE
510 The
511 .Vt double
512 argument is rounded and converted in the style
513 .Sm off
514 .Oo \- Oc Ar d Li \&. Ar ddd Li e \*[Pm] Ar dd
515 .Sm on
516 where there is one digit before the
517 decimal-point character
518 and the number of digits after it is equal to the precision;
519 if the precision is missing,
520 it is taken as 6; if the precision is
521 zero, no decimal-point character appears.
522 An
523 .Cm E
524 conversion uses the letter
525 .Ql E
526 (rather than
527 .Ql e )
528 to introduce the exponent.
529 The exponent always contains at least two digits; if the value is zero,
530 the exponent is 00.
531 .Pp
532 For
533 .Cm a ,
534 .Cm A ,
535 .Cm e ,
536 .Cm E ,
537 .Cm f ,
538 .Cm F ,
539 .Cm g ,
540 and
541 .Cm G
542 conversions, positive and negative infinity are represented as
543 .Li inf
544 and
545 .Li -inf
546 respectively when using the lowercase conversion character, and
547 .Li INF
548 and
549 .Li -INF
550 respectively when using the uppercase conversion character.
551 Similarly, NaN is represented as
552 .Li nan
553 when using the lowercase conversion, and
554 .Li NAN
555 when using the uppercase conversion.
556 .It Cm fF
557 The
558 .Vt double
559 argument is rounded and converted to decimal notation in the style
560 .Sm off
561 .Oo \- Oc Ar ddd Li \&. Ar ddd ,
562 .Sm on
563 where the number of digits after the decimal-point character
564 is equal to the precision specification.
565 If the precision is missing, it is taken as 6; if the precision is
566 explicitly zero, no decimal-point character appears.
567 If a decimal point appears, at least one digit appears before it.
568 .It Cm gG
569 The
570 .Vt double
571 argument is converted in style
572 .Cm f
573 or
574 .Cm e
575 (or in style
576 .Cm F
577 or
578 .Cm E
579 for
580 .Cm G
581 conversions).
582 The precision specifies the number of significant digits.
583 If the precision is missing, 6 digits are given; if the precision is zero,
584 it is treated as 1.
585 Style
586 .Cm e
587 is used if the exponent from its conversion is less than \-4 or greater than
588 or equal to the precision.
589 Trailing zeros are removed from the fractional part of the result; a
590 decimal point appears only if it is followed by at least one digit.
591 .It Cm aA
592 The
593 .Vt double
594 argument is rounded and converted to hexadecimal notation in the style
595 .Sm off
596 .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \*[Pm] Oc Ar d ,
597 .Sm on
598 where the number of digits after the hexadecimal-point character
599 is equal to the precision specification.
600 If the precision is missing, it is taken as enough to represent
601 the floating-point number exactly, and no rounding occurs.
602 If the precision is zero, no hexadecimal-point character appears.
603 The
604 .Cm p
605 is a literal character
606 .Ql p ,
607 and the exponent consists of a positive or negative sign
608 followed by a decimal number representing an exponent of 2.
609 The
610 .Cm A
611 conversion uses the prefix
612 .Dq Li 0X
613 (rather than
614 .Dq Li 0x ) ,
615 the letters
616 .Dq Li ABCDEF
617 (rather than
618 .Dq Li abcdef )
619 to represent the hex digits, and the letter
620 .Ql P
621 (rather than
622 .Ql p )
623 to separate the mantissa and exponent.
624 .Pp
625 Note that there may be multiple valid ways to represent floating-point
626 numbers in this hexadecimal format.
627 For example,
628 .Li 0x3.24p+0 , 0x6.48p-1
629 and
630 .Li 0xc.9p-2
631 are all equivalent.
632 The format chosen depends on the internal representation of the
633 number, but the implementation guarantees that the length of the
634 mantissa will be minimized.
635 Zeroes are always represented with a mantissa of 0 (preceded by a
636 .Ql -
637 if appropriate) and an exponent of
638 .Li +0 .
639 .It Cm C
640 Treated as
641 .Cm c
642 with the
643 .Cm l
644 (ell) modifier.
645 .It Cm c
646 The
647 .Vt int
648 argument is converted to an
649 .Vt "unsigned char" ,
650 and the resulting character is written.
651 .Pp
652 If the
653 .Cm l
654 (ell) modifier is used, the
655 .Vt wint_t
656 argument shall be converted to a
657 .Vt wchar_t ,
658 and the (potentially multi-byte) sequence representing the
659 single wide character is written, including any shift sequences.
660 If a shift sequence is used, the shift state is also restored
661 to the original state after the character.
662 .It Cm S
663 Treated as
664 .Cm s
665 with the
666 .Cm l
667 (ell) modifier.
668 .It Cm s
669 The
670 .Vt "char *"
671 argument is expected to be a pointer to an array of character type (pointer
672 to a string).
673 Characters from the array are written up to (but not including)
674 a terminating
675 .Dv NUL
676 character;
677 if a precision is specified, no more than the number specified are
678 written.
679 If a precision is given, no null character
680 need be present; if the precision is not specified, or is greater than
681 the size of the array, the array must contain a terminating
682 .Dv NUL
683 character.
684 .Pp
685 If the
686 .Cm l
687 (ell) modifier is used, the
688 .Vt "wchar_t *"
689 argument is expected to be a pointer to an array of wide characters
690 (pointer to a wide string).
691 For each wide character in the string, the (potentially multi-byte)
692 sequence representing the
693 wide character is written, including any shift sequences.
694 If any shift sequence is used, the shift state is also restored
695 to the original state after the string.
696 Wide characters from the array are written up to (but not including)
697 a terminating wide
698 .Dv NUL
699 character;
700 if a precision is specified, no more than the number of bytes specified are
701 written (including shift sequences).
702 Partial characters are never written.
703 If a precision is given, no null character
704 need be present; if the precision is not specified, or is greater than
705 the number of bytes required to render the multibyte representation of
706 the string, the array must contain a terminating wide
707 .Dv NUL
708 character.
709 .It Cm p
710 The
711 .Vt "void *"
712 pointer argument is printed in hexadecimal (as if by
713 .Ql %#x
714 or
715 .Ql %#lx ) .
716 .It Cm n
717 The number of characters written so far is stored into the
718 integer indicated by the
719 .Vt "int *"
720 (or variant) pointer argument.
721 No argument is converted.
722 .It Cm %
723 A
724 .Ql %
725 is written.
726 No argument is converted.
727 The complete conversion specification is
728 .Ql %% .
729 .El
730 .Pp
731 The decimal point
732 character is defined in the program's locale (category
733 .Dv LC_NUMERIC ) .
734 .Pp
735 In no case does a non-existent or small field width cause truncation of
736 a numeric field; if the result of a conversion is wider than the field
737 width, the
738 field is expanded to contain the conversion result.
739 .Sh RETURN VALUES
740 These functions return
741 the number of characters printed, or that would be printed if there
742 was adequate space in case of
743 .Fn snprintf ,
744 .Fn vsnprintf ,
745 and
746 .Fn vsnprintf_ss
747 (not including the trailing
748 .Ql \e0
749 used to end output to strings).
750 If an output error was encountered, these functions shall return a
751 negative value.
752 .Sh EXAMPLES
753 To print a date and time in the form
754 .Dq Li "Sunday, July 3, 10:02" ,
755 where
756 .Fa weekday
757 and
758 .Fa month
759 are pointers to strings:
760 .Bd -literal -offset indent
761 #include \*[Lt]stdio.h\*[Gt]
762 fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
763 weekday, month, day, hour, min);
764 .Ed
765 .Pp
766 To print \*(Pi
767 to five decimal places:
768 .Bd -literal -offset indent
769 #include \*[Lt]math.h\*[Gt]
770 #include \*[Lt]stdio.h\*[Gt]
771 fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
772 .Ed
773 .Pp
774 To allocate a 128 byte string and print into it:
775 .Bd -literal -offset indent
776 #include \*[Lt]stdio.h\*[Gt]
777 #include \*[Lt]stdlib.h\*[Gt]
778 #include \*[Lt]stdarg.h\*[Gt]
779 char *newfmt(const char *fmt, ...)
780 {
781 char *p;
782 va_list ap;
783 if ((p = malloc(128)) == NULL)
784 return (NULL);
785 va_start(ap, fmt);
786 (void) vsnprintf(p, 128, fmt, ap);
787 va_end(ap);
788 return (p);
789 }
790 .Ed
791 .Sh ERRORS
792 In addition to the errors documented for the
793 .Xr write 2
794 system call, the
795 .Fn printf
796 family of functions may fail if:
797 .Bl -tag -width Er
798 .It Bq Er EILSEQ
799 An invalid wide-character code was encountered.
800 .It Bq Er ENOMEM
801 Insufficient storage space is available.
802 .It Bq Er EOVERFLOW
803 The
804 .Fa size
805 argument exceeds
806 .Dv INT_MAX ,
807 or the return value would be too large to be represented by an
808 .Vt int .
809 .El
810 .Sh SEE ALSO
811 .Xr printf 1 ,
812 .Xr fmtcheck 3 ,
813 .Xr scanf 3 ,
814 .Xr setlocale 3 ,
815 .Xr wprintf 3 ,
816 .Xr printf 9
817 .Sh STANDARDS
818 Subject to the caveats noted in the
819 .Sx BUGS
820 section below, the
821 .Fn fprintf ,
822 .Fn printf ,
823 .Fn sprintf ,
824 .Fn vprintf ,
825 .Fn vfprintf ,
826 and
827 .Fn vsprintf
828 functions
829 conform to
830 .St -ansiC
831 and
832 .St -isoC-99 .
833 With the same reservation, the
834 .Fn snprintf
835 and
836 .Fn vsnprintf
837 functions conform to
838 .St -isoC-99 .
839 .Sh HISTORY
840 The functions
841 .Fn snprintf
842 and
843 .Fn vsnprintf
844 first appeared in
845 .Bx 4.4 .
846 The functions
847 .Fn asprintf
848 and
849 .Fn vasprintf
850 are modeled on the ones that first appeared in the GNU C library.
851 The function
852 .Fn vsnprintf_ss
853 is non-standard and appeared in
854 .Nx 4.0 .
855 The functions
856 .Fn dprintf
857 and
858 .Fn vdprintf
859 are parts of
860 .St -p1003.1-2008
861 and appeared in
862 .Nx 6.0 .
863 .Sh CAVEATS
864 Because
865 .Fn sprintf
866 and
867 .Fn vsprintf
868 assume an infinitely long string, callers must be careful not to
869 overflow the actual space; this is often impossible to assure.
870 For safety, programmers should use the
871 .Fn snprintf
872 and
873 .Fn asprintf
874 family of interfaces instead.
875 Unfortunately, the
876 .Fn snprintf
877 interfaces are not available on older
878 systems and the
879 .Fn asprintf
880 interfaces are not yet portable.
881 .Pp
882 It is important never to pass a string with user-supplied data as a
883 format without using
884 .Ql %s .
885 An attacker can put format specifiers in the string to mangle your stack,
886 leading to a possible security hole.
887 This holds true even if you have built the string
888 .Dq by hand
889 using a function like
890 .Fn snprintf ,
891 as the resulting string may still contain user-supplied conversion specifiers
892 for later interpolation by
893 .Fn printf .
894 .Pp
895 Be sure to use the proper secure idiom:
896 .Bd -literal -offset indent
897 snprintf(buffer, sizeof(buffer), "%s", string);
898 .Ed
899 .Pp
900 There is no way for
901 .Fn printf
902 to know the size of each argument passed.
903 If you use positional arguments you must ensure that all parameters, up to the
904 last positionally specified parameter, are used in the format string.
905 This allows for the format string to be parsed for this information.
906 Failure to do this will mean your code is non-portable and liable to fail.
907 .Pp
908 In this implementation, passing a
909 .Dv NULL
910 .Vt char *
911 argument to the
912 .Cm %s
913 format specifier will output
914 .Em "(null)"
915 instead of crashing.
916 Programs that depend on this behavior are non-portable and may crash
917 on other systems or in the future.
918 .Sh BUGS
919 The conversion formats
920 .Cm \&%D ,
921 .Cm \&%O ,
922 and
923 .Cm \&%U
924 are not standard and are provided only for backward compatibility.
925 The effect of padding the
926 .Cm %p
927 format with zeros (either by the
928 .Sq Cm 0
929 flag or by specifying a precision), and the benign effect (i.e. none)
930 of the
931 .Sq Cm #
932 flag on
933 .Cm %n
934 and
935 .Cm %p
936 conversions, as well as other nonsensical combinations such as
937 .Cm %Ld ,
938 are not standard; such combinations should be avoided.
939 .Pp
940 The
941 .Nm
942 family of functions do not correctly handle multibyte characters in the
943 .Fa format
944 argument.
945 .Sh SECURITY CONSIDERATIONS
946 The
947 .Fn sprintf
948 and
949 .Fn vsprintf
950 functions are easily misused in a manner which enables malicious users
951 to arbitrarily change a running program's functionality through
952 a buffer overflow attack.
953 Because
954 .Fn sprintf
955 and
956 .Fn vsprintf
957 assume an infinitely long string,
958 callers must be careful not to overflow the actual space;
959 this is often hard to assure.
960 For safety, programmers should use the
961 .Fn snprintf
962 interface instead.
963 For example:
964 .Bd -literal
965 void
966 foo(const char *arbitrary_string, const char *and_another)
967 {
968 char onstack[8];
970 #ifdef BAD
971 /*
972 * This first sprintf is bad behavior. Do not use sprintf!
973 */
974 sprintf(onstack, "%s, %s", arbitrary_string, and_another);
975 #else
976 /*
977 * The following two lines demonstrate better use of
978 * snprintf().
979 */
980 snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
981 and_another);
982 #endif
983 }
984 .Ed
985 .Pp
986 The
987 .Fn printf
988 and
989 .Fn sprintf
990 family of functions are also easily misused in a manner
991 allowing malicious users to arbitrarily change a running program's
992 functionality by either causing the program
993 to print potentially sensitive data
994 .Dq "left on the stack" ,
995 or causing it to generate a memory fault or bus error
996 by dereferencing an invalid pointer.
997 .Pp
998 .Cm %n
999 can be used to write arbitrary data to potentially carefully-selected
1000 addresses.
1001 Programmers are therefore strongly advised to never pass untrusted strings
1002 as the
1003 .Fa format
1004 argument, as an attacker can put format specifiers in the string
1005 to mangle your stack,
1006 leading to a possible security hole.
1007 This holds true even if the string was built using a function like
1008 .Fn snprintf ,
1009 as the resulting string may still contain user-supplied conversion specifiers
1010 for later interpolation by
1011 .Fn printf .
1012 .Pp
1013 Always use the proper secure idiom:
1014 .Pp
1015 .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"