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
13 fwprintf, swprintf, wprintf — print formatted wide-character output
14
16 #include <stdio.h>
17 #include <wchar.h>
18 int fwprintf(FILE *restrict stream, const wchar_t *restrict format, ...);
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
25 The functionality described on this reference page is aligned with the
26 ISO C standard. Any conflict between the requirements described here
27 and the ISO C standard is unintentional. This volume of POSIX.1‐2008
28 defers to the ISO C standard.
29 The fwprintf() function shall place output on the named output stream.
31 The wprintf() function shall place output on the standard output stream
32 stdout. The swprintf() function shall place output followed by the
33 null wide character in consecutive wide characters starting at *ws; no
34 more than n wide characters shall be written, including a terminating
35 null wide character, which is always added (unless n is zero).
36 Each of these functions shall convert, format, and print its arguments
38 under control of the format wide-character string. The format is com‐
39 posed of zero or more directives: ordinary wide-characters, which are
40 simply copied to the output stream, and conversion specifications, each
41 of which results in the fetching of zero or more arguments. The results
42 are undefined if there are insufficient arguments for the format. If
43 the format is exhausted while arguments remain, the excess arguments
44 are evaluated but are otherwise ignored.
45 Conversions can be applied to the nth argument after the format in the
47 argument list, rather than to the next unused argument. In this case,
48 the conversion specifier wide character % (see below) is replaced by
49 the sequence "%n$", where n is a decimal integer in the range
50 [1,{NL_ARGMAX}], giving the position of the argument in the argument
51 list. This feature provides for the definition of format wide-character
52 strings that select arguments in an order appropriate to specific lan‐
53 guages (see the EXAMPLES section).
54 The format can contain either numbered argument specifications (that
56 is, "%n$" and "*m$"), or unnumbered argument conversion specifications
57 (that is, % and *), but not both. The only exception to this is that %%
58 can be mixed with the "%n$" form. The results of mixing numbered and
59 unnumbered argument specifications in a format wide-character string
60 are undefined. When numbered argument specifications are used, specify‐
61 ing the Nth argument requires that all the leading arguments, from the
62 first to the (N−1)th, are specified in the format wide-character
63 string.
64 In format wide-character strings containing the "%n$" form of conver‐
66 sion specification, numbered arguments in the argument list can be ref‐
67 erenced from the format wide-character string as many times as
68 required.
69 In format wide-character strings containing the % form of conversion
71 specification, each argument in the argument list shall be used exactly
72 once.
73 All forms of the fwprintf() function allow for the insertion of a
75 locale-dependent radix character in the output string, output as a
76 wide-character value. The radix character is defined in the current
77 locale (category LC_NUMERIC). In the POSIX locale, or in a locale
78 where the radix character is not defined, the radix character shall
79 default to a <period> ('.').
80 Each conversion specification is introduced by the '%' wide character
82 or by the wide-character sequence "%n$", after which the following
83 appear in sequence:
84 * Zero or more flags (in any order), which modify the meaning of the
86 conversion specification.
87 * An optional minimum field width. If the converted value has fewer
89 wide characters than the field width, it shall be padded with
90 <space> characters by default on the left; it shall be padded on
91 the right, if the left-adjustment flag ('−'), described below, is
92 given to the field width. The field width takes the form of an
93 <asterisk> ('*'), described below, or a decimal integer.
94 * An optional precision that gives the minimum number of digits to
96 appear for the d, i, o, u, x, and X conversion specifiers; the num‐
97 ber of digits to appear after the radix character for the a, A, e,
98 E, f, and F conversion specifiers; the maximum number of signifi‐
99 cant digits for the g and G conversion specifiers; or the maximum
100 number of wide characters to be printed from a string in the s con‐
101 version specifiers. The precision takes the form of a <period>
102 ('.') followed either by an <asterisk> ('*'), described below, or
103 an optional decimal digit string, where a null digit string is
104 treated as 0. If a precision appears with any other conversion wide
105 character, the behavior is undefined.
106 * An optional length modifier that specifies the size of the argu‐
108 ment.
109 * A conversion specifier wide character that indicates the type of
111 conversion to be applied.
112 A field width, or precision, or both, may be indicated by an <asterisk>
114 ('*'). In this case an argument of type int supplies the field width
115 or precision. Applications shall ensure that arguments specifying field
116 width, or precision, or both appear in that order before the argument,
117 if any, to be converted. A negative field width is taken as a '−' flag
118 followed by a positive field width. A negative precision is taken as if
119 the precision were omitted. In format wide-character strings contain‐
120 ing the "%n$" form of a conversion specification, a field width or pre‐
121 cision may be indicated by the sequence "*m$", where m is a decimal
122 integer in the range [1,{NL_ARGMAX}] giving the position in the argu‐
123 ment list (after the format argument) of an integer argument containing
124 the field width or precision, for example:
125 wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);
127 The flag wide characters and their meanings are:
129 ' (The <apostrophe>.) The integer portion of the result of a
131 decimal conversion (%i, %d, %u, %f, %F, %g, or %G) shall be
132 formatted with thousands' grouping wide characters. For other
133 conversions, the behavior is undefined. The numeric grouping
134 wide character is used.
135 − The result of the conversion shall be left-justified within the
137 field. The conversion shall be right-justified if this flag is
138 not specified.
139 + The result of a signed conversion shall always begin with a
141 sign ('+' or '−'). The conversion shall begin with a sign only
142 when a negative value is converted if this flag is not speci‐
143 fied.
144 <space> If the first wide character of a signed conversion is not a
146 sign, or if a signed conversion results in no wide characters,
147 a <space> shall be prefixed to the result. This means that if
148 the <space> and '+' flags both appear, the <space> flag shall
149 be ignored.
150 # Specifies that the value is to be converted to an alternative
152 form. For o conversion, it increases the precision (if neces‐
153 sary) to force the first digit of the result to be 0. For x or
154 X conversion specifiers, a non-zero result shall have 0x (or
155 0X) prefixed to it. For a, A, e, E, f, F, g, and G conversion
156 specifiers, the result shall always contain a radix character,
157 even if no digits follow it. Without this flag, a radix charac‐
158 ter appears in the result of these conversions only if a digit
159 follows it. For g and G conversion specifiers, trailing zeros
160 shall not be removed from the result as they normally are. For
161 other conversion specifiers, the behavior is undefined.
162 0 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversion
164 specifiers, leading zeros (following any indication of sign or
165 base) are used to pad to the field width rather than performing
166 space padding, except when converting an infinity or NaN. If
167 the '0' and '−' flags both appear, the '0' flag shall be
168 ignored. For d, i, o, u, x, and X conversion specifiers, if a
169 precision is specified, the '0' flag shall be ignored. If the
170 '0' and <apostrophe> flags both appear, the grouping wide char‐
171 acters are inserted before zero padding. For other conversions,
172 the behavior is undefined.
173 The length modifiers and their meanings are:
175 hh Specifies that a following d, i, o, u, x, or X conversion spec‐
177 ifier applies to a signed char or unsigned char argument (the
178 argument will have been promoted according to the integer pro‐
179 motions, but its value shall be converted to signed char or
180 unsigned char before printing); or that a following n conver‐
181 sion specifier applies to a pointer to a signed char argument.
182 h Specifies that a following d, i, o, u, x, or X conversion spec‐
184 ifier applies to a short or unsigned short argument (the argu‐
185 ment will have been promoted according to the integer promo‐
186 tions, but its value shall be converted to short or unsigned
187 short before printing); or that a following n conversion speci‐
188 fier applies to a pointer to a short argument.
189 l (ell) Specifies that a following d, i, o, u, x, or X conversion spec‐
191 ifier applies to a long or unsigned long argument; that a fol‐
192 lowing n conversion specifier applies to a pointer to a long
193 argument; that a following c conversion specifier applies to a
194 wint_t argument; that a following s conversion specifier
195 applies to a pointer to a wchar_t argument; or has no effect on
196 a following a, A, e, E, f, F, g, or G conversion specifier.
197 ll (ell-ell)
199 Specifies that a following d, i, o, u, x, or X conversion spec‐
200 ifier applies to a long long or unsigned long long argument; or
201 that a following n conversion specifier applies to a pointer to
202 a long long argument.
203 j Specifies that a following d, i, o, u, x, or X conversion spec‐
205 ifier applies to an intmax_t or uintmax_t argument; or that a
206 following n conversion specifier applies to a pointer to an
207 intmax_t argument.
208 z Specifies that a following d, i, o, u, x, or X conversion spec‐
210 ifier applies to a size_t or the corresponding signed integer
211 type argument; or that a following n conversion specifier
212 applies to a pointer to a signed integer type corresponding to
213 a size_t argument.
214 t Specifies that a following d, i, o, u, x, or X conversion spec‐
216 ifier applies to a ptrdiff_t or the corresponding unsigned type
217 argument; or that a following n conversion specifier applies to
218 a pointer to a ptrdiff_t argument.
219 L Specifies that a following a, A, e, E, f, F, g, or G conversion
221 specifier applies to a long double argument.
222 If a length modifier appears with any conversion specifier other than
224 as specified above, the behavior is undefined.
225 The conversion specifiers and their meanings are:
227 d, i The int argument shall be converted to a signed decimal in the
229 style "[−]dddd". The precision specifies the minimum number of
230 digits to appear; if the value being converted can be repre‐
231 sented in fewer digits, it shall be expanded with leading
232 zeros. The default precision shall be 1. The result of convert‐
233 ing zero with an explicit precision of zero shall be no wide
234 characters.
235 o The unsigned argument shall be converted to unsigned octal for‐
237 mat in the style "dddd". The precision specifies the minimum
238 number of digits to appear; if the value being converted can be
239 represented in fewer digits, it shall be expanded with leading
240 zeros. The default precision shall be 1. The result of convert‐
241 ing zero with an explicit precision of zero shall be no wide
242 characters.
243 u The unsigned argument shall be converted to unsigned decimal
245 format in the style "dddd". The precision specifies the mini‐
246 mum number of digits to appear; if the value being converted
247 can be represented in fewer digits, it shall be expanded with
248 leading zeros. The default precision shall be 1. The result of
249 converting zero with an explicit precision of zero shall be no
250 wide characters.
251 x The unsigned argument shall be converted to unsigned hexadeci‐
253 mal format in the style "dddd"; the letters "abcdef" are used.
254 The precision specifies the minimum number of digits to appear;
255 if the value being converted can be represented in fewer dig‐
256 its, it shall be expanded with leading zeros. The default pre‐
257 cision shall be 1. The result of converting zero with an
258 explicit precision of zero shall be no wide characters.
259 X Equivalent to the x conversion specifier, except that letters
261 "ABCDEF" are used instead of "abcdef".
262 f, F The double argument shall be converted to decimal notation in
264 the style "[−]ddd.ddd", where the number of digits after the
265 radix character shall be equal to the precision specification.
266 If the precision is missing, it shall be taken as 6; if the
267 precision is explicitly zero and no '#' flag is present, no
268 radix character shall appear. If a radix character appears, at
269 least one digit shall appear before it. The value shall be
270 rounded in an implementation-defined manner to the appropriate
271 number of digits.
272 A double argument representing an infinity shall be converted
274 in one of the styles "[−]inf" or "[−]infinity"; which style is
275 implementation-defined. A double argument representing a NaN
276 shall be converted in one of the styles "[−]nan" or "[−]nan(n-
277 char-sequence)"; which style, and the meaning of any n-char-
278 sequence, is implementation-defined. The F conversion specifier
279 produces "INF", "INFINITY", or "NAN" instead of "inf", "infin‐
280 ity", or "nan", respectively.
281 e, E The double argument shall be converted in the style
283 "[−]d.ddde±dd", where there shall be one digit before the radix
284 character (which is non-zero if the argument is non-zero) and
285 the number of digits after it shall be equal to the precision;
286 if the precision is missing, it shall be taken as 6; if the
287 precision is zero and no '#' flag is present, no radix charac‐
288 ter shall appear. The value shall be rounded in an implementa‐
289 tion-defined manner to the appropriate number of digits. The E
290 conversion wide character shall produce a number with 'E'
291 instead of 'e' introducing the exponent. The exponent shall
292 always contain at least two digits. If the value is zero, the
293 exponent shall be zero.
294 A double argument representing an infinity or NaN shall be con‐
296 verted in the style of an f or F conversion specifier.
297 g, G The double argument representing a floating-point number shall
299 be converted in the style f or e (or in the style F or E in the
300 case of a G conversion specifier), depending on the value con‐
301 verted and the precision. Let P equal the precision if non-
302 zero, 6 if the precision is omitted, or 1 if the precision is
303 zero. Then, if a conversion with style E would have an exponent
304 of X:
305 -- If P>X≥−4, the conversion shall be with style f (or F) and
307 precision P−(X+1).
308 -- Otherwise, the conversion shall be with style e (or E) and
310 precision P−1.
311 Finally, unless the '#' flag is used, any trailing zeros shall
313 be removed from the fractional portion of the result and the
314 decimal-point character shall be removed if there is no frac‐
315 tional portion remaining.
316 A double argument representing an infinity or NaN shall be con‐
318 verted in the style of an f or F conversion specifier.
319 a, A A double argument representing a floating-point number shall be
321 converted in the style "[−]0xh.hhhhp±d", where there shall be
322 one hexadecimal digit (which is non-zero if the argument is a
323 normalized floating-point number and is otherwise unspecified)
324 before the decimal-point wide character and the number of hexa‐
325 decimal digits after it shall be equal to the precision; if the
326 precision is missing and FLT_RADIX is a power of 2, then the
327 precision shall be sufficient for an exact representation of
328 the value; if the precision is missing and FLT_RADIX is not a
329 power of 2, then the precision shall be sufficient to distin‐
330 guish values of type double, except that trailing zeros may be
331 omitted; if the precision is zero and the '#' flag is not spec‐
332 ified, no decimal-point wide character shall appear. The let‐
333 ters "abcdef" are used for a conversion and the letters
334 "ABCDEF" for A conversion. The A conversion specifier produces
335 a number with 'X' and 'P' instead of 'x' and 'p'. The exponent
336 shall always contain at least one digit, and only as many more
337 digits as necessary to represent the decimal exponent of 2. If
338 the value is zero, the exponent shall be zero.
339 A double argument representing an infinity or NaN shall be con‐
341 verted in the style of an f or F conversion specifier.
342 c If no l (ell) qualifier is present, the int argument shall be
344 converted to a wide character as if by calling the btowc()
345 function and the resulting wide character shall be written.
346 Otherwise, the wint_t argument shall be converted to wchar_t,
347 and written.
348 s If no l (ell) qualifier is present, the application shall
350 ensure that the argument is a pointer to a character array con‐
351 taining a character sequence beginning in the initial shift
352 state. Characters from the array shall be converted as if by
353 repeated calls to the mbrtowc() function, with the conversion
354 state described by an mbstate_t object initialized to zero
355 before the first character is converted, and written up to (but
356 not including) the terminating null wide character. If the
357 precision is specified, no more than that many wide characters
358 shall be written. If the precision is not specified, or is
359 greater than the size of the array, the application shall
360 ensure that the array contains a null wide character.
361 If an l (ell) qualifier is present, the application shall
363 ensure that the argument is a pointer to an array of type
364 wchar_t. Wide characters from the array shall be written up to
365 (but not including) a terminating null wide character. If no
366 precision is specified, or is greater than the size of the
367 array, the application shall ensure that the array contains a
368 null wide character. If a precision is specified, no more than
369 that many wide characters shall be written.
370 p The application shall ensure that the argument is a pointer to
372 void. The value of the pointer shall be converted to a
373 sequence of printable wide characters in an implementation-
374 defined manner.
375 n The application shall ensure that the argument is a pointer to
377 an integer into which is written the number of wide characters
378 written to the output so far by this call to one of the
379 fwprintf() functions. No argument shall be converted, but one
380 shall be consumed. If the conversion specification includes
381 any flags, a field width, or a precision, the behavior is unde‐
382 fined.
383 C Equivalent to lc.
385 S Equivalent to ls.
387 % Output a '%' wide character; no argument shall be converted.
389 The entire conversion specification shall be %%.
390 If a conversion specification does not match one of the above forms,
392 the behavior is undefined.
393 In no case does a nonexistent or small field width cause truncation of
395 a field; if the result of a conversion is wider than the field width,
396 the field shall be expanded to contain the conversion result. Charac‐
397 ters generated by fwprintf() and wprintf() shall be printed as if
398 fputwc() had been called.
399 For a and A conversions, if FLT_RADIX is not a power of 2 and the
401 result is not exactly representable in the given precision, the result
402 should be one of the two adjacent numbers in hexadecimal floating style
403 with the given precision, with the extra stipulation that the error
404 should have a correct sign for the current rounding direction.
405 For e, E, f, F, g, and G conversion specifiers, if the number of sig‐
407 nificant decimal digits is at most DECIMAL_DIG, then the result should
408 be correctly rounded. If the number of significant decimal digits is
409 more than DECIMAL_DIG but the source value is exactly representable
410 with DECIMAL_DIG digits, then the result should be an exact representa‐
411 tion with trailing zeros. Otherwise, the source value is bounded by
412 two adjacent decimal strings L < U, both having DECIMAL_DIG significant
413 digits; the value of the resultant decimal string D should satisfy L <=
414 D <= U, with the extra stipulation that the error should have a correct
415 sign for the current rounding direction.
416 The last data modification and last file status change timestamps of
418 the file shall be marked for update between the call to a successful
419 execution of fwprintf() or wprintf() and the next successful completion
420 of a call to fflush() or fclose() on the same stream, or a call to
421 exit() or abort().
422
424 Upon successful completion, these functions shall return the number of
425 wide characters transmitted, excluding the terminating null wide char‐
426 acter in the case of swprintf(), or a negative value if an output error
427 was encountered, and set errno to indicate the error.
428 If n or more wide characters were requested to be written, swprintf()
430 shall return a negative value, and set errno to indicate the error.
431
433 For the conditions under which fwprintf() and wprintf() fail and may
434 fail, refer to fputwc().
435 In addition, all forms of fwprintf() shall fail if:
437 EILSEQ A wide-character code that does not correspond to a valid char‐
439 acter has been detected.
440 In addition, all forms of fwprintf() may fail if:
442 EINVAL There are insufficient arguments.
444 In addition, fwprintf() and wprintf() may fail if:
446 ENOMEM Insufficient storage space is available.
448 The swprintf() shall fail if:
450 EOVERFLOW
452 The value of n is greater than {INT_MAX} or the number of bytes
453 needed to hold the output excluding the terminating null is
454 greater than {INT_MAX}.
455 The following sections are informative.
457
459 To print the language-independent date and time format, the following
460 statement could be used:
461 wprintf(format, weekday, month, day, hour, min);
463 For American usage, format could be a pointer to the wide-character
465 string:
466 L"%s, %s %d, %d:%.2d\n"
468 producing the message:
470 Sunday, July 3, 10:02
472 whereas for German usage, format could be a pointer to the wide-charac‐
474 ter string:
475 L"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
477 producing the message:
479 Sonntag, 3. Juli, 10:02
481
483 None.
484
486 None.
487
489 None.
490
492 Section 2.5, Standard I/O Streams, btowc(), fputwc(), fwscanf(), mbr‐
493 towc(), setlocale()
494 The Base Definitions volume of POSIX.1‐2008, Chapter 7, Locale,
496 <stdio.h>, <wchar.h>
497
499 Portions of this text are reprinted and reproduced in electronic form
500 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
501 -- Portable Operating System Interface (POSIX), The Open Group Base
502 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
503 cal and Electronics Engineers, Inc and The Open Group. (This is
504 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
505 event of any discrepancy between this version and the original IEEE and
506 The Open Group Standard, the original IEEE and The Open Group Standard
507 is the referee document. The original Standard can be obtained online
508 at http://www.unix.org/online.html .
509 Any typographical or formatting errors that appear in this page are
511 most likely to have been introduced during the conversion of the source
512 files to man page format. To report such errors, see https://www.ker‐
513 nel.org/doc/man-pages/reporting_bugs.html .
514IEEE/The Open Group 2013 FWPRINTF(3P)