xref: /minix3/lib/libc/stdio/wprintf.3 (revision 2fe8fb192fe7e8720e3e7a77f928da545e872a6a)
1*2fe8fb19SBen Gras.\" $NetBSD: wprintf.3,v 1.8 2010/12/16 17:42:27 wiz Exp $
2*2fe8fb19SBen Gras.\" Copyright (c) 1990, 1991, 1993
3*2fe8fb19SBen Gras.\"	The Regents of the University of California.  All rights reserved.
4*2fe8fb19SBen Gras.\"
5*2fe8fb19SBen Gras.\" This code is derived from software contributed to Berkeley by
6*2fe8fb19SBen Gras.\" Chris Torek and the American National Standards Committee X3,
7*2fe8fb19SBen Gras.\" on Information Processing Systems.
8*2fe8fb19SBen Gras.\"
9*2fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without
10*2fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions
11*2fe8fb19SBen Gras.\" are met:
12*2fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright
13*2fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer.
14*2fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright
15*2fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer in the
16*2fe8fb19SBen Gras.\"    documentation and/or other materials provided with the distribution.
17*2fe8fb19SBen Gras.\" 3. All advertising materials mentioning features or use of this software
18*2fe8fb19SBen Gras.\"    must display the following acknowledgement:
19*2fe8fb19SBen Gras.\"	This product includes software developed by the University of
20*2fe8fb19SBen Gras.\"	California, Berkeley and its contributors.
21*2fe8fb19SBen Gras.\" 4. Neither the name of the University nor the names of its contributors
22*2fe8fb19SBen Gras.\"    may be used to endorse or promote products derived from this software
23*2fe8fb19SBen Gras.\"    without specific prior written permission.
24*2fe8fb19SBen Gras.\"
25*2fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
26*2fe8fb19SBen Gras.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27*2fe8fb19SBen Gras.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28*2fe8fb19SBen Gras.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29*2fe8fb19SBen Gras.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30*2fe8fb19SBen Gras.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31*2fe8fb19SBen Gras.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32*2fe8fb19SBen Gras.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33*2fe8fb19SBen Gras.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34*2fe8fb19SBen Gras.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35*2fe8fb19SBen Gras.\" SUCH DAMAGE.
36*2fe8fb19SBen Gras.\"
37*2fe8fb19SBen Gras.\"     @(#)printf.3	8.1 (Berkeley) 6/4/93
38*2fe8fb19SBen Gras.\" FreeBSD: src/lib/libc/stdio/printf.3,v 1.47 2002/09/06 11:23:55 tjr Exp
39*2fe8fb19SBen Gras.\" $FreeBSD: src/lib/libc/stdio/wprintf.3,v 1.5 2003/07/05 07:55:34 tjr Exp $
40*2fe8fb19SBen Gras.\"
41*2fe8fb19SBen Gras.Dd April 30, 2010
42*2fe8fb19SBen Gras.Dt WPRINTF 3
43*2fe8fb19SBen Gras.Os
44*2fe8fb19SBen Gras.Sh NAME
45*2fe8fb19SBen Gras.Nm wprintf , fwprintf , swprintf ,
46*2fe8fb19SBen Gras.Nm vwprintf , vfwprintf , vswprintf
47*2fe8fb19SBen Gras.Nd formatted wide character output conversion
48*2fe8fb19SBen Gras.Sh LIBRARY
49*2fe8fb19SBen Gras.Lb libc
50*2fe8fb19SBen Gras.Sh SYNOPSIS
51*2fe8fb19SBen Gras.In stdio.h
52*2fe8fb19SBen Gras.In wchar.h
53*2fe8fb19SBen Gras.Ft int
54*2fe8fb19SBen Gras.Fn fwprintf "FILE * restrict stream" "const wchar_t * restrict format" ...
55*2fe8fb19SBen Gras.Ft int
56*2fe8fb19SBen Gras.Fn swprintf "wchar_t * restrict ws" "size_t n" "const wchar_t * restrict format" ...
57*2fe8fb19SBen Gras.Ft int
58*2fe8fb19SBen Gras.Fn wprintf "const wchar_t * restrict format" ...
59*2fe8fb19SBen Gras.In stdarg.h
60*2fe8fb19SBen Gras.Ft int
61*2fe8fb19SBen Gras.Fn vfwprintf "FILE * restrict stream" "const wchar_t * restrict" "va_list ap"
62*2fe8fb19SBen Gras.Ft int
63*2fe8fb19SBen Gras.Fn vswprintf "wchar_t * restrict ws" "size_t n" "const wchar_t *restrict format" "va_list ap"
64*2fe8fb19SBen Gras.Ft int
65*2fe8fb19SBen Gras.Fn vwprintf "const wchar_t * restrict format" "va_list ap"
66*2fe8fb19SBen Gras.Sh DESCRIPTION
67*2fe8fb19SBen GrasThe
68*2fe8fb19SBen Gras.Fn wprintf
69*2fe8fb19SBen Grasfamily of functions produces output according to a
70*2fe8fb19SBen Gras.Fa format
71*2fe8fb19SBen Grasas described below.
72*2fe8fb19SBen GrasThe
73*2fe8fb19SBen Gras.Fn wprintf
74*2fe8fb19SBen Grasand
75*2fe8fb19SBen Gras.Fn vwprintf
76*2fe8fb19SBen Grasfunctions
77*2fe8fb19SBen Graswrite output to
78*2fe8fb19SBen Gras.Dv stdout ,
79*2fe8fb19SBen Grasthe standard output stream;
80*2fe8fb19SBen Gras.Fn fwprintf
81*2fe8fb19SBen Grasand
82*2fe8fb19SBen Gras.Fn vfwprintf
83*2fe8fb19SBen Graswrite output to the given output
84*2fe8fb19SBen Gras.Fa stream ;
85*2fe8fb19SBen Gras.Fn swprintf
86*2fe8fb19SBen Grasand
87*2fe8fb19SBen Gras.Fn vswprintf
88*2fe8fb19SBen Graswrite to the wide-character string
89*2fe8fb19SBen Gras.Fa ws .
90*2fe8fb19SBen Gras.Pp
91*2fe8fb19SBen GrasThese functions write the output under the control of a
92*2fe8fb19SBen Gras.Fa format
93*2fe8fb19SBen Grasstring that specifies how subsequent arguments
94*2fe8fb19SBen Gras(or arguments accessed via the variable-length argument facilities of
95*2fe8fb19SBen Gras.Xr stdarg 3 )
96*2fe8fb19SBen Grasare converted for output.
97*2fe8fb19SBen Gras.Pp
98*2fe8fb19SBen GrasThe
99*2fe8fb19SBen Gras.Fn swprintf
100*2fe8fb19SBen Grasand
101*2fe8fb19SBen Gras.Fn vswprintf
102*2fe8fb19SBen Grasfunctions will fail if
103*2fe8fb19SBen Gras.Fa n
104*2fe8fb19SBen Grasor more wide characters were requested to be written,
105*2fe8fb19SBen Gras.Pp
106*2fe8fb19SBen GrasThe format string is composed of zero or more directives:
107*2fe8fb19SBen Grasordinary
108*2fe8fb19SBen Grascharacters (not
109*2fe8fb19SBen Gras.Cm % ) ,
110*2fe8fb19SBen Graswhich are copied unchanged to the output stream;
111*2fe8fb19SBen Grasand conversion specifications, each of which results
112*2fe8fb19SBen Grasin fetching zero or more subsequent arguments.
113*2fe8fb19SBen GrasEach conversion specification is introduced by
114*2fe8fb19SBen Grasthe
115*2fe8fb19SBen Gras.Cm %
116*2fe8fb19SBen Grascharacter.
117*2fe8fb19SBen GrasThe arguments must correspond properly (after type promotion)
118*2fe8fb19SBen Graswith the conversion specifier.
119*2fe8fb19SBen GrasAfter the
120*2fe8fb19SBen Gras.Cm % ,
121*2fe8fb19SBen Grasthe following appear in sequence:
122*2fe8fb19SBen Gras.Bl -bullet
123*2fe8fb19SBen Gras.It
124*2fe8fb19SBen GrasAn optional field, consisting of a decimal digit string followed by a
125*2fe8fb19SBen Gras.Cm $ ,
126*2fe8fb19SBen Grasspecifying the next argument to access.
127*2fe8fb19SBen GrasIf this field is not provided, the argument following the last
128*2fe8fb19SBen Grasargument accessed will be used.
129*2fe8fb19SBen GrasArguments are numbered starting at
130*2fe8fb19SBen Gras.Cm 1 .
131*2fe8fb19SBen GrasIf unaccessed arguments in the format string are interspersed with ones that
132*2fe8fb19SBen Grasare accessed the results will be indeterminate.
133*2fe8fb19SBen Gras.It
134*2fe8fb19SBen GrasZero or more of the following flags:
135*2fe8fb19SBen Gras.Bl -tag -width ".So \  Sc (space)"
136*2fe8fb19SBen Gras.It Sq Cm #
137*2fe8fb19SBen GrasThe value should be converted to an
138*2fe8fb19SBen Gras.Dq alternate form .
139*2fe8fb19SBen GrasFor
140*2fe8fb19SBen Gras.Cm c , d , i , n , p , s ,
141*2fe8fb19SBen Grasand
142*2fe8fb19SBen Gras.Cm u
143*2fe8fb19SBen Grasconversions, this option has no effect.
144*2fe8fb19SBen GrasFor
145*2fe8fb19SBen Gras.Cm o
146*2fe8fb19SBen Grasconversions, the precision of the number is increased to force the first
147*2fe8fb19SBen Grascharacter of the output string to a zero (except if a zero value is printed
148*2fe8fb19SBen Graswith an explicit precision of zero).
149*2fe8fb19SBen GrasFor
150*2fe8fb19SBen Gras.Cm x
151*2fe8fb19SBen Grasand
152*2fe8fb19SBen Gras.Cm X
153*2fe8fb19SBen Grasconversions, a non-zero result has the string
154*2fe8fb19SBen Gras.Ql 0x
155*2fe8fb19SBen Gras(or
156*2fe8fb19SBen Gras.Ql 0X
157*2fe8fb19SBen Grasfor
158*2fe8fb19SBen Gras.Cm X
159*2fe8fb19SBen Grasconversions) prepended to it.
160*2fe8fb19SBen GrasFor
161*2fe8fb19SBen Gras.Cm a , A , e , E , f , F , g ,
162*2fe8fb19SBen Grasand
163*2fe8fb19SBen Gras.Cm G
164*2fe8fb19SBen Grasconversions, the result will always contain a decimal point, even if no
165*2fe8fb19SBen Grasdigits follow it (normally, a decimal point appears in the results of
166*2fe8fb19SBen Grasthose conversions only if a digit follows).
167*2fe8fb19SBen GrasFor
168*2fe8fb19SBen Gras.Cm g
169*2fe8fb19SBen Grasand
170*2fe8fb19SBen Gras.Cm G
171*2fe8fb19SBen Grasconversions, trailing zeros are not removed from the result as they
172*2fe8fb19SBen Graswould otherwise be.
173*2fe8fb19SBen Gras.It So Cm 0 Sc (zero)
174*2fe8fb19SBen GrasZero padding.
175*2fe8fb19SBen GrasFor all conversions except
176*2fe8fb19SBen Gras.Cm n ,
177*2fe8fb19SBen Grasthe converted value is padded on the left with zeros rather than blanks.
178*2fe8fb19SBen GrasIf a precision is given with a numeric conversion
179*2fe8fb19SBen Gras.Cm ( d , i , o , u , i , x ,
180*2fe8fb19SBen Grasand
181*2fe8fb19SBen Gras.Cm X ) ,
182*2fe8fb19SBen Grasthe
183*2fe8fb19SBen Gras.Cm 0
184*2fe8fb19SBen Grasflag is ignored.
185*2fe8fb19SBen Gras.It Sq Cm \-
186*2fe8fb19SBen GrasA negative field width flag;
187*2fe8fb19SBen Grasthe converted value is to be left adjusted on the field boundary.
188*2fe8fb19SBen GrasExcept for
189*2fe8fb19SBen Gras.Cm n
190*2fe8fb19SBen Grasconversions, the converted value is padded on the right with blanks,
191*2fe8fb19SBen Grasrather than on the left with blanks or zeros.
192*2fe8fb19SBen GrasA
193*2fe8fb19SBen Gras.Cm \-
194*2fe8fb19SBen Grasoverrides a
195*2fe8fb19SBen Gras.Cm 0
196*2fe8fb19SBen Grasif both are given.
197*2fe8fb19SBen Gras.It So "\ " Sc (space)
198*2fe8fb19SBen GrasA blank should be left before a positive number
199*2fe8fb19SBen Grasproduced by a signed conversion
200*2fe8fb19SBen Gras.Cm ( a , A , d , e , E , f , F , g , G ,
201*2fe8fb19SBen Grasor
202*2fe8fb19SBen Gras.Cm i ) .
203*2fe8fb19SBen Gras.It Sq Cm +
204*2fe8fb19SBen GrasA sign must always be placed before a
205*2fe8fb19SBen Grasnumber produced by a signed conversion.
206*2fe8fb19SBen GrasA
207*2fe8fb19SBen Gras.Cm +
208*2fe8fb19SBen Grasoverrides a space if both are used.
209*2fe8fb19SBen Gras.It Sq Cm '
210*2fe8fb19SBen GrasDecimal conversions
211*2fe8fb19SBen Gras.Cm ( d , u ,
212*2fe8fb19SBen Grasor
213*2fe8fb19SBen Gras.Cm i )
214*2fe8fb19SBen Grasor the integral portion of a floating point conversion
215*2fe8fb19SBen Gras.Cm ( f
216*2fe8fb19SBen Grasor
217*2fe8fb19SBen Gras.Cm F )
218*2fe8fb19SBen Grasshould be grouped and separated by thousands using
219*2fe8fb19SBen Grasthe non-monetary separator returned by
220*2fe8fb19SBen Gras.Xr localeconv 3 .
221*2fe8fb19SBen Gras.El
222*2fe8fb19SBen Gras.It
223*2fe8fb19SBen GrasAn optional decimal digit string specifying a minimum field width.
224*2fe8fb19SBen GrasIf the converted value has fewer characters than the field width, it will
225*2fe8fb19SBen Grasbe padded with spaces on the left (or right, if the left-adjustment
226*2fe8fb19SBen Grasflag has been given) to fill out
227*2fe8fb19SBen Grasthe field width.
228*2fe8fb19SBen Gras.It
229*2fe8fb19SBen GrasAn optional precision, in the form of a period
230*2fe8fb19SBen Gras.Cm \&.
231*2fe8fb19SBen Grasfollowed by an
232*2fe8fb19SBen Grasoptional digit string.
233*2fe8fb19SBen GrasIf the digit string is omitted, the precision is taken as zero.
234*2fe8fb19SBen GrasThis gives the minimum number of digits to appear for
235*2fe8fb19SBen Gras.Cm d , i , o , u , x ,
236*2fe8fb19SBen Grasand
237*2fe8fb19SBen Gras.Cm X
238*2fe8fb19SBen Grasconversions, the number of digits to appear after the decimal-point for
239*2fe8fb19SBen Gras.Cm a , A , e , E , f ,
240*2fe8fb19SBen Grasand
241*2fe8fb19SBen Gras.Cm F
242*2fe8fb19SBen Grasconversions, the maximum number of significant digits for
243*2fe8fb19SBen Gras.Cm g
244*2fe8fb19SBen Grasand
245*2fe8fb19SBen Gras.Cm G
246*2fe8fb19SBen Grasconversions, or the maximum number of characters to be printed from a
247*2fe8fb19SBen Grasstring for
248*2fe8fb19SBen Gras.Cm s
249*2fe8fb19SBen Grasconversions.
250*2fe8fb19SBen Gras.It
251*2fe8fb19SBen GrasAn optional length modifier, that specifies the size of the argument.
252*2fe8fb19SBen GrasThe following length modifiers are valid for the
253*2fe8fb19SBen Gras.Cm d , i , n , o , u , x ,
254*2fe8fb19SBen Grasor
255*2fe8fb19SBen Gras.Cm X
256*2fe8fb19SBen Grasconversion:
257*2fe8fb19SBen Gras.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
258*2fe8fb19SBen Gras.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
259*2fe8fb19SBen Gras.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
260*2fe8fb19SBen Gras.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
261*2fe8fb19SBen Gras.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
262*2fe8fb19SBen Gras.It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
263*2fe8fb19SBen Gras.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
264*2fe8fb19SBen Gras.It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
265*2fe8fb19SBen Gras.It Cm z Ta (see note) Ta Vt size_t Ta (see note)
266*2fe8fb19SBen Gras.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
267*2fe8fb19SBen Gras.El
268*2fe8fb19SBen Gras.Pp
269*2fe8fb19SBen GrasNote:
270*2fe8fb19SBen Grasthe
271*2fe8fb19SBen Gras.Cm t
272*2fe8fb19SBen Grasmodifier, when applied to a
273*2fe8fb19SBen Gras.Cm o , u , x ,
274*2fe8fb19SBen Grasor
275*2fe8fb19SBen Gras.Cm X
276*2fe8fb19SBen Grasconversion, indicates that the argument is of an unsigned type
277*2fe8fb19SBen Grasequivalent in size to a
278*2fe8fb19SBen Gras.Vt ptrdiff_t .
279*2fe8fb19SBen GrasThe
280*2fe8fb19SBen Gras.Cm z
281*2fe8fb19SBen Grasmodifier, when applied to a
282*2fe8fb19SBen Gras.Cm d
283*2fe8fb19SBen Grasor
284*2fe8fb19SBen Gras.Cm i
285*2fe8fb19SBen Grasconversion, indicates that the argument is of a signed type equivalent in
286*2fe8fb19SBen Grassize to a
287*2fe8fb19SBen Gras.Vt size_t .
288*2fe8fb19SBen GrasSimilarly, when applied to an
289*2fe8fb19SBen Gras.Cm n
290*2fe8fb19SBen Grasconversion, it indicates that the argument is a pointer to a signed type
291*2fe8fb19SBen Grasequivalent in size to a
292*2fe8fb19SBen Gras.Vt size_t .
293*2fe8fb19SBen Gras.Pp
294*2fe8fb19SBen GrasThe following length modifier is valid for the
295*2fe8fb19SBen Gras.Cm a , A , e , E , f , F , g ,
296*2fe8fb19SBen Grasor
297*2fe8fb19SBen Gras.Cm G
298*2fe8fb19SBen Grasconversion:
299*2fe8fb19SBen Gras.Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
300*2fe8fb19SBen Gras.It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
301*2fe8fb19SBen Gras.It Cm L Ta Vt "long double"
302*2fe8fb19SBen Gras.El
303*2fe8fb19SBen Gras.Pp
304*2fe8fb19SBen GrasThe following length modifier is valid for the
305*2fe8fb19SBen Gras.Cm c
306*2fe8fb19SBen Grasor
307*2fe8fb19SBen Gras.Cm s
308*2fe8fb19SBen Grasconversion:
309*2fe8fb19SBen Gras.Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
310*2fe8fb19SBen Gras.It Sy Modifier Ta Cm c Ta Cm s
311*2fe8fb19SBen Gras.It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
312*2fe8fb19SBen Gras.El
313*2fe8fb19SBen Gras.It
314*2fe8fb19SBen GrasA character that specifies the type of conversion to be applied.
315*2fe8fb19SBen Gras.El
316*2fe8fb19SBen Gras.Pp
317*2fe8fb19SBen GrasA field width or precision, or both, may be indicated by
318*2fe8fb19SBen Grasan asterisk
319*2fe8fb19SBen Gras.Ql *
320*2fe8fb19SBen Grasor an asterisk followed by one or more decimal digits and a
321*2fe8fb19SBen Gras.Ql $
322*2fe8fb19SBen Grasinstead of a
323*2fe8fb19SBen Grasdigit string.
324*2fe8fb19SBen GrasIn this case, an
325*2fe8fb19SBen Gras.Vt int
326*2fe8fb19SBen Grasargument supplies the field width or precision.
327*2fe8fb19SBen GrasA negative field width is treated as a left adjustment flag followed by a
328*2fe8fb19SBen Graspositive field width; a negative precision is treated as though it were
329*2fe8fb19SBen Grasmissing.
330*2fe8fb19SBen GrasIf a single format directive mixes positional
331*2fe8fb19SBen Gras.Pq Li nn$
332*2fe8fb19SBen Grasand non-positional arguments, the results are undefined.
333*2fe8fb19SBen Gras.Pp
334*2fe8fb19SBen GrasThe conversion specifiers and their meanings are:
335*2fe8fb19SBen Gras.Bl -tag -width ".Cm diouxX"
336*2fe8fb19SBen Gras.It Cm diouxX
337*2fe8fb19SBen GrasThe
338*2fe8fb19SBen Gras.Vt int
339*2fe8fb19SBen Gras(or appropriate variant) argument is converted to signed decimal
340*2fe8fb19SBen Gras.Cm ( d
341*2fe8fb19SBen Grasand
342*2fe8fb19SBen Gras.Cm i ) ,
343*2fe8fb19SBen Grasunsigned octal
344*2fe8fb19SBen Gras.Pq Cm o ,
345*2fe8fb19SBen Grasunsigned decimal
346*2fe8fb19SBen Gras.Pq Cm u ,
347*2fe8fb19SBen Grasor unsigned hexadecimal
348*2fe8fb19SBen Gras.Cm ( x
349*2fe8fb19SBen Grasand
350*2fe8fb19SBen Gras.Cm X )
351*2fe8fb19SBen Grasnotation.
352*2fe8fb19SBen GrasThe letters
353*2fe8fb19SBen Gras.Dq Li abcdef
354*2fe8fb19SBen Grasare used for
355*2fe8fb19SBen Gras.Cm x
356*2fe8fb19SBen Grasconversions; the letters
357*2fe8fb19SBen Gras.Dq Li ABCDEF
358*2fe8fb19SBen Grasare used for
359*2fe8fb19SBen Gras.Cm X
360*2fe8fb19SBen Grasconversions.
361*2fe8fb19SBen GrasThe precision, if any, gives the minimum number of digits that must
362*2fe8fb19SBen Grasappear; if the converted value requires fewer digits, it is padded on
363*2fe8fb19SBen Grasthe left with zeros.
364*2fe8fb19SBen Gras.It Cm DOU
365*2fe8fb19SBen GrasThe
366*2fe8fb19SBen Gras.Vt "long int"
367*2fe8fb19SBen Grasargument is converted to signed decimal, unsigned octal, or unsigned
368*2fe8fb19SBen Grasdecimal, as if the format had been
369*2fe8fb19SBen Gras.Cm ld , lo ,
370*2fe8fb19SBen Grasor
371*2fe8fb19SBen Gras.Cm lu
372*2fe8fb19SBen Grasrespectively.
373*2fe8fb19SBen GrasThese conversion characters are deprecated, and will eventually disappear.
374*2fe8fb19SBen Gras.It Cm eE
375*2fe8fb19SBen GrasThe
376*2fe8fb19SBen Gras.Vt double
377*2fe8fb19SBen Grasargument is rounded and converted in the style
378*2fe8fb19SBen Gras.Sm off
379*2fe8fb19SBen Gras.Oo \- Oc Ar d Li \&. Ar ddd Li e \*[Pm] Ar dd
380*2fe8fb19SBen Gras.Sm on
381*2fe8fb19SBen Graswhere there is one digit before the
382*2fe8fb19SBen Grasdecimal-point character
383*2fe8fb19SBen Grasand the number of digits after it is equal to the precision;
384*2fe8fb19SBen Grasif the precision is missing,
385*2fe8fb19SBen Grasit is taken as 6; if the precision is
386*2fe8fb19SBen Graszero, no decimal-point character appears.
387*2fe8fb19SBen GrasAn
388*2fe8fb19SBen Gras.Cm E
389*2fe8fb19SBen Grasconversion uses the letter
390*2fe8fb19SBen Gras.Ql E
391*2fe8fb19SBen Gras(rather than
392*2fe8fb19SBen Gras.Ql e )
393*2fe8fb19SBen Grasto introduce the exponent.
394*2fe8fb19SBen GrasThe exponent always contains at least two digits; if the value is zero,
395*2fe8fb19SBen Grasthe exponent is 00.
396*2fe8fb19SBen Gras.Pp
397*2fe8fb19SBen GrasFor
398*2fe8fb19SBen Gras.Cm a , A , e , E , f , F , g ,
399*2fe8fb19SBen Grasand
400*2fe8fb19SBen Gras.Cm G
401*2fe8fb19SBen Grasconversions, positive and negative infinity are represented as
402*2fe8fb19SBen Gras.Li inf
403*2fe8fb19SBen Grasand
404*2fe8fb19SBen Gras.Li -inf
405*2fe8fb19SBen Grasrespectively when using the lowercase conversion character, and
406*2fe8fb19SBen Gras.Li INF
407*2fe8fb19SBen Grasand
408*2fe8fb19SBen Gras.Li -INF
409*2fe8fb19SBen Grasrespectively when using the uppercase conversion character.
410*2fe8fb19SBen GrasSimilarly, NaN is represented as
411*2fe8fb19SBen Gras.Li nan
412*2fe8fb19SBen Graswhen using the lowercase conversion, and
413*2fe8fb19SBen Gras.Li NAN
414*2fe8fb19SBen Graswhen using the uppercase conversion.
415*2fe8fb19SBen Gras.It Cm fF
416*2fe8fb19SBen GrasThe
417*2fe8fb19SBen Gras.Vt double
418*2fe8fb19SBen Grasargument is rounded and converted to decimal notation in the style
419*2fe8fb19SBen Gras.Sm off
420*2fe8fb19SBen Gras.Oo \- Oc Ar ddd Li \&. Ar ddd ,
421*2fe8fb19SBen Gras.Sm on
422*2fe8fb19SBen Graswhere the number of digits after the decimal-point character
423*2fe8fb19SBen Grasis equal to the precision specification.
424*2fe8fb19SBen GrasIf the precision is missing, it is taken as 6; if the precision is
425*2fe8fb19SBen Grasexplicitly zero, no decimal-point character appears.
426*2fe8fb19SBen GrasIf a decimal point appears, at least one digit appears before it.
427*2fe8fb19SBen Gras.It Cm gG
428*2fe8fb19SBen GrasThe
429*2fe8fb19SBen Gras.Vt double
430*2fe8fb19SBen Grasargument is converted in style
431*2fe8fb19SBen Gras.Cm f
432*2fe8fb19SBen Grasor
433*2fe8fb19SBen Gras.Cm e
434*2fe8fb19SBen Gras(or
435*2fe8fb19SBen Gras.Cm F
436*2fe8fb19SBen Grasor
437*2fe8fb19SBen Gras.Cm E
438*2fe8fb19SBen Grasfor
439*2fe8fb19SBen Gras.Cm G
440*2fe8fb19SBen Grasconversions).
441*2fe8fb19SBen GrasThe precision specifies the number of significant digits.
442*2fe8fb19SBen GrasIf the precision is missing, 6 digits are given; if the precision is zero,
443*2fe8fb19SBen Grasit is treated as 1.
444*2fe8fb19SBen GrasStyle
445*2fe8fb19SBen Gras.Cm e
446*2fe8fb19SBen Grasis used if the exponent from its conversion is less than \-4 or greater than
447*2fe8fb19SBen Grasor equal to the precision.
448*2fe8fb19SBen GrasTrailing zeros are removed from the fractional part of the result; a
449*2fe8fb19SBen Grasdecimal point appears only if it is followed by at least one digit.
450*2fe8fb19SBen Gras.It Cm aA
451*2fe8fb19SBen GrasThe
452*2fe8fb19SBen Gras.Vt double
453*2fe8fb19SBen Grasargument is converted to hexadecimal notation in the style
454*2fe8fb19SBen Gras.Sm off
455*2fe8fb19SBen Gras.Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \*[Pm] Oc Ar d ,
456*2fe8fb19SBen Gras.Sm on
457*2fe8fb19SBen Graswhere the number of digits after the hexadecimal-point character
458*2fe8fb19SBen Grasis equal to the precision specification.
459*2fe8fb19SBen GrasIf the precision is missing, it is taken as enough to exactly
460*2fe8fb19SBen Grasrepresent the floating-point number; if the precision is
461*2fe8fb19SBen Grasexplicitly zero, no hexadecimal-point character appears.
462*2fe8fb19SBen GrasThis is an exact conversion of the mantissa+exponent internal
463*2fe8fb19SBen Grasfloating point representation; the
464*2fe8fb19SBen Gras.Sm off
465*2fe8fb19SBen Gras.Oo \- Oc Li 0x Ar h Li \&. Ar hhh
466*2fe8fb19SBen Gras.Sm on
467*2fe8fb19SBen Grasportion represents exactly the mantissa; only denormalized
468*2fe8fb19SBen Grasmantissas have a zero value to the left of the hexadecimal
469*2fe8fb19SBen Graspoint.
470*2fe8fb19SBen GrasThe
471*2fe8fb19SBen Gras.Cm p
472*2fe8fb19SBen Grasis a literal character
473*2fe8fb19SBen Gras.Ql p ;
474*2fe8fb19SBen Grasthe exponent is preceded by a positive or negative sign
475*2fe8fb19SBen Grasand is represented in decimal, using only enough characters
476*2fe8fb19SBen Grasto represent the exponent.
477*2fe8fb19SBen GrasThe
478*2fe8fb19SBen Gras.Cm A
479*2fe8fb19SBen Grasconversion uses the prefix
480*2fe8fb19SBen Gras.Dq Li 0X
481*2fe8fb19SBen Gras(rather than
482*2fe8fb19SBen Gras.Dq Li 0x ) ,
483*2fe8fb19SBen Grasthe letters
484*2fe8fb19SBen Gras.Dq Li ABCDEF
485*2fe8fb19SBen Gras(rather than
486*2fe8fb19SBen Gras.Dq Li abcdef )
487*2fe8fb19SBen Grasto represent the hex digits, and the letter
488*2fe8fb19SBen Gras.Ql P
489*2fe8fb19SBen Gras(rather than
490*2fe8fb19SBen Gras.Ql p )
491*2fe8fb19SBen Grasto separate the mantissa and exponent.
492*2fe8fb19SBen Gras.It Cm C
493*2fe8fb19SBen GrasTreated as
494*2fe8fb19SBen Gras.Cm c
495*2fe8fb19SBen Graswith the
496*2fe8fb19SBen Gras.Cm l
497*2fe8fb19SBen Gras(ell) modifier.
498*2fe8fb19SBen Gras.It Cm c
499*2fe8fb19SBen GrasThe
500*2fe8fb19SBen Gras.Vt int
501*2fe8fb19SBen Grasargument is converted to an
502*2fe8fb19SBen Gras.Vt "unsigned char" ,
503*2fe8fb19SBen Grasthen to a
504*2fe8fb19SBen Gras.Vt wchar_t
505*2fe8fb19SBen Grasas if by
506*2fe8fb19SBen Gras.Xr btowc 3 ,
507*2fe8fb19SBen Grasand the resulting character is written.
508*2fe8fb19SBen Gras.Pp
509*2fe8fb19SBen GrasIf the
510*2fe8fb19SBen Gras.Cm l
511*2fe8fb19SBen Gras(ell) modifier is used, the
512*2fe8fb19SBen Gras.Vt wint_t
513*2fe8fb19SBen Grasargument is converted to a
514*2fe8fb19SBen Gras.Vt wchar_t
515*2fe8fb19SBen Grasand written.
516*2fe8fb19SBen Gras.It Cm S
517*2fe8fb19SBen GrasTreated as
518*2fe8fb19SBen Gras.Cm s
519*2fe8fb19SBen Graswith the
520*2fe8fb19SBen Gras.Cm l
521*2fe8fb19SBen Gras(ell) modifier.
522*2fe8fb19SBen Gras.It Cm s
523*2fe8fb19SBen GrasThe
524*2fe8fb19SBen Gras.Vt "char *"
525*2fe8fb19SBen Grasargument is expected to be a pointer to an array of character type (pointer
526*2fe8fb19SBen Grasto a string) containing a multibyte sequence.
527*2fe8fb19SBen GrasCharacters from the array are converted to wide characters and written up to
528*2fe8fb19SBen Gras(but not including)
529*2fe8fb19SBen Grasa terminating
530*2fe8fb19SBen Gras.Dv NUL
531*2fe8fb19SBen Grascharacter;
532*2fe8fb19SBen Grasif a precision is specified, no more than the number specified are
533*2fe8fb19SBen Graswritten.
534*2fe8fb19SBen GrasIf a precision is given, no null character
535*2fe8fb19SBen Grasneed be present; if the precision is not specified, or is greater than
536*2fe8fb19SBen Grasthe size of the array, the array must contain a terminating
537*2fe8fb19SBen Gras.Dv NUL
538*2fe8fb19SBen Grascharacter.
539*2fe8fb19SBen Gras.Pp
540*2fe8fb19SBen GrasIf the
541*2fe8fb19SBen Gras.Cm l
542*2fe8fb19SBen Gras(ell) modifier is used, the
543*2fe8fb19SBen Gras.Vt "wchar_t *"
544*2fe8fb19SBen Grasargument is expected to be a pointer to an array of wide characters
545*2fe8fb19SBen Gras(pointer to a wide string).
546*2fe8fb19SBen GrasEach wide character in the string
547*2fe8fb19SBen Grasis written.
548*2fe8fb19SBen GrasWide characters from the array are written up to (but not including)
549*2fe8fb19SBen Grasa terminating wide
550*2fe8fb19SBen Gras.Dv NUL
551*2fe8fb19SBen Grascharacter;
552*2fe8fb19SBen Grasif a precision is specified, no more than the number specified are
553*2fe8fb19SBen Graswritten (including shift sequences).
554*2fe8fb19SBen GrasIf a precision is given, no null character
555*2fe8fb19SBen Grasneed be present; if the precision is not specified, or is greater than
556*2fe8fb19SBen Grasthe number of characters in
557*2fe8fb19SBen Grasthe string, the array must contain a terminating wide
558*2fe8fb19SBen Gras.Dv NUL
559*2fe8fb19SBen Grascharacter.
560*2fe8fb19SBen Gras.It Cm p
561*2fe8fb19SBen GrasThe
562*2fe8fb19SBen Gras.Vt "void *"
563*2fe8fb19SBen Graspointer argument is printed in hexadecimal (as if by
564*2fe8fb19SBen Gras.Ql %#x
565*2fe8fb19SBen Grasor
566*2fe8fb19SBen Gras.Ql %#lx ) .
567*2fe8fb19SBen Gras.It Cm n
568*2fe8fb19SBen GrasThe number of characters written so far is stored into the
569*2fe8fb19SBen Grasinteger indicated by the
570*2fe8fb19SBen Gras.Vt "int *"
571*2fe8fb19SBen Gras(or variant) pointer argument.
572*2fe8fb19SBen GrasNo argument is converted.
573*2fe8fb19SBen Gras.It Cm %
574*2fe8fb19SBen GrasA
575*2fe8fb19SBen Gras.Ql %
576*2fe8fb19SBen Grasis written.
577*2fe8fb19SBen GrasNo argument is converted.
578*2fe8fb19SBen GrasThe complete conversion specification
579*2fe8fb19SBen Grasis
580*2fe8fb19SBen Gras.Ql %% .
581*2fe8fb19SBen Gras.El
582*2fe8fb19SBen Gras.Pp
583*2fe8fb19SBen GrasThe decimal point
584*2fe8fb19SBen Grascharacter is defined in the program's locale (category
585*2fe8fb19SBen Gras.Dv LC_NUMERIC ) .
586*2fe8fb19SBen Gras.Pp
587*2fe8fb19SBen GrasIn no case does a non-existent or small field width cause truncation of
588*2fe8fb19SBen Grasa numeric field; if the result of a conversion is wider than the field
589*2fe8fb19SBen Graswidth, the
590*2fe8fb19SBen Grasfield is expanded to contain the conversion result.
591*2fe8fb19SBen Gras.Sh RETURN VALUES
592*2fe8fb19SBen GrasThese functions return the number of characters printed
593*2fe8fb19SBen Gras(not including the trailing
594*2fe8fb19SBen Gras.Ql \e0
595*2fe8fb19SBen Grasused to end output to strings).
596*2fe8fb19SBen Gras.Sh SEE ALSO
597*2fe8fb19SBen Gras.Xr btowc 3 ,
598*2fe8fb19SBen Gras.Xr fputws 3 ,
599*2fe8fb19SBen Gras.Xr printf 3 ,
600*2fe8fb19SBen Gras.Xr putwc 3 ,
601*2fe8fb19SBen Gras.Xr setlocale 3 ,
602*2fe8fb19SBen Gras.Xr wcsrtombs 3 ,
603*2fe8fb19SBen Gras.Xr wscanf 3
604*2fe8fb19SBen Gras.Sh STANDARDS
605*2fe8fb19SBen GrasThe
606*2fe8fb19SBen Gras.Fn wprintf ,
607*2fe8fb19SBen Gras.Fn fwprintf ,
608*2fe8fb19SBen Gras.Fn swprintf ,
609*2fe8fb19SBen Gras.Fn vwprintf ,
610*2fe8fb19SBen Gras.Fn vfwprintf
611*2fe8fb19SBen Grasand
612*2fe8fb19SBen Gras.Fn vswprintf
613*2fe8fb19SBen Grasfunctions
614*2fe8fb19SBen Grasconform to
615*2fe8fb19SBen Gras.St -isoC-99 .
616*2fe8fb19SBen Gras.Sh SECURITY CONSIDERATIONS
617*2fe8fb19SBen GrasSubject to the caveats noted in the
618*2fe8fb19SBen Gras.Xr printf 3 .
619