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