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. All advertising materials mentioning features or use of this software
17.\" must display the following acknowledgement:
18.\" This product includes software developed by the University of
19.\" California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\" may be used to endorse or promote products derived from this software
22.\" without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)printf.3 8.1 (Berkeley) 6/4/93
| 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. All advertising materials mentioning features or use of this software
17.\" must display the following acknowledgement:
18.\" This product includes software developed by the University of
19.\" California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\" may be used to endorse or promote products derived from this software
22.\" without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)printf.3 8.1 (Berkeley) 6/4/93
|
38.\"
39.Dd June 4, 1993
40.Dt PRINTF 3
41.Os
42.Sh NAME
43.Nm printf ,
44.Nm fprintf ,
45.Nm sprintf ,
46.Nm snprintf ,
47.Nm asprintf ,
48.Nm vprintf ,
49.Nm vfprintf,
50.Nm vsprintf ,
51.Nm vsnprintf ,
52.Nm vasprintf
53.Nd formatted output conversion
54.Sh SYNOPSIS
55.Fd #include <stdio.h>
56.Ft int
57.Fn printf "const char *format" ...
58.Ft int
59.Fn fprintf "FILE *stream" "const char *format" ...
60.Ft int
61.Fn sprintf "char *str" "const char *format" ...
62.Ft int
63.Fn snprintf "char *str" "size_t size" "const char *format" ...
64.Ft int
65.Fn asprintf "char **ret" "const char *format" ...
66.Fd #include <stdarg.h>
67.Ft int
68.Fn vprintf "const char *format" "va_list ap"
69.Ft int
70.Fn vfprintf "FILE *stream" "const char *format" "va_list ap"
71.Ft int
72.Fn vsprintf "char *str" "const char *format" "va_list ap"
73.Ft int
74.Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap"
75.Ft int
76.Fn vasprintf "char **ret" "const char *format" "va_list ap"
77.Sh DESCRIPTION
78The
79.Fn printf
80family of functions produces output according to a
81.Fa format
82as described below.
83.Fn Printf
84and
85.Fn vprintf
86write output to
87.Em stdout,
88the standard output stream;
89.Fn fprintf
90and
91.Fn vfprintf
92write output to the given output
93.Fa stream ;
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
108These functions write the output under the control of a
109.Fa format
110string that specifies how subsequent arguments
111(or arguments accessed via the variable-length argument facilities of
112.Xr stdarg 3 )
113are converted for output.
114.Pp
115These functions return
116the number of characters printed
117(not including the trailing
118.Ql \e0
119used to end output to strings).
120.Pp
121.Fn Asprintf
122and
123.Fn vasprintf
124return a pointer to a buffer sufficiently large to hold the
125string in the
126.Fa ret
127argument;
128This pointer should be passed to
129.Xr free 3
130to release the allocated storage when it is no longer needed.
131If sufficient space cannot be allocated,
132.Fn asprintf
133and
134.Fn vasprintf
135will return -1 and set
136.Fa ret
137to be a NULL pointer.
138.Pp
139.Fn Snprintf
140and
141.Fn vsnprintf
142will write at most
143.Fa size Ns \-1
144of the characters printed into the output string
145(the
146.Fa size Ns 'th
147character then gets the terminating
148.Ql \e0 ) ;
149if the return value is greater than or equal to the
150.Fa size
151argument, the string was too short
152and some of the printed characters were discarded.
153.Pp
154.Fn Sprintf
155and
156.Fn vsprintf
157effectively assume an infinite
158.Fa size .
159.Pp
160The format string is composed of zero or more directives:
161ordinary
162.\" multibyte
163characters (not
164.Cm % ) ,
165which are copied unchanged to the output stream;
166and conversion specifications, each of which results
167in fetching zero or more subsequent arguments.
168Each conversion specification is introduced by
169the character
170.Cm % .
171The arguments must correspond properly (after type promotion)
172with the conversion specifier.
173After the
174.Cm % ,
175the following appear in sequence:
176.Bl -bullet
177.It
178An optional field, consisting of a decimal digit string followed by a
179.Cm $ ,
180specifying the next argument to access .
181If this field is not provided, the argument following the last
182argument accessed will be used.
183Arguments are numbered starting at
184.Cm 1 .
185If unaccessed arguments in the format string are interspersed with ones that
186are accessed the results will be indeterminate.
187.It
188Zero or more of the following flags:
189.Bl -hyphen
190.It
191A
192.Cm #
193character
194specifying that the value should be converted to an ``alternate form''.
195For
196.Cm c ,
197.Cm d ,
198.Cm i ,
199.Cm n ,
200.Cm p ,
201.Cm s ,
202and
203.Cm u ,
204conversions, this option has no effect.
205For
206.Cm o
207conversions, the precision of the number is increased to force the first
208character of the output string to a zero (except if a zero value is printed
209with an explicit precision of zero).
210For
211.Cm x
212and
213.Cm X
214conversions, a non-zero result has the string
215.Ql 0x
216(or
217.Ql 0X
218for
219.Cm X
220conversions) prepended to it.
221For
222.Cm e ,
223.Cm E ,
224.Cm f ,
225.Cm g ,
226and
227.Cm G ,
228conversions, the result will always contain a decimal point, even if no
229digits follow it (normally, a decimal point appears in the results of
230those conversions only if a digit follows).
231For
232.Cm g
233and
234.Cm G
235conversions, trailing zeros are not removed from the result as they
236would otherwise be.
237.It
238A zero
239.Sq Cm \&0
240character specifying zero padding.
241For all conversions except
242.Cm n ,
243the converted value is padded on the left with zeros rather than blanks.
244If a precision is given with a numeric conversion
245.Pf ( Cm d ,
246.Cm i ,
247.Cm o ,
248.Cm u ,
249.Cm i ,
250.Cm x ,
251and
252.Cm X ) ,
253the
254.Sq Cm \&0
255flag is ignored.
256.It
257A negative field width flag
258.Sq Cm \-
259indicates the converted value is to be left adjusted on the field boundary.
260Except for
261.Cm n
262conversions, the converted value is padded on the right with blanks,
263rather than on the left with blanks or zeros.
264A
265.Sq Cm \-
266overrides a
267.Sq Cm \&0
268if both are given.
269.It
270A space, specifying that a blank should be left before a positive number
271produced by a signed conversion
272.Pf ( Cm d ,
273.Cm e ,
274.Cm E ,
275.Cm f ,
276.Cm g ,
277.Cm G ,
278or
279.Cm i ) .
280.It
281A
282.Sq Cm +
283character specifying that a sign always be placed before a
284number produced by a signed conversion.
285A
286.Sq Cm +
287overrides a space if both are used.
288.El
289.It
290An optional decimal digit string specifying a minimum field width.
291If the converted value has fewer characters than the field width, it will
292be padded with spaces on the left (or right, if the left-adjustment
293flag has been given) to fill out
294the field width.
295.It
296An optional precision, in the form of a period
297.Sq Cm \&.
298followed by an
299optional digit string. If the digit string is omitted, the precision
300is taken as zero. This gives the minimum number of digits to appear for
301.Cm d ,
302.Cm i ,
303.Cm o ,
304.Cm u ,
305.Cm x ,
306and
307.Cm X
308conversions, the number of digits to appear after the decimal-point for
309.Cm e ,
310.Cm E ,
311and
312.Cm f
313conversions, the maximum number of significant digits for
314.Cm g
315and
316.Cm G
317conversions, or the maximum number of characters to be printed from a
318string for
319.Cm s
320conversions.
321.It
322The optional character
323.Cm h ,
324specifying that a following
325.Cm d ,
326.Cm i ,
327.Cm o ,
328.Cm u ,
329.Cm x ,
330or
331.Cm X
332conversion corresponds to a
333.Em short int
334or
335.Em unsigned short int
336argument, or that a following
337.Cm n
338conversion corresponds to a pointer to a
339.Em short int
340argument.
341.It
342The optional character
343.Cm l
344(ell) specifying that a following
345.Cm d ,
346.Cm i ,
347.Cm o ,
348.Cm u ,
349.Cm x ,
350or
351.Cm X
352conversion applies to a pointer to a
353.Em long int
354or
355.Em unsigned long int
356argument, or that a following
357.Cm n
358conversion corresponds to a pointer to a
359.Em long int
360argument.
361.It
362The optional character
363.Cm q ,
364specifying that a following
365.Cm d ,
366.Cm i ,
367.Cm o ,
368.Cm u ,
369.Cm x ,
370or
371.Cm X
372conversion corresponds to a
373.Em quad int
374or
375.Em unsigned quad int
376argument, or that a following
377.Cm n
378conversion corresponds to a pointer to a
379.Em quad int
380argument.
381.It
382The character
383.Cm L
384specifying that a following
385.Cm e ,
386.Cm E ,
387.Cm f ,
388.Cm g ,
389or
390.Cm G
391conversion corresponds to a
392.Em long double
393argument.
394.It
395A character that specifies the type of conversion to be applied.
396.El
397.Pp
398A field width or precision, or both, may be indicated by
399an asterisk
400.Ql *
401or an asterisk followed by one or more decimal digits and a
402.Ql $
403instead of a
404digit string.
405In this case, an
406.Em int
407argument supplies the field width or precision.
408A negative field width is treated as a left adjustment flag followed by a
409positive field width; a negative precision is treated as though it were
410missing.
411If a single format directive mixes positional (nn$)
412and non-positional arguments, the results are undefined.
413.Pp
414The conversion specifiers and their meanings are:
415.Bl -tag -width "diouxX"
416.It Cm diouxX
417The
418.Em int
419(or appropriate variant) argument is converted to signed decimal
420.Pf ( Cm d
421and
422.Cm i ) ,
423unsigned octal
424.Pq Cm o ,
425unsigned decimal
426.Pq Cm u ,
427or unsigned hexadecimal
428.Pf ( Cm x
429and
430.Cm X )
431notation. The letters
432.Cm abcdef
433are used for
434.Cm x
435conversions; the letters
436.Cm ABCDEF
437are used for
438.Cm X
439conversions.
440The precision, if any, gives the minimum number of digits that must
441appear; if the converted value requires fewer digits, it is padded on
442the left with zeros.
443.It Cm DOU
444The
445.Em long int
446argument is converted to signed decimal, unsigned octal, or unsigned
447decimal, as if the format had been
448.Cm ld ,
449.Cm lo ,
450or
451.Cm lu
452respectively.
453These conversion characters are deprecated, and will eventually disappear.
454.It Cm eE
455The
456.Em double
457argument is rounded and converted in the style
458.Sm off
459.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
460.Sm on
461where there is one digit before the
462decimal-point character
463and the number of digits after it is equal to the precision;
464if the precision is missing,
465it is taken as 6; if the precision is
466zero, no decimal-point character appears.
467An
468.Cm E
469conversion uses the letter
470.Cm E
471(rather than
472.Cm e )
473to introduce the exponent.
474The exponent always contains at least two digits; if the value is zero,
475the exponent is 00.
476.It Cm f
477The
478.Em double
479argument is rounded and converted to decimal notation in the style
480.Sm off
481.Pf [-]ddd Cm \&. No ddd ,
482.Sm on
483where the number of digits after the decimal-point character
484is equal to the precision specification.
485If the precision is missing, it is taken as 6; if the precision is
486explicitly zero, no decimal-point character appears.
487If a decimal point appears, at least one digit appears before it.
488.It Cm gG
489The
490.Em double
491argument is converted in style
492.Cm f
493or
494.Cm e
495(or
496.Cm E
497for
498.Cm G
499conversions).
500The precision specifies the number of significant digits.
501If the precision is missing, 6 digits are given; if the precision is zero,
502it is treated as 1.
503Style
504.Cm e
505is used if the exponent from its conversion is less than -4 or greater than
506or equal to the precision.
507Trailing zeros are removed from the fractional part of the result; a
508decimal point appears only if it is followed by at least one digit.
509.It Cm c
510The
511.Em int
512argument is converted to an
513.Em unsigned char ,
514and the resulting character is written.
515.It Cm s
516The
517.Dq Em char *
518argument is expected to be a pointer to an array of character type (pointer
519to a string).
520Characters from the array are written up to (but not including)
521a terminating
522.Dv NUL
523character;
524if a precision is specified, no more than the number specified are
525written.
526If a precision is given, no null character
527need be present; if the precision is not specified, or is greater than
528the size of the array, the array must contain a terminating
529.Dv NUL
530character.
531.It Cm p
532The
533.Dq Em void *
534pointer argument is printed in hexadecimal (as if by
535.Ql %#x
536or
537.Ql %#lx ) .
538.It Cm n
539The number of characters written so far is stored into the
540integer indicated by the
541.Dq Em int *
542(or variant) pointer argument.
543No argument is converted.
544.It Cm %
545A
546.Ql %
| 38.\"
39.Dd June 4, 1993
40.Dt PRINTF 3
41.Os
42.Sh NAME
43.Nm printf ,
44.Nm fprintf ,
45.Nm sprintf ,
46.Nm snprintf ,
47.Nm asprintf ,
48.Nm vprintf ,
49.Nm vfprintf,
50.Nm vsprintf ,
51.Nm vsnprintf ,
52.Nm vasprintf
53.Nd formatted output conversion
54.Sh SYNOPSIS
55.Fd #include <stdio.h>
56.Ft int
57.Fn printf "const char *format" ...
58.Ft int
59.Fn fprintf "FILE *stream" "const char *format" ...
60.Ft int
61.Fn sprintf "char *str" "const char *format" ...
62.Ft int
63.Fn snprintf "char *str" "size_t size" "const char *format" ...
64.Ft int
65.Fn asprintf "char **ret" "const char *format" ...
66.Fd #include <stdarg.h>
67.Ft int
68.Fn vprintf "const char *format" "va_list ap"
69.Ft int
70.Fn vfprintf "FILE *stream" "const char *format" "va_list ap"
71.Ft int
72.Fn vsprintf "char *str" "const char *format" "va_list ap"
73.Ft int
74.Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap"
75.Ft int
76.Fn vasprintf "char **ret" "const char *format" "va_list ap"
77.Sh DESCRIPTION
78The
79.Fn printf
80family of functions produces output according to a
81.Fa format
82as described below.
83.Fn Printf
84and
85.Fn vprintf
86write output to
87.Em stdout,
88the standard output stream;
89.Fn fprintf
90and
91.Fn vfprintf
92write output to the given output
93.Fa stream ;
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
108These functions write the output under the control of a
109.Fa format
110string that specifies how subsequent arguments
111(or arguments accessed via the variable-length argument facilities of
112.Xr stdarg 3 )
113are converted for output.
114.Pp
115These functions return
116the number of characters printed
117(not including the trailing
118.Ql \e0
119used to end output to strings).
120.Pp
121.Fn Asprintf
122and
123.Fn vasprintf
124return a pointer to a buffer sufficiently large to hold the
125string in the
126.Fa ret
127argument;
128This pointer should be passed to
129.Xr free 3
130to release the allocated storage when it is no longer needed.
131If sufficient space cannot be allocated,
132.Fn asprintf
133and
134.Fn vasprintf
135will return -1 and set
136.Fa ret
137to be a NULL pointer.
138.Pp
139.Fn Snprintf
140and
141.Fn vsnprintf
142will write at most
143.Fa size Ns \-1
144of the characters printed into the output string
145(the
146.Fa size Ns 'th
147character then gets the terminating
148.Ql \e0 ) ;
149if the return value is greater than or equal to the
150.Fa size
151argument, the string was too short
152and some of the printed characters were discarded.
153.Pp
154.Fn Sprintf
155and
156.Fn vsprintf
157effectively assume an infinite
158.Fa size .
159.Pp
160The format string is composed of zero or more directives:
161ordinary
162.\" multibyte
163characters (not
164.Cm % ) ,
165which are copied unchanged to the output stream;
166and conversion specifications, each of which results
167in fetching zero or more subsequent arguments.
168Each conversion specification is introduced by
169the character
170.Cm % .
171The arguments must correspond properly (after type promotion)
172with the conversion specifier.
173After the
174.Cm % ,
175the following appear in sequence:
176.Bl -bullet
177.It
178An optional field, consisting of a decimal digit string followed by a
179.Cm $ ,
180specifying the next argument to access .
181If this field is not provided, the argument following the last
182argument accessed will be used.
183Arguments are numbered starting at
184.Cm 1 .
185If unaccessed arguments in the format string are interspersed with ones that
186are accessed the results will be indeterminate.
187.It
188Zero or more of the following flags:
189.Bl -hyphen
190.It
191A
192.Cm #
193character
194specifying that the value should be converted to an ``alternate form''.
195For
196.Cm c ,
197.Cm d ,
198.Cm i ,
199.Cm n ,
200.Cm p ,
201.Cm s ,
202and
203.Cm u ,
204conversions, this option has no effect.
205For
206.Cm o
207conversions, the precision of the number is increased to force the first
208character of the output string to a zero (except if a zero value is printed
209with an explicit precision of zero).
210For
211.Cm x
212and
213.Cm X
214conversions, a non-zero result has the string
215.Ql 0x
216(or
217.Ql 0X
218for
219.Cm X
220conversions) prepended to it.
221For
222.Cm e ,
223.Cm E ,
224.Cm f ,
225.Cm g ,
226and
227.Cm G ,
228conversions, the result will always contain a decimal point, even if no
229digits follow it (normally, a decimal point appears in the results of
230those conversions only if a digit follows).
231For
232.Cm g
233and
234.Cm G
235conversions, trailing zeros are not removed from the result as they
236would otherwise be.
237.It
238A zero
239.Sq Cm \&0
240character specifying zero padding.
241For all conversions except
242.Cm n ,
243the converted value is padded on the left with zeros rather than blanks.
244If a precision is given with a numeric conversion
245.Pf ( Cm d ,
246.Cm i ,
247.Cm o ,
248.Cm u ,
249.Cm i ,
250.Cm x ,
251and
252.Cm X ) ,
253the
254.Sq Cm \&0
255flag is ignored.
256.It
257A negative field width flag
258.Sq Cm \-
259indicates the converted value is to be left adjusted on the field boundary.
260Except for
261.Cm n
262conversions, the converted value is padded on the right with blanks,
263rather than on the left with blanks or zeros.
264A
265.Sq Cm \-
266overrides a
267.Sq Cm \&0
268if both are given.
269.It
270A space, specifying that a blank should be left before a positive number
271produced by a signed conversion
272.Pf ( Cm d ,
273.Cm e ,
274.Cm E ,
275.Cm f ,
276.Cm g ,
277.Cm G ,
278or
279.Cm i ) .
280.It
281A
282.Sq Cm +
283character specifying that a sign always be placed before a
284number produced by a signed conversion.
285A
286.Sq Cm +
287overrides a space if both are used.
288.El
289.It
290An optional decimal digit string specifying a minimum field width.
291If the converted value has fewer characters than the field width, it will
292be padded with spaces on the left (or right, if the left-adjustment
293flag has been given) to fill out
294the field width.
295.It
296An optional precision, in the form of a period
297.Sq Cm \&.
298followed by an
299optional digit string. If the digit string is omitted, the precision
300is taken as zero. This gives the minimum number of digits to appear for
301.Cm d ,
302.Cm i ,
303.Cm o ,
304.Cm u ,
305.Cm x ,
306and
307.Cm X
308conversions, the number of digits to appear after the decimal-point for
309.Cm e ,
310.Cm E ,
311and
312.Cm f
313conversions, the maximum number of significant digits for
314.Cm g
315and
316.Cm G
317conversions, or the maximum number of characters to be printed from a
318string for
319.Cm s
320conversions.
321.It
322The optional character
323.Cm h ,
324specifying that a following
325.Cm d ,
326.Cm i ,
327.Cm o ,
328.Cm u ,
329.Cm x ,
330or
331.Cm X
332conversion corresponds to a
333.Em short int
334or
335.Em unsigned short int
336argument, or that a following
337.Cm n
338conversion corresponds to a pointer to a
339.Em short int
340argument.
341.It
342The optional character
343.Cm l
344(ell) specifying that a following
345.Cm d ,
346.Cm i ,
347.Cm o ,
348.Cm u ,
349.Cm x ,
350or
351.Cm X
352conversion applies to a pointer to a
353.Em long int
354or
355.Em unsigned long int
356argument, or that a following
357.Cm n
358conversion corresponds to a pointer to a
359.Em long int
360argument.
361.It
362The optional character
363.Cm q ,
364specifying that a following
365.Cm d ,
366.Cm i ,
367.Cm o ,
368.Cm u ,
369.Cm x ,
370or
371.Cm X
372conversion corresponds to a
373.Em quad int
374or
375.Em unsigned quad int
376argument, or that a following
377.Cm n
378conversion corresponds to a pointer to a
379.Em quad int
380argument.
381.It
382The character
383.Cm L
384specifying that a following
385.Cm e ,
386.Cm E ,
387.Cm f ,
388.Cm g ,
389or
390.Cm G
391conversion corresponds to a
392.Em long double
393argument.
394.It
395A character that specifies the type of conversion to be applied.
396.El
397.Pp
398A field width or precision, or both, may be indicated by
399an asterisk
400.Ql *
401or an asterisk followed by one or more decimal digits and a
402.Ql $
403instead of a
404digit string.
405In this case, an
406.Em int
407argument supplies the field width or precision.
408A negative field width is treated as a left adjustment flag followed by a
409positive field width; a negative precision is treated as though it were
410missing.
411If a single format directive mixes positional (nn$)
412and non-positional arguments, the results are undefined.
413.Pp
414The conversion specifiers and their meanings are:
415.Bl -tag -width "diouxX"
416.It Cm diouxX
417The
418.Em int
419(or appropriate variant) argument is converted to signed decimal
420.Pf ( Cm d
421and
422.Cm i ) ,
423unsigned octal
424.Pq Cm o ,
425unsigned decimal
426.Pq Cm u ,
427or unsigned hexadecimal
428.Pf ( Cm x
429and
430.Cm X )
431notation. The letters
432.Cm abcdef
433are used for
434.Cm x
435conversions; the letters
436.Cm ABCDEF
437are used for
438.Cm X
439conversions.
440The precision, if any, gives the minimum number of digits that must
441appear; if the converted value requires fewer digits, it is padded on
442the left with zeros.
443.It Cm DOU
444The
445.Em long int
446argument is converted to signed decimal, unsigned octal, or unsigned
447decimal, as if the format had been
448.Cm ld ,
449.Cm lo ,
450or
451.Cm lu
452respectively.
453These conversion characters are deprecated, and will eventually disappear.
454.It Cm eE
455The
456.Em double
457argument is rounded and converted in the style
458.Sm off
459.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd
460.Sm on
461where there is one digit before the
462decimal-point character
463and the number of digits after it is equal to the precision;
464if the precision is missing,
465it is taken as 6; if the precision is
466zero, no decimal-point character appears.
467An
468.Cm E
469conversion uses the letter
470.Cm E
471(rather than
472.Cm e )
473to introduce the exponent.
474The exponent always contains at least two digits; if the value is zero,
475the exponent is 00.
476.It Cm f
477The
478.Em double
479argument is rounded and converted to decimal notation in the style
480.Sm off
481.Pf [-]ddd Cm \&. No ddd ,
482.Sm on
483where the number of digits after the decimal-point character
484is equal to the precision specification.
485If the precision is missing, it is taken as 6; if the precision is
486explicitly zero, no decimal-point character appears.
487If a decimal point appears, at least one digit appears before it.
488.It Cm gG
489The
490.Em double
491argument is converted in style
492.Cm f
493or
494.Cm e
495(or
496.Cm E
497for
498.Cm G
499conversions).
500The precision specifies the number of significant digits.
501If the precision is missing, 6 digits are given; if the precision is zero,
502it is treated as 1.
503Style
504.Cm e
505is used if the exponent from its conversion is less than -4 or greater than
506or equal to the precision.
507Trailing zeros are removed from the fractional part of the result; a
508decimal point appears only if it is followed by at least one digit.
509.It Cm c
510The
511.Em int
512argument is converted to an
513.Em unsigned char ,
514and the resulting character is written.
515.It Cm s
516The
517.Dq Em char *
518argument is expected to be a pointer to an array of character type (pointer
519to a string).
520Characters from the array are written up to (but not including)
521a terminating
522.Dv NUL
523character;
524if a precision is specified, no more than the number specified are
525written.
526If a precision is given, no null character
527need be present; if the precision is not specified, or is greater than
528the size of the array, the array must contain a terminating
529.Dv NUL
530character.
531.It Cm p
532The
533.Dq Em void *
534pointer argument is printed in hexadecimal (as if by
535.Ql %#x
536or
537.Ql %#lx ) .
538.It Cm n
539The number of characters written so far is stored into the
540integer indicated by the
541.Dq Em int *
542(or variant) pointer argument.
543No argument is converted.
544.It Cm %
545A
546.Ql %
|
548is
549.Ql %% .
550.El
551.Pp
552In no case does a non-existent or small field width cause truncation of
553a field; if the result of a conversion is wider than the field width, the
554field is expanded to contain the conversion result.
555.Pp
556.Sh EXAMPLES
557.br
558To print a date and time in the form `Sunday, July 3, 10:02',
559where
560.Em weekday
561and
562.Em month
563are pointers to strings:
564.Bd -literal -offset indent
565#include <stdio.h>
566fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
567 weekday, month, day, hour, min);
568.Ed
569.Pp
570To print \*(Pi
571to five decimal places:
572.Bd -literal -offset indent
573#include <math.h>
574#include <stdio.h>
575fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
576.Ed
577.Pp
578To allocate a 128 byte string and print into it:
579.Bd -literal -offset indent
580#include <stdio.h>
581#include <stdlib.h>
582#include <stdarg.h>
583char *newfmt(const char *fmt, ...)
584{
585 char *p;
586 va_list ap;
587 if ((p = malloc(128)) == NULL)
588 return (NULL);
589 va_start(ap, fmt);
590 (void) vsnprintf(p, 128, fmt, ap);
591 va_end(ap);
592 return (p);
593}
594.Ed
595.Sh SEE ALSO
596.Xr printf 1 ,
597.Xr scanf 3
598.Sh STANDARDS
599The
600.Fn fprintf ,
601.Fn printf ,
602.Fn sprintf ,
603.Fn vprintf ,
604.Fn vfprintf ,
605and
606.Fn vsprintf
607functions
608conform to
609.St -ansiC .
610.Sh HISTORY
611The functions
612.Fn asprintf
613and
614.Fn vasprintf
615first appeared in the GNU C library.
616These were implemented by Peter Wemm <peter@FreeBSD.org> in
617.Fx 2.2 ,
618but were later replaced with a different implementation
619from Todd C. Miller <Todd.Miller@courtesan.com> for
620.Ox 2.3 .
621.Sh BUGS
622The conversion formats
623.Cm \&%D ,
624.Cm \&%O ,
625and
626.Cm %U
627are not standard and
628are provided only for backward compatibility.
629The effect of padding the
630.Cm %p
631format with zeros (either by the
632.Sq Cm 0
633flag or by specifying a precision), and the benign effect (i.e., none)
634of the
635.Sq Cm #
636flag on
637.Cm %n
638and
639.Cm %p
640conversions, as well as other
641nonsensical combinations such as
642.Cm %Ld ,
643are not standard; such combinations
644should be avoided.
645.Pp
646Because
647.Fn sprintf
648and
649.Fn vsprintf
650assume an infinitely long string,
651callers must be careful not to overflow the actual space;
652this is often hard to assure.
653For safety, programmers should use the
654.Fn snprintf
655interface instead.
656Unfortunately, this interface is not portable.
| 549is
550.Ql %% .
551.El
552.Pp
553In no case does a non-existent or small field width cause truncation of
554a field; if the result of a conversion is wider than the field width, the
555field is expanded to contain the conversion result.
556.Pp
557.Sh EXAMPLES
558.br
559To print a date and time in the form `Sunday, July 3, 10:02',
560where
561.Em weekday
562and
563.Em month
564are pointers to strings:
565.Bd -literal -offset indent
566#include <stdio.h>
567fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
568 weekday, month, day, hour, min);
569.Ed
570.Pp
571To print \*(Pi
572to five decimal places:
573.Bd -literal -offset indent
574#include <math.h>
575#include <stdio.h>
576fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
577.Ed
578.Pp
579To allocate a 128 byte string and print into it:
580.Bd -literal -offset indent
581#include <stdio.h>
582#include <stdlib.h>
583#include <stdarg.h>
584char *newfmt(const char *fmt, ...)
585{
586 char *p;
587 va_list ap;
588 if ((p = malloc(128)) == NULL)
589 return (NULL);
590 va_start(ap, fmt);
591 (void) vsnprintf(p, 128, fmt, ap);
592 va_end(ap);
593 return (p);
594}
595.Ed
596.Sh SEE ALSO
597.Xr printf 1 ,
598.Xr scanf 3
599.Sh STANDARDS
600The
601.Fn fprintf ,
602.Fn printf ,
603.Fn sprintf ,
604.Fn vprintf ,
605.Fn vfprintf ,
606and
607.Fn vsprintf
608functions
609conform to
610.St -ansiC .
611.Sh HISTORY
612The functions
613.Fn asprintf
614and
615.Fn vasprintf
616first appeared in the GNU C library.
617These were implemented by Peter Wemm <peter@FreeBSD.org> in
618.Fx 2.2 ,
619but were later replaced with a different implementation
620from Todd C. Miller <Todd.Miller@courtesan.com> for
621.Ox 2.3 .
622.Sh BUGS
623The conversion formats
624.Cm \&%D ,
625.Cm \&%O ,
626and
627.Cm %U
628are not standard and
629are provided only for backward compatibility.
630The effect of padding the
631.Cm %p
632format with zeros (either by the
633.Sq Cm 0
634flag or by specifying a precision), and the benign effect (i.e., none)
635of the
636.Sq Cm #
637flag on
638.Cm %n
639and
640.Cm %p
641conversions, as well as other
642nonsensical combinations such as
643.Cm %Ld ,
644are not standard; such combinations
645should be avoided.
646.Pp
647Because
648.Fn sprintf
649and
650.Fn vsprintf
651assume an infinitely long string,
652callers must be careful not to overflow the actual space;
653this is often hard to assure.
654For safety, programmers should use the
655.Fn snprintf
656interface instead.
657Unfortunately, this interface is not portable.
|