1 .\" Copyright (c) 1990, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
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.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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
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
40 .Nm wprintf , fwprintf , swprintf ,
41 .Nm vwprintf , vfwprintf , vswprintf
42 .Nd formatted wide character output conversion
49 .Fn fwprintf "FILE * restrict stream" "const wchar_t * restrict format" ...
51 .Fn swprintf "wchar_t * restrict ws" "size_t n" "const wchar_t * restrict format" ...
53 .Fn wprintf "const wchar_t * restrict format" ...
56 .Fn vfwprintf "FILE * restrict stream" "const wchar_t * restrict" "va_list ap"
58 .Fn vswprintf "wchar_t * restrict ws" "size_t n" "const wchar_t *restrict format" "va_list ap"
60 .Fn vwprintf "const wchar_t * restrict format" "va_list ap"
64 family of functions produces output according to a
74 the standard output stream;
78 write output to the given output
83 write to the wide character string
86 Extended locale versions of these functions are documented in
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 return the number of characters written (not including the terminating
109 null wide character).
110 These functions will fail (returning a negative value and setting
114 or more wide characters were requested to be written.
116 The other functions return the number of wide characters printed on success, or
117 a negative value on faiure, setting
119 to indicate the error.
121 The format string is composed of zero or more directives:
125 which are copied unchanged to the output stream;
126 and conversion specifications, each of which results
127 in fetching zero or more subsequent arguments.
128 Each conversion specification is introduced by
132 The arguments must correspond properly (after type promotion)
133 with the conversion specifier.
136 the following appear in sequence:
139 An optional field, consisting of a decimal digit string followed by a
141 specifying the next argument to access.
142 If this field is not provided, the argument following the last
143 argument accessed will be used.
144 Arguments are numbered starting at
146 If unaccessed arguments in the format string are interspersed with ones that
147 are accessed the results will be indeterminate.
149 Zero or more of the following flags:
150 .Bl -tag -width ".So \ Sc (space)"
152 The value should be converted to an
155 .Cm c , d , i , n , p , s ,
158 conversions, this option has no effect.
161 conversions, the precision of the number is increased to force the first
162 character of the output string to a zero (except if a zero value is printed
163 with an explicit precision of zero).
168 conversions, a non-zero result has the string
174 conversions) prepended to it.
176 .Cm a , A , e , E , f , F , g ,
179 conversions, the result will always contain a decimal point, even if no
180 digits follow it (normally, a decimal point appears in the results of
181 those conversions only if a digit follows).
186 conversions, trailing zeros are not removed from the result as they
188 .It So Cm 0 Sc (zero)
190 For all conversions except
192 the converted value is padded on the left with zeros rather than blanks.
193 If a precision is given with a numeric conversion
194 .Cm ( d , i , o , u , i , x ,
201 A negative field width flag;
202 the converted value is to be left adjusted on the field boundary.
205 conversions, the converted value is padded on the right with blanks,
206 rather than on the left with blanks or zeros.
212 .It So "\ " Sc (space)
213 A blank should be left before a positive number
214 produced by a signed conversion
215 .Cm ( a , A , d , e , E , f , F , g , G ,
219 A sign must always be placed before a
220 number produced by a signed conversion.
223 overrides a space if both are used.
229 or the integral portion of a floating point conversion
233 should be grouped and separated by thousands using
234 the non-monetary separator returned by
238 An optional decimal digit string specifying a minimum field width.
239 If the converted value has fewer characters than the field width, it will
240 be padded with spaces on the left (or right, if the left-adjustment
241 flag has been given) to fill out
244 An optional precision, in the form of a period
247 optional digit string.
248 If the digit string is omitted, the precision is taken as zero.
249 This gives the minimum number of digits to appear for
250 .Cm d , i , o , u , x ,
253 conversions, the number of digits to appear after the decimal-point for
254 .Cm a , A , e , E , f ,
257 conversions, the maximum number of significant digits for
261 conversions, or the maximum number of characters to be printed from a
266 An optional length modifier, that specifies the size of the argument.
267 The following length modifiers are valid for the
268 .Cm d , i , n , o , u , x ,
272 .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
273 .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
274 .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
275 .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
276 .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
277 .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
278 .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
279 .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
280 .It Cm z Ta (see note) Ta Vt size_t Ta (see note)
281 .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
287 modifier, when applied to a
291 conversion, indicates that the argument is of an unsigned type
292 equivalent in size to a
296 modifier, when applied to a
300 conversion, indicates that the argument is of a signed type equivalent in
303 Similarly, when applied to an
305 conversion, it indicates that the argument is a pointer to a signed type
306 equivalent in size to a
309 The following length modifier is valid for the
310 .Cm a , A , e , E , f , F , g ,
314 .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G"
315 .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G
316 .It Cm L Ta Vt "long double"
319 The following length modifier is valid for the
324 .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *"
325 .It Sy Modifier Ta Cm c Ta Cm s
326 .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
329 A character that specifies the type of conversion to be applied.
332 A field width or precision, or both, may be indicated by
335 or an asterisk followed by one or more decimal digits and a
341 argument supplies the field width or precision.
342 A negative field width is treated as a left adjustment flag followed by a
343 positive field width; a negative precision is treated as though it were
345 If a single format directive mixes positional
347 and non-positional arguments, the results are undefined.
349 The conversion specifiers and their meanings are:
350 .Bl -tag -width ".Cm diouxX"
354 (or appropriate variant) argument is converted to signed decimal
362 or unsigned hexadecimal
371 conversions; the letters
376 The precision, if any, gives the minimum number of digits that must
377 appear; if the converted value requires fewer digits, it is padded on
382 argument is converted to signed decimal, unsigned octal, or unsigned
383 decimal, as if the format had been
388 These conversion characters are deprecated, and will eventually disappear.
392 argument is rounded and converted in the style
394 .Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd
396 where there is one digit before the
397 decimal-point character
398 and the number of digits after it is equal to the precision;
399 if the precision is missing,
400 it is taken as 6; if the precision is
401 zero, no decimal-point character appears.
404 conversion uses the letter
408 to introduce the exponent.
409 The exponent always contains at least two digits; if the value is zero,
413 .Cm a , A , e , E , f , F , g ,
416 conversions, positive and negative infinity are represented as
420 respectively when using the lowercase conversion character, and
424 respectively when using the uppercase conversion character.
425 Similarly, NaN is represented as
427 when using the lowercase conversion, and
429 when using the uppercase conversion.
433 argument is rounded and converted to decimal notation in the style
435 .Oo \- Oc Ar ddd Li \&. Ar ddd ,
437 where the number of digits after the decimal-point character
438 is equal to the precision specification.
439 If the precision is missing, it is taken as 6; if the precision is
440 explicitly zero, no decimal-point character appears.
441 If a decimal point appears, at least one digit appears before it.
445 argument is converted in style
456 The precision specifies the number of significant digits.
457 If the precision is missing, 6 digits are given; if the precision is zero,
461 is used if the exponent from its conversion is less than \-4 or greater than
462 or equal to the precision.
463 Trailing zeros are removed from the fractional part of the result; a
464 decimal point appears only if it is followed by at least one digit.
468 argument is converted to hexadecimal notation in the style
470 .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d ,
472 where the number of digits after the hexadecimal-point character
473 is equal to the precision specification.
474 If the precision is missing, it is taken as enough to exactly
475 represent the floating-point number; if the precision is
476 explicitly zero, no hexadecimal-point character appears.
477 This is an exact conversion of the mantissa+exponent internal
478 floating point representation; the
480 .Oo \- Oc Li 0x Ar h Li \&. Ar hhh
482 portion represents exactly the mantissa; only denormalized
483 mantissas have a zero value to the left of the hexadecimal
487 is a literal character
489 the exponent is preceded by a positive or negative sign
490 and is represented in decimal, using only enough characters
491 to represent the exponent.
494 conversion uses the prefix
502 to represent the hex digits, and the letter
506 to separate the mantissa and exponent.
516 argument is converted to an
517 .Vt "unsigned char" ,
522 and the resulting character is written.
526 (ell) modifier is used, the
528 argument is converted to a
540 argument is expected to be a pointer to an array of character type (pointer
541 to a string) containing a multibyte sequence.
542 Characters from the array are converted to wide characters and written up to
547 if a precision is specified, no more than the number specified are
549 If a precision is given, no null character
550 need be present; if the precision is not specified, or is greater than
551 the size of the array, the array must contain a terminating
557 (ell) modifier is used, the
559 argument is expected to be a pointer to an array of wide characters
560 (pointer to a wide string).
561 Each wide character in the string
563 Wide characters from the array are written up to (but not including)
567 if a precision is specified, no more than the number specified are
568 written (including shift sequences).
569 If a precision is given, no null character
570 need be present; if the precision is not specified, or is greater than
571 the number of characters in
572 the string, the array must contain a terminating wide
578 pointer argument is printed in hexadecimal (as if by
583 The number of characters written so far is stored into the
584 integer indicated by the
586 (or variant) pointer argument.
587 No argument is converted.
592 No argument is converted.
593 The complete conversion specification
599 character is defined in the program's locale (category
602 In no case does a non-existent or small field width cause truncation of
603 a numeric field; if the result of a conversion is wider than the field
605 field is expanded to contain the conversion result.
606 .Sh SECURITY CONSIDERATIONS
622 Subject to the caveats noted in the