1FWPRINTF(3P) POSIX Programmer's Manual FWPRINTF(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 fwprintf, swprintf, wprintf - print formatted wide-character output
13
15 #include <stdio.h>
16 #include <wchar.h>
17 int fwprintf(FILE *restrict stream, const wchar_t *restrict format,
19 ...);
20 int swprintf(wchar_t *restrict ws, size_t n,
21 const wchar_t *restrict format, ...);
22 int wprintf(const wchar_t *restrict format, ...);
23
26 The fwprintf() function shall place output on the named output stream.
27 The wprintf() function shall place output on the standard output stream
28 stdout. The swprintf() function shall place output followed by the null
29 wide character in consecutive wide characters starting at *ws; no more
30 than n wide characters shall be written, including a terminating null
31 wide character, which is always added (unless n is zero).
32 Each of these functions shall convert, format, and print its arguments
34 under control of the format wide-character string. The format is com‐
35 posed of zero or more directives: ordinary wide-characters, which are
36 simply copied to the output stream, and conversion specifications, each
37 of which results in the fetching of zero or more arguments. The results
38 are undefined if there are insufficient arguments for the format. If
39 the format is exhausted while arguments remain, the excess arguments
40 are evaluated but are otherwise ignored.
41 Conversions can be applied to the nth argument after the format in the
43 argument list, rather than to the next unused argument. In this case,
44 the conversion specifier wide character % (see below) is replaced by
45 the sequence "%n$", where n is a decimal integer in the range
46 [1,{NL_ARGMAX}], giving the position of the argument in the argument
47 list. This feature provides for the definition of format wide-character
48 strings that select arguments in an order appropriate to specific lan‐
49 guages (see the EXAMPLES section).
50 The format can contain either numbered argument specifications (that
52 is, "%n$" and "*m$"), or unnumbered argument conversion specifications
53 (that is, % and * ), but not both. The only exception to this is that
54 %% can be mixed with the "%n$" form. The results of mixing numbered and
55 unnumbered argument specifications in a format wide-character string
56 are undefined. When numbered argument specifications are used, specify‐
57 ing the Nth argument requires that all the leading arguments, from the
58 first to the (N-1)th, are specified in the format wide-character
59 string.
60 In format wide-character strings containing the "%n$" form of conver‐
62 sion specification, numbered arguments in the argument list can be ref‐
63 erenced from the format wide-character string as many times as
64 required.
65 In format wide-character strings containing the % form of conversion
67 specification, each argument in the argument list shall be used exactly
68 once.
69 All forms of the fwprintf() function allow for the insertion of a
71 locale-dependent radix character in the output string, output as a
72 wide-character value. The radix character is defined in the program's
73 locale (category LC_NUMERIC ). In the POSIX locale, or in a locale
74 where the radix character is not defined, the radix character shall
75 default to a period ( '.' ).
76 Each conversion specification is introduced by the '%' wide character
78 or by the wide-character sequence "%n$", after which the following
79 appear in sequence:
80 * Zero or more flags (in any order), which modify the meaning of the
82 conversion specification.
83 * An optional minimum field width. If the converted value has fewer
85 wide characters than the field width, it shall be padded with spaces
86 by default on the left; it shall be padded on the right, if the
87 left-adjustment flag ( '-' ), described below, is given to the field
88 width. The field width takes the form of an asterisk ( '*' ),
89 described below, or a decimal integer.
90 * An optional precision that gives the minimum number of digits to
92 appear for the d, i, o, u, x, and X conversion specifiers; the num‐
93 ber of digits to appear after the radix character for the a, A, e,
94 E, f, and F conversion specifiers; the maximum number of significant
95 digits for the g and G conversion specifiers; or the maximum number
96 of wide characters to be printed from a string in the s conversion
97 specifiers. The precision takes the form of a period ( '.' ) fol‐
98 lowed either by an asterisk ( '*' ), described below, or an optional
99 decimal digit string, where a null digit string is treated as 0. If
100 a precision appears with any other conversion wide character, the
101 behavior is undefined.
102 * An optional length modifier that specifies the size of the argument.
104 * A conversion specifier wide character that indicates the type of
106 conversion to be applied.
107 A field width, or precision, or both, may be indicated by an asterisk (
109 '*' ). In this case an argument of type int supplies the field width or
110 precision. Applications shall ensure that arguments specifying field
111 width, or precision, or both appear in that order before the argument,
112 if any, to be converted. A negative field width is taken as a '-' flag
113 followed by a positive field width. A negative precision is taken as if
114 the precision were omitted. In format wide-character strings contain‐
115 ing the "%n$" form of a conversion specification, a field width or pre‐
116 cision may be indicated by the sequence "*m$", where m is a decimal
117 integer in the range [1,{NL_ARGMAX}] giving the position in the argu‐
118 ment list (after the format argument) of an integer argument containing
119 the field width or precision, for example:
120 wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);
123 The flag wide characters and their meanings are:
125 ' The integer portion of the result of a decimal conversion ( %i,
127 %d, %u, %f, %F, %g, or %G ) shall be formatted with thousands'
128 grouping wide characters. For other conversions, the behavior is
129 undefined. The numeric grouping wide character is used.
130 - The result of the conversion shall be left-justified within the
132 field. The conversion shall be right-justified if this flag is
133 not specified.
134 + The result of a signed conversion shall always begin with a sign
136 ( '+' or '-' ). The conversion shall begin with a sign only when
137 a negative value is converted if this flag is not specified.
138 <space>
140 If the first wide character of a signed conversion is not a
141 sign, or if a signed conversion results in no wide characters, a
142 <space> shall be prefixed to the result. This means that if the
143 <space> and '+' flags both appear, the <space> flag shall be
144 ignored.
145 # Specifies that the value is to be converted to an alternative
147 form. For o conversion, it increases the precision (if neces‐
148 sary) to force the first digit of the result to be 0. For x or X
149 conversion specifiers, a non-zero result shall have 0x (or 0X)
150 prefixed to it. For a, A, e, E, f, F, g, and G conversion speci‐
151 fiers, the result shall always contain a radix character, even
152 if no digits follow it. Without this flag, a radix character
153 appears in the result of these conversions only if a digit fol‐
154 lows it. For g and G conversion specifiers, trailing zeros shall
155 not be removed from the result as they normally are. For other
156 conversion specifiers, the behavior is undefined.
157 0 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversion
159 specifiers, leading zeros (following any indication of sign or
160 base) are used to pad to the field width; no space padding is
161 performed. If the '0' and '-' flags both appear, the '0' flag
162 shall be ignored. For d, i, o, u, x, and X conversion speci‐
163 fiers, if a precision is specified, the '0' flag shall be
164 ignored. If the '0' and '" flags both appear, the grouping wide
165 characters are inserted before zero padding. For other conver‐
166 sions, the behavior is undefined.
167 The length modifiers and their meanings are:
170 hh Specifies that a following d, i, o, u, x, or X conversion speci‐
172 fier applies to a signed char or unsigned char argument (the
173 argument will have been promoted according to the integer promo‐
174 tions, but its value shall be converted to signed char or
175 unsigned char before printing); or that a following n conversion
176 specifier applies to a pointer to a signed char argument.
177 h Specifies that a following d, i, o, u, x, or X conversion speci‐
179 fier applies to a short or unsigned short argument (the argument
180 will have been promoted according to the integer promotions, but
181 its value shall be converted to short or unsigned short before
182 printing); or that a following n conversion specifier applies to
183 a pointer to a short argument.
184 l (ell)
186 Specifies that a following d, i, o, u, x, or X conversion speci‐
187 fier applies to a long or unsigned long argument; that a follow‐
188 ing n conversion specifier applies to a pointer to a long argu‐
189 ment; that a following c conversion specifier applies to a
190 wint_t argument; that a following s conversion specifier applies
191 to a pointer to a wchar_t argument; or has no effect on a fol‐
192 lowing a, A, e, E, f, F, g, or G conversion specifier.
193 ll (ell-ell)
195 Specifies that a following d, i, o, u, x, or X conversion speci‐
197 fier applies to a long long or unsigned long long argument; or
198 that a following n conversion specifier applies to a pointer to
199 a long long argument.
200 j Specifies that a following d, i, o, u, x, or X conversion speci‐
202 fier applies to an intmax_t or uintmax_t argument; or that a
203 following n conversion specifier applies to a pointer to an int‐
204 max_t argument.
205 z Specifies that a following d, i, o, u, x, or X conversion speci‐
207 fier applies to a size_t or the corresponding signed integer
208 type argument; or that a following n conversion specifier
209 applies to a pointer to a signed integer type corresponding to a
210 size_t argument.
211 t Specifies that a following d, i, o, u, x, or X conversion speci‐
213 fier applies to a ptrdiff_t or the corresponding unsigned type
214 argument; or that a following n conversion specifier applies to
215 a pointer to a ptrdiff_t argument.
216 L Specifies that a following a, A, e, E, f, F, g, or G conversion
218 specifier applies to a long double argument.
219 If a length modifier appears with any conversion specifier other than
222 as specified above, the behavior is undefined.
223 The conversion specifiers and their meanings are:
225 d, i The int argument shall be converted to a signed decimal in the
227 style "[-]dddd". The precision specifies the minimum number of
228 digits to appear; if the value being converted can be repre‐
229 sented in fewer digits, it shall be expanded with leading zeros.
230 The default precision shall be 1. The result of converting zero
231 with an explicit precision of zero shall be no wide characters.
232 o The unsigned argument shall be converted to unsigned octal for‐
234 mat in the style "dddd" . The precision specifies the minimum
235 number of digits to appear; if the value being converted can be
236 represented in fewer digits, it shall be expanded with leading
237 zeros. The default precision shall be 1. The result of convert‐
238 ing zero with an explicit precision of zero shall be no wide
239 characters.
240 u The unsigned argument shall be converted to unsigned decimal
242 format in the style "dddd" . The precision specifies the minimum
243 number of digits to appear; if the value being converted can be
244 represented in fewer digits, it shall be expanded with leading
245 zeros. The default precision shall be 1. The result of convert‐
246 ing zero with an explicit precision of zero shall be no wide
247 characters.
248 x The unsigned argument shall be converted to unsigned hexadecimal
250 format in the style "dddd" ; the letters "abcdef" are used. The
251 precision specifies the minimum number of digits to appear; if
252 the value being converted can be represented in fewer digits, it
253 shall be expanded with leading zeros. The default precision
254 shall be 1. The result of converting zero with an explicit pre‐
255 cision of zero shall be no wide characters.
256 X Equivalent to the x conversion specifier, except that letters
258 "ABCDEF" are used instead of "abcdef" .
259 f, F The double argument shall be converted to decimal notation in
261 the style "[-]ddd.ddd", where the number of digits after the
262 radix character shall be equal to the precision specification.
263 If the precision is missing, it shall be taken as 6; if the pre‐
264 cision is explicitly zero and no '#' flag is present, no radix
265 character shall appear. If a radix character appears, at least
266 one digit shall appear before it. The value shall be rounded in
267 an implementation-defined manner to the appropriate number of
268 digits.
269 A double argument representing an infinity shall be converted in one of
271 the styles "[-]inf" or "[-]infinity" ; which style is implementation-
272 defined. A double argument representing a NaN shall be converted in one
273 of the styles "[-]nan" or "[-]nan(n-char-sequence)"; which style, and
274 the meaning of any n-char-sequence, is implementation-defined. The F
275 conversion specifier produces "INF", "INFINITY", or "NAN" instead of
276 "inf", "infinity", or "nan", respectively.
277 e, E The double argument shall be converted in the style
279 "[-]d.ddde±dd", where there shall be one digit before the radix
280 character (which is non-zero if the argument is non-zero) and
281 the number of digits after it shall be equal to the precision;
282 if the precision is missing, it shall be taken as 6; if the pre‐
283 cision is zero and no '#' flag is present, no radix character
284 shall appear. The value shall be rounded in an implementation-
285 defined manner to the appropriate number of digits. The E con‐
286 version wide character shall produce a number with 'E' instead
287 of 'e' introducing the exponent. The exponent shall always con‐
288 tain at least two digits. If the value is zero, the exponent
289 shall be zero.
290 A double argument representing an infinity or NaN shall be converted in
292 the style of an f or F conversion specifier.
293 g, G The double argument shall be converted in the style f or e (or
295 in the style F or E in the case of a G conversion specifier),
296 with the precision specifying the number of significant digits.
297 If an explicit precision is zero, it shall be taken as 1. The
298 style used depends on the value converted; style e (or E ) shall
299 be used only if the exponent resulting from such a conversion is
300 less than -4 or greater than or equal to the precision. Trailing
301 zeros shall be removed from the fractional portion of the
302 result; a radix character shall appear only if it is followed by
303 a digit.
304 A double argument representing an infinity or NaN shall be converted in
306 the style of an f or F conversion specifier.
307 a, A A double argument representing a floating-point number shall be
309 converted in the style "[-]0xh.hhhhp±d", where there shall be
310 one hexadecimal digit (which is non-zero if the argument is a
311 normalized floating-point number and is otherwise unspecified)
312 before the decimal-point wide character and the number of hexa‐
313 decimal digits after it shall be equal to the precision; if the
314 precision is missing and FLT_RADIX is a power of 2, then the
315 precision shall be sufficient for an exact representation of the
316 value; if the precision is missing and FLT_RADIX is not a power
317 of 2, then the precision shall be sufficient to distinguish val‐
318 ues of type double, except that trailing zeros may be omitted;
319 if the precision is zero and the '#' flag is not specified, no
320 decimal-point wide character shall appear. The letters "abcdef"
321 are used for a conversion and the letters "ABCDEF" for A conver‐
322 sion. The A conversion specifier produces a number with 'X' and
323 'P' instead of 'x' and 'p' . The exponent shall always contain
324 at least one digit, and only as many more digits as necessary to
325 represent the decimal exponent of 2. If the value is zero, the
326 exponent shall be zero.
327 A double argument representing an infinity or NaN shall be converted in
329 the style of an f or F conversion specifier.
330 c If no l (ell) qualifier is present, the int argument shall be
332 converted to a wide character as if by calling the btowc() func‐
333 tion and the resulting wide character shall be written. Other‐
334 wise, the wint_t argument shall be converted to wchar_t, and
335 written.
336 s If no l (ell) qualifier is present, the application shall ensure
338 that the argument is a pointer to a character array containing a
339 character sequence beginning in the initial shift state. Char‐
340 acters from the array shall be converted as if by repeated calls
341 to the mbrtowc() function, with the conversion state described
342 by an mbstate_t object initialized to zero before the first
343 character is converted, and written up to (but not including)
344 the terminating null wide character. If the precision is speci‐
345 fied, no more than that many wide characters shall be written.
346 If the precision is not specified, or is greater than the size
347 of the array, the application shall ensure that the array con‐
348 tains a null wide character.
349 If an l (ell) qualifier is present, the application shall ensure that
351 the argument is a pointer to an array of type wchar_t. Wide characters
352 from the array shall be written up to (but not including) a terminating
353 null wide character. If no precision is specified, or is greater than
354 the size of the array, the application shall ensure that the array con‐
355 tains a null wide character. If a precision is specified, no more than
356 that many wide characters shall be written.
357 p The application shall ensure that the argument is a pointer to
359 void. The value of the pointer shall be converted to a sequence
360 of printable wide characters in an implementation-defined man‐
361 ner.
362 n The application shall ensure that the argument is a pointer to
364 an integer into which is written the number of wide characters
365 written to the output so far by this call to one of the
366 fwprintf() functions. No argument shall be converted, but one
367 shall be consumed. If the conversion specification includes any
368 flags, a field width, or a precision, the behavior is undefined.
369 C Equivalent to lc .
371 S Equivalent to ls .
373 % Output a '%' wide character; no argument shall be converted.
375 The entire conversion specification shall be %% .
376 If a conversion specification does not match one of the above forms,
379 the behavior is undefined.
380 In no case does a nonexistent or small field width cause truncation of
382 a field; if the result of a conversion is wider than the field width,
383 the field shall be expanded to contain the conversion result. Charac‐
384 ters generated by fwprintf() and wprintf() shall be printed as if
385 fputwc() had been called.
386 For a and A conversions, if FLT_RADIX is not a power of 2 and the
388 result is not exactly representable in the given precision, the result
389 should be one of the two adjacent numbers in hexadecimal floating style
390 with the given precision, with the extra stipulation that the error
391 should have a correct sign for the current rounding direction.
392 For e, E, f, F, g, and G conversion specifiers, if the number of sig‐
394 nificant decimal digits is at most DECIMAL_DIG, then the result should
395 be correctly rounded. If the number of significant decimal digits is
396 more than DECIMAL_DIG but the source value is exactly representable
397 with DECIMAL_DIG digits, then the result should be an exact representa‐
398 tion with trailing zeros. Otherwise, the source value is bounded by two
399 adjacent decimal strings L < U, both having DECIMAL_DIG significant
400 digits; the value of the resultant decimal string D should satisfy L <=
401 D <= U, with the extra stipulation that the error should have a correct
402 sign for the current rounding direction.
403 The st_ctime and st_mtime fields of the file shall be marked for update
405 between the call to a successful execution of fwprintf() or wprintf()
406 and the next successful completion of a call to fflush() or fclose() on
407 the same stream, or a call to exit() or abort().
408
410 Upon successful completion, these functions shall return the number of
411 wide characters transmitted, excluding the terminating null wide char‐
412 acter in the case of swprintf(), or a negative value if an output error
413 was encountered, and set errno to indicate the error.
414 If n or more wide characters were requested to be written, swprintf()
416 shall return a negative value, and set errno to indicate the error.
417
419 For the conditions under which fwprintf() and wprintf() fail and may
420 fail, refer to fputwc().
421 In addition, all forms of fwprintf() may fail if:
423 EILSEQ A wide-character code that does not correspond to a valid char‐
425 acter has been detected.
426 EINVAL There are insufficient arguments.
428 In addition, wprintf() and fwprintf() may fail if:
431 ENOMEM Insufficient storage space is available.
433 The following sections are informative.
436
438 To print the language-independent date and time format, the following
439 statement could be used:
440 wprintf(format, weekday, month, day, hour, min);
443 For American usage, format could be a pointer to the wide-character
445 string:
446 L"%s, %s %d, %d:%.2d\n"
449 producing the message:
451 Sunday, July 3, 10:02
454 whereas for German usage, format could be a pointer to the wide-charac‐
456 ter string:
457 L"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
460 producing the message:
462 Sonntag, 3. Juli, 10:02
465
467 None.
468
470 None.
471
473 None.
474
476 btowc(), fputwc(), fwscanf(), mbrtowc(), setlocale(), the Base Defini‐
477 tions volume of IEEE Std 1003.1-2001, Chapter 7, Locale, <stdio.h>,
478 <wchar.h>
479
481 Portions of this text are reprinted and reproduced in electronic form
482 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
483 -- Portable Operating System Interface (POSIX), The Open Group Base
484 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
485 Electrical and Electronics Engineers, Inc and The Open Group. In the
486 event of any discrepancy between this version and the original IEEE and
487 The Open Group Standard, the original IEEE and The Open Group Standard
488 is the referee document. The original Standard can be obtained online
489 at http://www.opengroup.org/unix/online.html .
490IEEE/The Open Group 2003 FWPRINTF(3P)