1 .\" $NetBSD: wprintf.3,v 1.2 2005/06/03 20:32:20 wiz Exp $
2 .\" $DragonFly: src/lib/libc/stdio/wprintf.3,v 1.1 2005/07/25 00:37:41 joerg Exp $
3 .\" Copyright (c) 1990, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" This code is derived from software contributed to Berkeley by
7 .\" Chris Torek and the American National Standards Committee X3,
8 .\" on Information Processing Systems.
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. All advertising materials mentioning features or use of this software
19 .\" must display the following acknowledgement:
20 .\" This product includes software developed by the University of
21 .\" California, Berkeley and its contributors.
22 .\" 4. Neither the name of the University nor the names of its contributors
23 .\" may be used to endorse or promote products derived from this software
24 .\" without specific prior written permission.
26 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
38 .\" @(#)printf.3 8.1 (Berkeley) 6/4/93
39 .\" FreeBSD: src/lib/libc/stdio/printf.3,v 1.47 2002/09/06 11:23:55 tjr Exp
40 .\" $FreeBSD: src/lib/libc/stdio/wprintf.3,v 1.5 2003/07/05 07:55:34 tjr Exp $
46 .Nm wprintf , fwprintf , swprintf ,
47 .Nm vwprintf , vfwprintf , vswprintf
48 .Nd formatted wide character output conversion
55 .Fn fwprintf "FILE * restrict stream" "const wchar_t * restrict format" ...
57 .Fn swprintf "wchar_t * restrict ws" "size_t n" "const wchar_t * restrict format" ...
59 .Fn wprintf "const wchar_t * restrict format" ...
62 .Fn vfwprintf "FILE * restrict stream" "const wchar_t * restrict" "va_list ap"
64 .Fn vswprintf "wchar_t * restrict ws" "size_t n" "const wchar_t *restrict format" "va_list ap"
66 .Fn vwprintf "const wchar_t * restrict format" "va_list ap"
70 family of functions produces output according to a
80 the standard output stream;
84 write output to the given output
89 write to the wide character string
92 These functions write the output under the control of a
94 string that specifies how subsequent arguments
95 (or arguments accessed via the variable-length argument facilities of
97 are converted for output.
99 These functions return the number of characters printed
100 (not including the trailing
102 used to end output to strings).
108 functions will fail if
110 or more wide characters were requested to be written,
112 The format string is composed of zero or more directives:
116 which are copied unchanged to the output stream;
117 and conversion specifications, each of which results
118 in fetching zero or more subsequent arguments.
119 Each conversion specification is introduced by
123 The arguments must correspond properly (after type promotion)
124 with the conversion specifier.
127 the following appear in sequence:
130 An optional field, consisting of a decimal digit string followed by a
132 specifying the next argument to access.
133 If this field is not provided, the argument following the last
134 argument accessed will be used.
135 Arguments are numbered starting at
137 If unaccessed arguments in the format string are interspersed with ones that
138 are accessed the results will be indeterminate.
140 Zero or more of the following flags:
141 .Bl -tag -width ".So \ Sc (space)"
143 The value should be converted to an
146 .Cm c , d , i , n , p , s ,
149 conversions, this option has no effect.
152 conversions, the precision of the number is increased to force the first
153 character of the output string to a zero (except if a zero value is printed
154 with an explicit precision of zero).
159 conversions, a non-zero result has the string
165 conversions) prepended to it.
167 .Cm a , A , e , E , f , F , g ,
170 conversions, the result will always contain a decimal point, even if no
171 digits follow it (normally, a decimal point appears in the results of
172 those conversions only if a digit follows).
177 conversions, trailing zeros are not removed from the result as they
179 .It So Cm 0 Sc (zero)
181 For all conversions except
183 the converted value is padded on the left with zeros rather than blanks.
184 If a precision is given with a numeric conversion
185 .Cm ( d , i , o , u , i , x ,
192 A negative field width flag;
193 the converted value is to be left adjusted on the field boundary.
196 conversions, the converted value is padded on the right with blanks,
197 rather than on the left with blanks or zeros.
203 .It So "\ " Sc (space)
204 A blank should be left before a positive number
205 produced by a signed conversion
206 .Cm ( a , A , d , e , E , f , F , g , G ,
210 A sign must always be placed before a
211 number produced by a signed conversion.
214 overrides a space if both are used.
220 or the integral portion of a floating point conversion
224 should be grouped and separated by thousands using
225 the non-monetary separator returned by
229 An optional decimal digit string specifying a minimum field width.
230 If the converted value has fewer characters than the field width, it will
231 be padded with spaces on the left (or right, if the left-adjustment
232 flag has been given) to fill out
235 An optional precision, in the form of a period
238 optional digit string.
239 If the digit string is omitted, the precision is taken as zero.
240 This gives the minimum number of digits to appear for
241 .Cm d , i , o , u , x ,
244 conversions, the number of digits to appear after the decimal-point for
245 .Cm a , A , e , E , f ,
248 conversions, the maximum number of significant digits for
252 conversions, or the maximum number of characters to be printed from a
257 An optional length modifier, that specifies the size of the argument.
258 The following length modifiers are valid for the
259 .Cm d , i , n , o , u , x ,
263 .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
264 .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
265 .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
266 .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
267 .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
268 .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
269 .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
270 .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
271 .It Cm z Ta (see note) Ta Vt size_t Ta (see note)
272 .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
278 modifier, when applied to a
282 conversion, indicates that the argument is of an unsigned type
283 equivalent in size to a
287 modifier, when applied to a
291 conversion, indicates that the argument is of a signed type equivalent in
294 Similarly, when applied to an
296 conversion, it indicates that the argument is a pointer to a signed type
297 equivalent in size to a
300 The following length modifier is valid for the
301 .Cm a , A , e , E , f , F , g ,
305 .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
306 .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
307 .It Cm L Ta Vt "long double"
310 The following length modifier is valid for the
315 .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
316 .It Sy Modifier Ta Cm c Ta Cm s
317 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
320 A character that specifies the type of conversion to be applied.
323 A field width or precision, or both, may be indicated by
326 or an asterisk followed by one or more decimal digits and a
332 argument supplies the field width or precision.
333 A negative field width is treated as a left adjustment flag followed by a
334 positive field width; a negative precision is treated as though it were
336 If a single format directive mixes positional
338 and non-positional arguments, the results are undefined.
340 The conversion specifiers and their meanings are:
341 .Bl -tag -width ".Cm diouxX"
345 (or appropriate variant) argument is converted to signed decimal
353 or unsigned hexadecimal
362 conversions; the letters
367 The precision, if any, gives the minimum number of digits that must
368 appear; if the converted value requires fewer digits, it is padded on
373 argument is converted to signed decimal, unsigned octal, or unsigned
374 decimal, as if the format had been
379 These conversion characters are deprecated, and will eventually disappear.
383 argument is rounded and converted in the style
385 .Oo \- Oc Ar d Li \&. Ar ddd Li e \\*[Pm] Ar dd
387 where there is one digit before the
388 decimal-point character
389 and the number of digits after it is equal to the precision;
390 if the precision is missing,
391 it is taken as 6; if the precision is
392 zero, no decimal-point character appears.
395 conversion uses the letter
399 to introduce the exponent.
400 The exponent always contains at least two digits; if the value is zero,
404 .Cm a , A , e , E , f , F , g ,
407 conversions, positive and negative infinity are represented as
411 respectively when using the lowercase conversion character, and
415 respectively when using the uppercase conversion character.
416 Similarly, NaN is represented as
418 when using the lowercase conversion, and
420 when using the uppercase conversion.
424 argument is rounded and converted to decimal notation in the style
426 .Oo \- Oc Ar ddd Li \&. Ar ddd ,
428 where the number of digits after the decimal-point character
429 is equal to the precision specification.
430 If the precision is missing, it is taken as 6; if the precision is
431 explicitly zero, no decimal-point character appears.
432 If a decimal point appears, at least one digit appears before it.
436 argument is converted in style
447 The precision specifies the number of significant digits.
448 If the precision is missing, 6 digits are given; if the precision is zero,
452 is used if the exponent from its conversion is less than \-4 or greater than
453 or equal to the precision.
454 Trailing zeros are removed from the fractional part of the result; a
455 decimal point appears only if it is followed by at least one digit.
459 argument is converted to hexadecimal notation in the style
461 .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \\*[Pm] Oc Ar d ,
463 where the number of digits after the hexadecimal-point character
464 is equal to the precision specification.
465 If the precision is missing, it is taken as enough to exactly
466 represent the floating-point number; if the precision is
467 explicitly zero, no hexadecimal-point character appears.
468 This is an exact conversion of the mantissa+exponent internal
469 floating point representation; the
471 .Oo \- Oc Li 0x Ar h Li \&. Ar hhh
473 portion represents exactly the mantissa; only denormalized
474 mantissas have a zero value to the left of the hexadecimal
478 is a literal character
480 the exponent is preceded by a positive or negative sign
481 and is represented in decimal, using only enough characters
482 to represent the exponent.
485 conversion uses the prefix
493 to represent the hex digits, and the letter
497 to separate the mantissa and exponent.
507 argument is converted to an
508 .Vt "unsigned char" ,
513 and the resulting character is written.
517 (ell) modifier is used, the
519 argument is converted to a
531 argument is expected to be a pointer to an array of character type (pointer
532 to a string) containing a multibyte sequence.
533 Characters from the array are converted to wide characters and written up to
538 if a precision is specified, no more than the number specified are
540 If a precision is given, no null character
541 need be present; if the precision is not specified, or is greater than
542 the size of the array, the array must contain a terminating
548 (ell) modifier is used, the
550 argument is expected to be a pointer to an array of wide characters
551 (pointer to a wide string).
552 Each wide character in the string
554 Wide characters from the array are written up to (but not including)
558 if a precision is specified, no more than the number specified are
559 written (including shift sequences).
560 If a precision is given, no null character
561 need be present; if the precision is not specified, or is greater than
562 the number of characters in
563 the string, the array must contain a terminating wide
569 pointer argument is printed in hexadecimal (as if by
574 The number of characters written so far is stored into the
575 integer indicated by the
577 (or variant) pointer argument.
578 No argument is converted.
583 No argument is converted.
584 The complete conversion specification
590 character is defined in the program's locale (category
593 In no case does a non-existent or small field width cause truncation of
594 a numeric field; if the result of a conversion is wider than the field
596 field is expanded to contain the conversion result.
606 Subject to the caveats noted in the
607 .Sh SECURITY CONSIDERATIONS