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