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