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