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