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