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