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: src/lib/libc/stdio/printf.3,v 1.47 2002/09/06 11:23:55 tjr Exp
34.\" $FreeBSD: head/lib/libc/stdio/wprintf.3 207940 2010-05-11 23:08:15Z uqs $
35.\"
36.Dd July 5, 2003
37.Dt WPRINTF 3
38.Os
39.Sh NAME
40.Nm wprintf , fwprintf , swprintf ,
41.Nm vwprintf , vfwprintf , vswprintf
42.Nd formatted wide character output conversion
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In stdio.h
47.In wchar.h
48.Ft int
49.Fn fwprintf "FILE * restrict stream" "const wchar_t * restrict format" ...
50.Ft int
51.Fn swprintf "wchar_t * restrict ws" "size_t n" "const wchar_t * restrict format" ...
52.Ft int
53.Fn wprintf "const wchar_t * restrict format" ...
54.In stdarg.h
55.Ft int
56.Fn vfwprintf "FILE * restrict stream" "const wchar_t * restrict" "va_list ap"
57.Ft int
58.Fn vswprintf "wchar_t * restrict ws" "size_t n" "const wchar_t *restrict format" "va_list ap"
59.Ft int
60.Fn vwprintf "const wchar_t * restrict format" "va_list ap"
61.Sh DESCRIPTION
62The
63.Fn wprintf
64family of functions produces output according to a
65.Fa format
66as described below.
67The
68.Fn wprintf
69and
70.Fn vwprintf
71functions
72write output to
73.Dv stdout ,
74the standard output stream;
75.Fn fwprintf
76and
77.Fn vfwprintf
78write output to the given output
79.Fa stream ;
80.Fn swprintf
81and
82.Fn vswprintf
83write to the wide character string
84.Fa ws .
85.Pp
86These functions write the output under the control of a
87.Fa format
88string that specifies how subsequent arguments
89(or arguments accessed via the variable-length argument facilities of
90.Xr stdarg 3 )
91are converted for output.
92.Pp
93These functions return the number of characters printed
94(not including the trailing
95.Ql \e0
96used to end output to strings).
97.Pp
98The
99.Fn swprintf
100and
101.Fn vswprintf
102functions will fail if
103.Fa n
104or more wide characters were requested to be written,
105.Pp
106The format string is composed of zero or more directives:
107ordinary
108characters (not
109.Cm % ) ,
110which are copied unchanged to the output stream;
111and conversion specifications, each of which results
112in fetching zero or more subsequent arguments.
113Each conversion specification is introduced by
114the
115.Cm %
116character.
117The arguments must correspond properly (after type promotion)
118with the conversion specifier.
119After the
120.Cm % ,
121the following appear in sequence:
122.Bl -bullet
123.It
124An optional field, consisting of a decimal digit string followed by a
125.Cm $ ,
126specifying the next argument to access.
127If this field is not provided, the argument following the last
128argument accessed will be used.
129Arguments are numbered starting at
130.Cm 1 .
131If unaccessed arguments in the format string are interspersed with ones that
132are accessed the results will be indeterminate.
133.It
134Zero or more of the following flags:
135.Bl -tag -width ".So \ Sc (space)"
136.It Sq Cm #
137The value should be converted to an
138.Dq alternate form .
139For
140.Cm c , d , i , n , p , s ,
141and
142.Cm u
143conversions, this option has no effect.
144For
145.Cm o
146conversions, the precision of the number is increased to force the first
147character of the output string to a zero (except if a zero value is printed
148with an explicit precision of zero).
149For
150.Cm x
151and
152.Cm X
153conversions, a non-zero result has the string
154.Ql 0x
155(or
156.Ql 0X
157for
158.Cm X
159conversions) prepended to it.
160For
161.Cm a , A , e , E , f , F , g ,
162and
163.Cm G
164conversions, the result will always contain a decimal point, even if no
165digits follow it (normally, a decimal point appears in the results of
166those conversions only if a digit follows).
167For
168.Cm g
169and
170.Cm G
171conversions, trailing zeros are not removed from the result as they
172would otherwise be.
173.It So Cm 0 Sc (zero)
174Zero padding.
175For all conversions except
176.Cm n ,
177the converted value is padded on the left with zeros rather than blanks.
178If a precision is given with a numeric conversion
179.Cm ( d , i , o , u , i , x ,
180and
181.Cm X ) ,
182the
183.Cm 0
184flag is ignored.
185.It Sq Cm \-
186A negative field width flag;
187the converted value is to be left adjusted on the field boundary.
188Except for
189.Cm n
190conversions, the converted value is padded on the right with blanks,
191rather than on the left with blanks or zeros.
192A
193.Cm \-
194overrides a
195.Cm 0
196if both are given.
197.It So "\ " Sc (space)
198A blank should be left before a positive number
199produced by a signed conversion
200.Cm ( a , A , d , e , E , f , F , g , G ,
201or
202.Cm i ) .
203.It Sq Cm +
204A sign must always be placed before a
205number produced by a signed conversion.
206A
207.Cm +
208overrides a space if both are used.
209.It Sq Cm '
210Decimal conversions
211.Cm ( d , u ,
212or
213.Cm i )
214or the integral portion of a floating point conversion
215.Cm ( f
216or
217.Cm F )
218should be grouped and separated by thousands using
219the non-monetary separator returned by
220.Xr localeconv 3 .
221.El
222.It
223An optional decimal digit string specifying a minimum field width.
224If the converted value has fewer characters than the field width, it will
225be padded with spaces on the left (or right, if the left-adjustment
226flag has been given) to fill out
227the field width.
228.It
229An optional precision, in the form of a period
230.Cm \&.
231followed by an
232optional digit string.
233If the digit string is omitted, the precision is taken as zero.
234This gives the minimum number of digits to appear for
235.Cm d , i , o , u , x ,
236and
237.Cm X
238conversions, the number of digits to appear after the decimal-point for
239.Cm a , A , e , E , f ,
240and
241.Cm F
242conversions, the maximum number of significant digits for
243.Cm g
244and
245.Cm G
246conversions, or the maximum number of characters to be printed from a
247string for
248.Cm s
249conversions.
250.It
251An optional length modifier, that specifies the size of the argument.
252The following length modifiers are valid for the
253.Cm d , i , n , o , u , x ,
254or
255.Cm X
256conversion:
257.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
258.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
259.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
260.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
261.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
262.It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
263.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
264.It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
265.It Cm z Ta (see note) Ta Vt size_t Ta (see note)
266.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
267.El
268.Pp
269Note:
270the
271.Cm t
272modifier, when applied to a
273.Cm o , u , x ,
274or
275.Cm X
276conversion, indicates that the argument is of an unsigned type
277equivalent in size to a
278.Vt ptrdiff_t .
279The
280.Cm z
281modifier, when applied to a
282.Cm d
283or
284.Cm i
285conversion, indicates that the argument is of a signed type equivalent in
286size to a
287.Vt size_t .
288Similarly, when applied to an
289.Cm n
290conversion, it indicates that the argument is a pointer to a signed type
291equivalent in size to a
292.Vt size_t .
293.Pp
294The following length modifier is valid for the
295.Cm a , A , e , E , f , F , g ,
296or
297.Cm G
298conversion:
299.Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
300.It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
301.It Cm L Ta Vt "long double"
302.El
303.Pp
304The following length modifier is valid for the
305.Cm c
306or
307.Cm s
308conversion:
309.Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
310.It Sy Modifier Ta Cm c Ta Cm s
311.It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
312.El
313.It
314A character that specifies the type of conversion to be applied.
315.El
316.Pp
317A field width or precision, or both, may be indicated by
318an asterisk
319.Ql *
320or an asterisk followed by one or more decimal digits and a
321.Ql $
322instead of a
323digit string.
324In this case, an
325.Vt int
326argument supplies the field width or precision.
327A negative field width is treated as a left adjustment flag followed by a
328positive field width; a negative precision is treated as though it were
329missing.
330If a single format directive mixes positional
331.Pq Li nn$
332and non-positional arguments, the results are undefined.
333.Pp
334The conversion specifiers and their meanings are:
335.Bl -tag -width ".Cm diouxX"
336.It Cm diouxX
337The
338.Vt int
339(or appropriate variant) argument is converted to signed decimal
340.Cm ( d
341and
342.Cm i ) ,
343unsigned octal
344.Pq Cm o ,
345unsigned decimal
346.Pq Cm u ,
347or unsigned hexadecimal
348.Cm ( x
349and
350.Cm X )
351notation.
352The letters
353.Dq Li abcdef
354are used for
355.Cm x
356conversions; the letters
357.Dq Li ABCDEF
358are used for
359.Cm X
360conversions.
361The precision, if any, gives the minimum number of digits that must
362appear; if the converted value requires fewer digits, it is padded on
363the left with zeros.
364.It Cm DOU
365The
366.Vt "long int"
367argument is converted to signed decimal, unsigned octal, or unsigned
368decimal, as if the format had been
369.Cm ld , lo ,
370or
371.Cm lu
372respectively.
373These conversion characters are deprecated, and will eventually disappear.
374.It Cm eE
375The
376.Vt double
377argument is rounded and converted in the style
378.Sm off
379.Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd
380.Sm on
381where there is one digit before the
382decimal-point character
383and the number of digits after it is equal to the precision;
384if the precision is missing,
385it is taken as 6; if the precision is
386zero, no decimal-point character appears.
387An
388.Cm E
389conversion uses the letter
390.Ql E
391(rather than
392.Ql e )
393to introduce the exponent.
394The exponent always contains at least two digits; if the value is zero,
395the exponent is 00.
396.Pp
397For
398.Cm a , A , e , E , f , F , g ,
399and
400.Cm G
401conversions, positive and negative infinity are represented as
402.Li inf
403and
404.Li -inf
405respectively when using the lowercase conversion character, and
406.Li INF
407and
408.Li -INF
409respectively when using the uppercase conversion character.
410Similarly, NaN is represented as
411.Li nan
412when using the lowercase conversion, and
413.Li NAN
414when using the uppercase conversion.
415.It Cm fF
416The
417.Vt double
418argument is rounded and converted to decimal notation in the style
419.Sm off
420.Oo \- Oc Ar ddd Li \&. Ar ddd ,
421.Sm on
422where the number of digits after the decimal-point character
423is equal to the precision specification.
424If the precision is missing, it is taken as 6; if the precision is
425explicitly zero, no decimal-point character appears.
426If a decimal point appears, at least one digit appears before it.
427.It Cm gG
428The
429.Vt double
430argument is converted in style
431.Cm f
432or
433.Cm e
434(or
435.Cm F
436or
437.Cm E
438for
439.Cm G
440conversions).
441The precision specifies the number of significant digits.
442If the precision is missing, 6 digits are given; if the precision is zero,
443it is treated as 1.
444Style
445.Cm e
446is used if the exponent from its conversion is less than \-4 or greater than
447or equal to the precision.
448Trailing zeros are removed from the fractional part of the result; a
449decimal point appears only if it is followed by at least one digit.
450.It Cm aA
451The
452.Vt double
453argument is converted to hexadecimal notation in the style
454.Sm off
455.Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d ,
456.Sm on
457where the number of digits after the hexadecimal-point character
458is equal to the precision specification.
459If the precision is missing, it is taken as enough to exactly
460represent the floating-point number; if the precision is
461explicitly zero, no hexadecimal-point character appears.
462This is an exact conversion of the mantissa+exponent internal
463floating point representation; the
464.Sm off
465.Oo \- Oc Li 0x Ar h Li \&. Ar hhh
466.Sm on
467portion represents exactly the mantissa; only denormalized
468mantissas have a zero value to the left of the hexadecimal
469point.
470The
471.Cm p
472is a literal character
473.Ql p ;
474the exponent is preceded by a positive or negative sign
475and is represented in decimal, using only enough characters
476to represent the exponent.
477The
478.Cm A
479conversion uses the prefix
480.Dq Li 0X
481(rather than
482.Dq Li 0x ) ,
483the letters
484.Dq Li ABCDEF
485(rather than
486.Dq Li abcdef )
487to represent the hex digits, and the letter
488.Ql P
489(rather than
490.Ql p )
491to separate the mantissa and exponent.
492.It Cm C
493Treated as
494.Cm c
495with the
496.Cm l
497(ell) modifier.
498.It Cm c
499The
500.Vt int
501argument is converted to an
502.Vt "unsigned char" ,
503then to a
504.Vt wchar_t
505as if by
506.Xr btowc 3 ,
507and the resulting character is written.
508.Pp
509If the
510.Cm l
511(ell) modifier is used, the
512.Vt wint_t
513argument is converted to a
514.Vt wchar_t
515and written.
516.It Cm S
517Treated as
518.Cm s
519with the
520.Cm l
521(ell) modifier.
522.It Cm s
523The
524.Vt "char *"
525argument is expected to be a pointer to an array of character type (pointer
526to a string) containing a multibyte sequence.
527Characters from the array are converted to wide characters and written up to
528(but not including)
529a terminating
530.Dv NUL
531character;
532if a precision is specified, no more than the number specified are
533written.
534If a precision is given, no null character
535need be present; if the precision is not specified, or is greater than
536the size of the array, the array must contain a terminating
537.Dv NUL
538character.
539.Pp
540If the
541.Cm l
542(ell) modifier is used, the
543.Vt "wchar_t *"
544argument is expected to be a pointer to an array of wide characters
545(pointer to a wide string).
546Each wide character in the string
547is written.
548Wide characters from the array are written up to (but not including)
549a terminating wide
550.Dv NUL
551character;
552if a precision is specified, no more than the number specified are
553written (including shift sequences).
554If a precision is given, no null character
555need be present; if the precision is not specified, or is greater than
556the number of characters in
557the string, the array must contain a terminating wide
558.Dv NUL
559character.
560.It Cm p
561The
562.Vt "void *"
563pointer argument is printed in hexadecimal (as if by
564.Ql %#x
565or
566.Ql %#lx ) .
567.It Cm n
568The number of characters written so far is stored into the
569integer indicated by the
570.Vt "int *"
571(or variant) pointer argument.
572No argument is converted.
573.It Cm %
574A
575.Ql %
576is written.
577No argument is converted.
578The complete conversion specification
579is
580.Ql %% .
581.El
582.Pp
583The decimal point
584character is defined in the program's locale (category
585.Dv LC_NUMERIC ) .
586.Pp
587In no case does a non-existent or small field width cause truncation of
588a numeric field; if the result of a conversion is wider than the field
589width, the
590field is expanded to contain the conversion result.
591.Sh SECURITY CONSIDERATIONS
592Refer to
593.Xr printf 3 .
594.Sh SEE ALSO
595.Xr btowc 3 ,
596.Xr fputws 3 ,
597.Xr printf 3 ,
598.Xr putwc 3 ,
599.Xr setlocale 3 ,
600.Xr wcsrtombs 3 ,
601.Xr wscanf 3
602.Sh STANDARDS
603Subject to the caveats noted in the
604.Sx BUGS
605section
606of
607.Xr printf 3 ,
608the
609.Fn wprintf ,
610.Fn fwprintf ,
611.Fn swprintf ,
612.Fn vwprintf ,
613.Fn vfwprintf
614and
615.Fn vswprintf
616functions
617conform to
618.St -isoC-99 .
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: src/lib/libc/stdio/printf.3,v 1.47 2002/09/06 11:23:55 tjr Exp
34.\" $FreeBSD: head/lib/libc/stdio/wprintf.3 207940 2010-05-11 23:08:15Z uqs $
35.\"
36.Dd July 5, 2003
37.Dt WPRINTF 3
38.Os
39.Sh NAME
40.Nm wprintf , fwprintf , swprintf ,
41.Nm vwprintf , vfwprintf , vswprintf
42.Nd formatted wide character output conversion
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In stdio.h
47.In wchar.h
48.Ft int
49.Fn fwprintf "FILE * restrict stream" "const wchar_t * restrict format" ...
50.Ft int
51.Fn swprintf "wchar_t * restrict ws" "size_t n" "const wchar_t * restrict format" ...
52.Ft int
53.Fn wprintf "const wchar_t * restrict format" ...
54.In stdarg.h
55.Ft int
56.Fn vfwprintf "FILE * restrict stream" "const wchar_t * restrict" "va_list ap"
57.Ft int
58.Fn vswprintf "wchar_t * restrict ws" "size_t n" "const wchar_t *restrict format" "va_list ap"
59.Ft int
60.Fn vwprintf "const wchar_t * restrict format" "va_list ap"
61.Sh DESCRIPTION
62The
63.Fn wprintf
64family of functions produces output according to a
65.Fa format
66as described below.
67The
68.Fn wprintf
69and
70.Fn vwprintf
71functions
72write output to
73.Dv stdout ,
74the standard output stream;
75.Fn fwprintf
76and
77.Fn vfwprintf
78write output to the given output
79.Fa stream ;
80.Fn swprintf
81and
82.Fn vswprintf
83write to the wide character string
84.Fa ws .
85.Pp
86These functions write the output under the control of a
87.Fa format
88string that specifies how subsequent arguments
89(or arguments accessed via the variable-length argument facilities of
90.Xr stdarg 3 )
91are converted for output.
92.Pp
93These functions return the number of characters printed
94(not including the trailing
95.Ql \e0
96used to end output to strings).
97.Pp
98The
99.Fn swprintf
100and
101.Fn vswprintf
102functions will fail if
103.Fa n
104or more wide characters were requested to be written,
105.Pp
106The format string is composed of zero or more directives:
107ordinary
108characters (not
109.Cm % ) ,
110which are copied unchanged to the output stream;
111and conversion specifications, each of which results
112in fetching zero or more subsequent arguments.
113Each conversion specification is introduced by
114the
115.Cm %
116character.
117The arguments must correspond properly (after type promotion)
118with the conversion specifier.
119After the
120.Cm % ,
121the following appear in sequence:
122.Bl -bullet
123.It
124An optional field, consisting of a decimal digit string followed by a
125.Cm $ ,
126specifying the next argument to access.
127If this field is not provided, the argument following the last
128argument accessed will be used.
129Arguments are numbered starting at
130.Cm 1 .
131If unaccessed arguments in the format string are interspersed with ones that
132are accessed the results will be indeterminate.
133.It
134Zero or more of the following flags:
135.Bl -tag -width ".So \ Sc (space)"
136.It Sq Cm #
137The value should be converted to an
138.Dq alternate form .
139For
140.Cm c , d , i , n , p , s ,
141and
142.Cm u
143conversions, this option has no effect.
144For
145.Cm o
146conversions, the precision of the number is increased to force the first
147character of the output string to a zero (except if a zero value is printed
148with an explicit precision of zero).
149For
150.Cm x
151and
152.Cm X
153conversions, a non-zero result has the string
154.Ql 0x
155(or
156.Ql 0X
157for
158.Cm X
159conversions) prepended to it.
160For
161.Cm a , A , e , E , f , F , g ,
162and
163.Cm G
164conversions, the result will always contain a decimal point, even if no
165digits follow it (normally, a decimal point appears in the results of
166those conversions only if a digit follows).
167For
168.Cm g
169and
170.Cm G
171conversions, trailing zeros are not removed from the result as they
172would otherwise be.
173.It So Cm 0 Sc (zero)
174Zero padding.
175For all conversions except
176.Cm n ,
177the converted value is padded on the left with zeros rather than blanks.
178If a precision is given with a numeric conversion
179.Cm ( d , i , o , u , i , x ,
180and
181.Cm X ) ,
182the
183.Cm 0
184flag is ignored.
185.It Sq Cm \-
186A negative field width flag;
187the converted value is to be left adjusted on the field boundary.
188Except for
189.Cm n
190conversions, the converted value is padded on the right with blanks,
191rather than on the left with blanks or zeros.
192A
193.Cm \-
194overrides a
195.Cm 0
196if both are given.
197.It So "\ " Sc (space)
198A blank should be left before a positive number
199produced by a signed conversion
200.Cm ( a , A , d , e , E , f , F , g , G ,
201or
202.Cm i ) .
203.It Sq Cm +
204A sign must always be placed before a
205number produced by a signed conversion.
206A
207.Cm +
208overrides a space if both are used.
209.It Sq Cm '
210Decimal conversions
211.Cm ( d , u ,
212or
213.Cm i )
214or the integral portion of a floating point conversion
215.Cm ( f
216or
217.Cm F )
218should be grouped and separated by thousands using
219the non-monetary separator returned by
220.Xr localeconv 3 .
221.El
222.It
223An optional decimal digit string specifying a minimum field width.
224If the converted value has fewer characters than the field width, it will
225be padded with spaces on the left (or right, if the left-adjustment
226flag has been given) to fill out
227the field width.
228.It
229An optional precision, in the form of a period
230.Cm \&.
231followed by an
232optional digit string.
233If the digit string is omitted, the precision is taken as zero.
234This gives the minimum number of digits to appear for
235.Cm d , i , o , u , x ,
236and
237.Cm X
238conversions, the number of digits to appear after the decimal-point for
239.Cm a , A , e , E , f ,
240and
241.Cm F
242conversions, the maximum number of significant digits for
243.Cm g
244and
245.Cm G
246conversions, or the maximum number of characters to be printed from a
247string for
248.Cm s
249conversions.
250.It
251An optional length modifier, that specifies the size of the argument.
252The following length modifiers are valid for the
253.Cm d , i , n , o , u , x ,
254or
255.Cm X
256conversion:
257.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
258.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
259.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
260.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
261.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
262.It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
263.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
264.It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
265.It Cm z Ta (see note) Ta Vt size_t Ta (see note)
266.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
267.El
268.Pp
269Note:
270the
271.Cm t
272modifier, when applied to a
273.Cm o , u , x ,
274or
275.Cm X
276conversion, indicates that the argument is of an unsigned type
277equivalent in size to a
278.Vt ptrdiff_t .
279The
280.Cm z
281modifier, when applied to a
282.Cm d
283or
284.Cm i
285conversion, indicates that the argument is of a signed type equivalent in
286size to a
287.Vt size_t .
288Similarly, when applied to an
289.Cm n
290conversion, it indicates that the argument is a pointer to a signed type
291equivalent in size to a
292.Vt size_t .
293.Pp
294The following length modifier is valid for the
295.Cm a , A , e , E , f , F , g ,
296or
297.Cm G
298conversion:
299.Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
300.It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
301.It Cm L Ta Vt "long double"
302.El
303.Pp
304The following length modifier is valid for the
305.Cm c
306or
307.Cm s
308conversion:
309.Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
310.It Sy Modifier Ta Cm c Ta Cm s
311.It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
312.El
313.It
314A character that specifies the type of conversion to be applied.
315.El
316.Pp
317A field width or precision, or both, may be indicated by
318an asterisk
319.Ql *
320or an asterisk followed by one or more decimal digits and a
321.Ql $
322instead of a
323digit string.
324In this case, an
325.Vt int
326argument supplies the field width or precision.
327A negative field width is treated as a left adjustment flag followed by a
328positive field width; a negative precision is treated as though it were
329missing.
330If a single format directive mixes positional
331.Pq Li nn$
332and non-positional arguments, the results are undefined.
333.Pp
334The conversion specifiers and their meanings are:
335.Bl -tag -width ".Cm diouxX"
336.It Cm diouxX
337The
338.Vt int
339(or appropriate variant) argument is converted to signed decimal
340.Cm ( d
341and
342.Cm i ) ,
343unsigned octal
344.Pq Cm o ,
345unsigned decimal
346.Pq Cm u ,
347or unsigned hexadecimal
348.Cm ( x
349and
350.Cm X )
351notation.
352The letters
353.Dq Li abcdef
354are used for
355.Cm x
356conversions; the letters
357.Dq Li ABCDEF
358are used for
359.Cm X
360conversions.
361The precision, if any, gives the minimum number of digits that must
362appear; if the converted value requires fewer digits, it is padded on
363the left with zeros.
364.It Cm DOU
365The
366.Vt "long int"
367argument is converted to signed decimal, unsigned octal, or unsigned
368decimal, as if the format had been
369.Cm ld , lo ,
370or
371.Cm lu
372respectively.
373These conversion characters are deprecated, and will eventually disappear.
374.It Cm eE
375The
376.Vt double
377argument is rounded and converted in the style
378.Sm off
379.Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd
380.Sm on
381where there is one digit before the
382decimal-point character
383and the number of digits after it is equal to the precision;
384if the precision is missing,
385it is taken as 6; if the precision is
386zero, no decimal-point character appears.
387An
388.Cm E
389conversion uses the letter
390.Ql E
391(rather than
392.Ql e )
393to introduce the exponent.
394The exponent always contains at least two digits; if the value is zero,
395the exponent is 00.
396.Pp
397For
398.Cm a , A , e , E , f , F , g ,
399and
400.Cm G
401conversions, positive and negative infinity are represented as
402.Li inf
403and
404.Li -inf
405respectively when using the lowercase conversion character, and
406.Li INF
407and
408.Li -INF
409respectively when using the uppercase conversion character.
410Similarly, NaN is represented as
411.Li nan
412when using the lowercase conversion, and
413.Li NAN
414when using the uppercase conversion.
415.It Cm fF
416The
417.Vt double
418argument is rounded and converted to decimal notation in the style
419.Sm off
420.Oo \- Oc Ar ddd Li \&. Ar ddd ,
421.Sm on
422where the number of digits after the decimal-point character
423is equal to the precision specification.
424If the precision is missing, it is taken as 6; if the precision is
425explicitly zero, no decimal-point character appears.
426If a decimal point appears, at least one digit appears before it.
427.It Cm gG
428The
429.Vt double
430argument is converted in style
431.Cm f
432or
433.Cm e
434(or
435.Cm F
436or
437.Cm E
438for
439.Cm G
440conversions).
441The precision specifies the number of significant digits.
442If the precision is missing, 6 digits are given; if the precision is zero,
443it is treated as 1.
444Style
445.Cm e
446is used if the exponent from its conversion is less than \-4 or greater than
447or equal to the precision.
448Trailing zeros are removed from the fractional part of the result; a
449decimal point appears only if it is followed by at least one digit.
450.It Cm aA
451The
452.Vt double
453argument is converted to hexadecimal notation in the style
454.Sm off
455.Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d ,
456.Sm on
457where the number of digits after the hexadecimal-point character
458is equal to the precision specification.
459If the precision is missing, it is taken as enough to exactly
460represent the floating-point number; if the precision is
461explicitly zero, no hexadecimal-point character appears.
462This is an exact conversion of the mantissa+exponent internal
463floating point representation; the
464.Sm off
465.Oo \- Oc Li 0x Ar h Li \&. Ar hhh
466.Sm on
467portion represents exactly the mantissa; only denormalized
468mantissas have a zero value to the left of the hexadecimal
469point.
470The
471.Cm p
472is a literal character
473.Ql p ;
474the exponent is preceded by a positive or negative sign
475and is represented in decimal, using only enough characters
476to represent the exponent.
477The
478.Cm A
479conversion uses the prefix
480.Dq Li 0X
481(rather than
482.Dq Li 0x ) ,
483the letters
484.Dq Li ABCDEF
485(rather than
486.Dq Li abcdef )
487to represent the hex digits, and the letter
488.Ql P
489(rather than
490.Ql p )
491to separate the mantissa and exponent.
492.It Cm C
493Treated as
494.Cm c
495with the
496.Cm l
497(ell) modifier.
498.It Cm c
499The
500.Vt int
501argument is converted to an
502.Vt "unsigned char" ,
503then to a
504.Vt wchar_t
505as if by
506.Xr btowc 3 ,
507and the resulting character is written.
508.Pp
509If the
510.Cm l
511(ell) modifier is used, the
512.Vt wint_t
513argument is converted to a
514.Vt wchar_t
515and written.
516.It Cm S
517Treated as
518.Cm s
519with the
520.Cm l
521(ell) modifier.
522.It Cm s
523The
524.Vt "char *"
525argument is expected to be a pointer to an array of character type (pointer
526to a string) containing a multibyte sequence.
527Characters from the array are converted to wide characters and written up to
528(but not including)
529a terminating
530.Dv NUL
531character;
532if a precision is specified, no more than the number specified are
533written.
534If a precision is given, no null character
535need be present; if the precision is not specified, or is greater than
536the size of the array, the array must contain a terminating
537.Dv NUL
538character.
539.Pp
540If the
541.Cm l
542(ell) modifier is used, the
543.Vt "wchar_t *"
544argument is expected to be a pointer to an array of wide characters
545(pointer to a wide string).
546Each wide character in the string
547is written.
548Wide characters from the array are written up to (but not including)
549a terminating wide
550.Dv NUL
551character;
552if a precision is specified, no more than the number specified are
553written (including shift sequences).
554If a precision is given, no null character
555need be present; if the precision is not specified, or is greater than
556the number of characters in
557the string, the array must contain a terminating wide
558.Dv NUL
559character.
560.It Cm p
561The
562.Vt "void *"
563pointer argument is printed in hexadecimal (as if by
564.Ql %#x
565or
566.Ql %#lx ) .
567.It Cm n
568The number of characters written so far is stored into the
569integer indicated by the
570.Vt "int *"
571(or variant) pointer argument.
572No argument is converted.
573.It Cm %
574A
575.Ql %
576is written.
577No argument is converted.
578The complete conversion specification
579is
580.Ql %% .
581.El
582.Pp
583The decimal point
584character is defined in the program's locale (category
585.Dv LC_NUMERIC ) .
586.Pp
587In no case does a non-existent or small field width cause truncation of
588a numeric field; if the result of a conversion is wider than the field
589width, the
590field is expanded to contain the conversion result.
591.Sh SECURITY CONSIDERATIONS
592Refer to
593.Xr printf 3 .
594.Sh SEE ALSO
595.Xr btowc 3 ,
596.Xr fputws 3 ,
597.Xr printf 3 ,
598.Xr putwc 3 ,
599.Xr setlocale 3 ,
600.Xr wcsrtombs 3 ,
601.Xr wscanf 3
602.Sh STANDARDS
603Subject to the caveats noted in the
604.Sx BUGS
605section
606of
607.Xr printf 3 ,
608the
609.Fn wprintf ,
610.Fn fwprintf ,
611.Fn swprintf ,
612.Fn vwprintf ,
613.Fn vfwprintf
614and
615.Fn vswprintf
616functions
617conform to
618.St -isoC-99 .