1fwprintf(3C) Standard C Library Functions fwprintf(3C)
2
6 fwprintf, wprintf, swprintf - print formatted wide-character output
7
9 #include <stdio.h>
10 #include <wchar.h>
11 int fwprintf(FILE *restrict stream, const wchar_t *restrict format,
13 ...);
14 int wprintf(const wchar_t *restrict format, ...);
17 int swprintf(wchar_t *restrict s, size_t n, const wchar_t *restrict format,
20 ...);
21
24 The fwprintf() function places output on the named output stream. The
25 wprintf() function places output on the standard output stream stdout.
26 The swprintf() function places output followed by the null wide-charac‐
27 ter in consecutive wide-characters starting at *s; no more than n wide-
28 characters are written, including a terminating null wide-character,
29 which is always added (unless n is zero).
30 Each of these functions converts, formats and prints its arguments
33 under control of the format wide-character string. The format is com‐
34 posed of zero or more directives: ordinary wide-characters, which are
35 simply copied to the output stream and conversion specifications, each
36 of which results in the fetching of zero or more arguments. The results
37 are undefined if there are insufficient arguments for the format. If
38 the format is exhausted while arguments remain, the excess arguments
39 are evaluated but are otherwise ignored.
40 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 wide-character % (see below) is replaced by the sequence
45 %n$, where n is a decimal integer in the range [1, NL_ARGMAX], giving
46 the position of the argument in the argument list. This feature pro‐
47 vides for the definition of format wide-character strings that select
48 arguments in an order appropriate to specific languages (see the EXAM‐
49 PLES section).
50 In format wide-character strings containing the %n$ form of conversion
53 specifications, numbered arguments in the argument list can be refer‐
54 enced from the format wide-character string as many times as required.
55 In format wide-character strings containing the % form of conversion
58 specifications, each argument in the argument list is used exactly
59 once.
60 All forms of the fwprintf() functions allow for the insertion of a lan‐
63 guage-dependent radix character in the output string, output as a wide-
64 character value. The radix character is defined in the program's locale
65 (category LC_NUMERIC). In the POSIX locale, or in a locale where the
66 radix character is not defined, the radix character defaults to a
67 period (.).
68 Each conversion specification is introduced by the % wide-character or
71 by the wide-character sequence %n$, after which the following appear in
72 sequence:
73 o Zero or more flags (in any order), which modify the meaning
75 of the conversion specification.
76 o An optional minimum field width. If the converted value has
78 fewer wide-characters than the field width, it will be
79 padded with spaces by default on the left; it will be padded
80 on the right, if the left-adjustment flag (−), described
81 below, is given to the field width. The field width takes
82 the form of an asterisk (*), described below, or a decimal
83 integer.
84 o An optional precision that gives the minimum number of dig‐
86 its to appear for the d, i, o, u, x, and X conversions; the
87 number of digits to appear after the radix character for the
88 a, A, e, E, f, and F conversions; the maximum number of sig‐
89 nificant digits for the g and G conversions; or the maximum
90 number of wide-characters to be printed from a string in s
91 conversions. The precision takes the form of a period (.)
92 followed by either an asterisk (*), described below, or an
93 optional decimal digit string, where a null digit string is
94 treated as 0. If a precision appears with any other conver‐
95 sion wide-character, the behavior is undefined.
96 o An optional length modifier that specifies the size of the
98 argument.
99 o A conversion specifier wide character that indicates the
101 type of conversion to be applied.
102 A field width, or precision, or both, may be indicated by an asterisk
105 (*). In this case an argument of type int supplies the field width or
106 precision. Arguments specifying field width, or precision, or both must
107 appear in that order before the argument, if any, to be converted. A
108 negative field width is taken as a − flag followed by a positive field
109 width. A negative precision is taken as if the precision were omitted.
110 In format wide-character strings containing the %n$ form of a conver‐
111 sion specification, a field width or precision may be indicated by the
112 sequence *m$, where m is a decimal integer in the range [1, NL_ARGMAX]
113 giving the position in the argument list (after the format argument) of
114 an integer argument containing the field width or precision, for exam‐
115 ple:
116 wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);
118 The format can contain either numbered argument specifications (that
122 is, %n$ and *m$), or unnumbered argument specifications (that is, % and
123 *), but normally not both. The only exception to this is that %% can be
124 mixed with the %n$ form. The results of mixing numbered and unnumbered
125 argument specifications in a format wide-character string are unde‐
126 fined. When numbered argument specifications are used, specifying the
127 Nth argument requires that all the leading arguments, from the first to
128 the (N−1)th, are specified in the format wide-character string.
129 The flag wide-characters and their meanings are:
132 ' The integer portion of the result of a decimal conversion (%i,
134 %d, %u, %f, %F, %g, or %G) will be formatted with thousands'
135 grouping wide-characters. For other conversions the behavior
136 is undefined. The non-monetary grouping wide-character is
137 used.
138 − The result of the conversion will be left-justified within the
141 field. The conversion will be right-justified if this flag is
142 not specified.
143 + The result of a signed conversion will always begin with a
146 sign (+ or −). The conversion will begin with a sign only when
147 a negative value is converted if this flag is not specified.
148 space If the first wide-character of a signed conversion is not a
151 sign or if a signed conversion results in no wide-characters,
152 a space will be prefixed to the result. This means that if the
153 space and + flags both appear, the space flag will be ignored.
154 # This flag specifies that the value is to be converted to an
157 alternative form. For o conversion, it increases the precision
158 (if necessary) to force the first digit of the result to be 0.
159 For x or X conversions, a non-zero result will have 0x (or 0X)
160 prefixed to it. For a, A, e, E, f, F, g, or G conversions, the
161 result will always contain a radix character, even if no dig‐
162 its follow it. Without this flag, a radix character appears in
163 the result of these conversions only if a digit follows it.
164 For g and G conversions, trailing zeros will not be removed
165 from the result as they normally are. For other conversions,
166 the behavior is undefined.
167 0 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions,
170 leading zeros (following any indication of sign or base) are
171 used to pad to the field width; no space padding is performed.
172 If the 0 and − flags both appear, the 0 flag will be ignored.
173 For d, i, o, u, x, and X conversions, if a precision is speci‐
174 fied, the 0 flag will be ignored. If the 0 and ' flags both
175 appear, the grouping wide-characters are inserted before zero
176 padding. For other conversions, the behavior is undefined.
177 The length modifiers and their meanings:
181 hh Specifies that a following d, i, o, u, x, or X conver‐
183 sion specifier applies to a signed char or unsigned
184 char argument (the argument will have been promoted
185 according to the integer promotions, but its value
186 shall be converted to signed char or unsigned char
187 before printing); or that a following n conversion
188 specifier applies to a pointer to a signed char argu‐
189 ment.
190 h Specifies that a following d, i, o, u, x, or X conver‐
193 sion specifier applies to a short or unsigned short
194 argument (the argument will have been promoted accord‐
195 ing to the integer promotions, but its value shall be
196 converted to short or unsigned short before printing);
197 or that a following n conversion specifier applies to a
198 pointer to a short argument.
199 l (ell) Specifies that a following d, i, o, u, x, or X conver‐
202 sion specifier applies to a long or unsigned long argu‐
203 ment; that a following n conversion specifier applies
204 to a pointer to a long argument; that a following c
205 conversion specifier applies to a wint_t argument; that
206 a following s conversion specifier applies to a pointer
207 to a wchar_t argument; or has no effect on a following
208 a, A, e, E, f, F, g, or G conversion specifier.
209 ll (ell-ell) Specifies that a following d, i, o, u, x, or X conver‐
212 sion specifier applies to a long long or unsigned long
213 long argument; or that a following n conversion speci‐
214 fier applies to a pointer to a long long argument.
215 j Specifies that a following d, i, o, u, x, or X conver‐
218 sion specifier applies to an intmax_t or uintmax_t
219 argument; or that a following n conversion specifier
220 applies to a pointer to an intmax_t argument.
221 z Specifies that a following d, i, o, u, x, or X conver‐
224 sion specifier applies to a size_t or the corresponding
225 signed integer type argument; or that a following n
226 conversion specifier applies to a pointer to a signed
227 integer type corresponding to size_t argument.
228 t Specifies that a following d, i, o, u, x, or X conver‐
231 sion specifier applies to a ptrdiff_t or the corre‐
232 sponding unsigned type argument; or that a following n
233 conversion specifier applies to a pointer to a
234 ptrdiff_t argument.
235 L Specifies that a following a, A, e, E, f, F, g, or G
238 conversion specifier applies to a long double argument.
239 If a length modifier appears with any conversion specifier other than
243 as specified above, the behavior is undefined.
244 The conversion wide-characters and their meanings are:
247 d, i The int argument is converted to a signed decimal in the style
249 [−]dddd. The precision specifies the minimum number of digits
250 to appear; if the value being converted can be represented in
251 fewer digits, it will be expanded with leading zeros. The
252 default precision is 1. The result of converting 0 with an
253 explicit precision of 0 is no wide-characters.
254 o The unsigned int argument is converted to unsigned octal format
257 in the style dddd. The precision specifies the minimum number
258 of digits to appear; if the value being converted can be repre‐
259 sented in fewer digits, it will be expanded with leading zeros.
260 The default precision is 1. The result of converting 0 with an
261 explicit precision of 0 is no wide-characters.
262 u The unsigned int argument is converted to unsigned decimal for‐
265 mat in the style dddd. The precision specifies the minimum num‐
266 ber of digits to appear; if the value being converted can be
267 represented in fewer digits, it will be expanded with leading
268 zeros. The default precision is 1. The result of converting 0
269 with an explicit precision of 0 is no wide-characters.
270 x The unsigned int argument is converted to unsigned hexadecimal
273 format in the style dddd; the letters abcdef are used. The pre‐
274 cision specifies the minimum number of digits to appear; if the
275 value being converted can be represented in fewer digits, it
276 will be expanded with leading zeros. The default precision is
277 1. The result of converting 0 with an explicit precision of 0
278 is no wide-characters.
279 X Behaves the same as the x conversion wide-character except that
282 letters "ABCDEF" are used instead of "abcdef".
283 f, F The double argument is converted to decimal notation in the
286 style [−]ddd.ddd, where the number of digits after the radix
287 character (see setlocale(3C)) is equal to the precision speci‐
288 fication. If the precision is missing it is taken as 6; if the
289 precision is explicitly 0 and the # flag is not specified, no
290 radix character appears. If a radix character appears, at least
291 1 digit appears before it. The converted value is rounded to
292 fit the specified output format according to the prevailing
293 floating point rounding direction mode. If the conversion is
294 not exact, an inexact exception is raised.
295 For the f specifier, a double argument representing an infinity
297 or NaN is converted in the style of the e conversion specifier,
298 except that for an infinite argument, "infinity" or "Infinity"
299 is printed when the precision is at least 8 and "inf" or "Inf"
300 is printed otherwise.
301 For the F specifier, a double argument representing an infinity
303 or NaN is converted in the SUSv3 style of the E conversion
304 specifier, except that for an infinite argument, "INFINITY" is
305 printed when the precision is at least 8 and or "INF" is
306 printed otherwise.
307 e, E The double argument is converted in the style [−]d.ddde±dd,
310 where there is one digit before the radix character (which is
311 non-zero if the argument is non-zero) and the number of digits
312 after it is equal to the precision; if the precision is miss‐
313 ing, it is taken as 6; if the precision is 0 and no # flag is
314 present, no radix character appears. The converted value is
315 rounded to fit the specified output format according to the
316 prevailing floating point rounding direction mode. If the con‐
317 version is not exact, an inexact exception is raised. The E
318 conversion wide-character will produce a number with E instead
319 of e introducing the exponent. The exponent always contains at
320 least two digits. If the value is 0, the exponent is 0.
321 Infinity and NaN values are handled in one of the following
323 ways:
324 SUSv3 For the e specifier, a double argument representing
326 an infinity is printed as "[−]infinity", when the
327 precision for the conversion is at least 7 and as
328 "[−]inf" otherwise. A double argument representing a
329 NaN is printed as "[−]nan". For the E specifier,
330 "INF", "INFINITY", and "NAN" are printed instead of
331 "inf", "infinity", and "nan", respectively. Printing
332 of the sign follows the rules described above.
333 Default A double argument representing an infinity is
336 printed as "[−]Infinity", when the precision for the
337 conversion is at least 7 and as "[−]Inf" otherwise.
338 A double argument representing a NaN is printed as
339 "[−]NaN". Printing of the sign follows the rules
340 described above.
341 g, G The double argument is converted in the style f or e (or in the
345 style E in the case of a G conversion wide-character), with the
346 precision specifying the number of significant digits. If an
347 explicit precision is 0, it is taken as 1. The style used
348 depends on the value converted; style e (or E ) will be used
349 only if the exponent resulting from such a conversion is less
350 than −4 or greater than or equal to the precision. Trailing
351 zeros are removed from the fractional portion of the result; a
352 radix character appears only if it is followed by a digit.
353 A double argument representing an infinity or NaN is converted
355 in the style of the e or E conversion specifier, except that
356 for an infinite argument, "infinity", "INFINITY", or "Infinity"
357 is printed when the precision is at least 8 and "inf", "INF",
358 or "Inf" is printed otherwise.
359 a, A A double argument representing a floating-point number is con‐
362 verted in the style "[-]0xh.hhhhp±d", where the single hexadec‐
363 imal digit preceding the radix point is 0 if the value con‐
364 verted is zero and 1 otherwise and the number of hexadecimal
365 digits after it are equal to the precision; if the precision is
366 missing, the number of digits printed after the radix point is
367 13 for the conversion of a double value, 16 for the conversion
368 of a long double value on x86, and 28 for the conversion of a
369 long double value on SPARC; if the precision is zero and the
370 '#' flag is not specified, no decimal-point wide character
371 appears. The letters "abcdef" are used for a conversion and the
372 letters "ABCDEF" for A conversion. The A conversion specifier
373 produces a number with 'X' and 'P' instead of 'x' and 'p'. The
374 exponent always contains at least one digit, and only as many
375 more digits as necessary to represent the decimal exponent of
376 2. If the value is zero, the exponent is zero.
377 The converted valueis rounded to fit the specified output for‐
379 mat according to the prevailing floating point rounding direc‐
380 tion mode. If the conversion is not exact, an inexact exception
381 is raised.
382 A double argument representing an infinity or NaN is converted
384 in the SUSv3 style of an e or E conversion specifier.
385 c If no l (ell) qualifier is present, the int argument is con‐
388 verted to a wide-character as if by calling the btowc(3C) func‐
389 tion and the resulting wide-character is written. Otherwise the
390 wint_t argument is converted to wchar_t, and written.
391 s If no l (ell) qualifier is present, the argument must be a
394 pointer to a character array containing a character sequence
395 beginning in the initial shift state. Characters from the array
396 are converted as if by repeated calls to the mbrtowc(3C) func‐
397 tion, with the conversion state described by an mbstate_t
398 object initialized to zero before the first character is con‐
399 verted, and written up to (but not including) the terminating
400 null wide-character. If the precision is specified, no more
401 than that many wide-characters are written. If the precision is
402 not specified or is greater than the size of the array, the
403 array must contain a null wide-character.
404 If an l (ell) qualifier is present, the argument must be a
406 pointer to an array of type wchar_t. Wide characters from the
407 array are written up to (but not including) a terminating null
408 wide-character. If no precision is specified or is greater than
409 the size of the array, the array must contain a null wide-char‐
410 acter. If a precision is specified, no more than that many
411 wide-characters are written.
412 p The argument must be a pointer to void. The value of the
415 pointer is converted to a sequence of printable wide-charac‐
416 ters.
417 n The argument must be a pointer to an integer into which is
420 written the number of wide-characters written to the output so
421 far by this call to one of the fwprintf() functions. No argu‐
422 ment is converted.
423 C Same as lc.
426 S Same as ls.
429 % Output a % wide-character; no argument is converted. The entire
432 conversion specification must be %%.
433 If a conversion specification does not match one of the above forms,
437 the behavior is undefined.
438 In no case does a non-existent or small field width cause truncation of
441 a field; if the result of a conversion is wider than the field width,
442 the field is simply expanded to contain the conversion result. Charac‐
443 ters generated by fwprintf() and wprintf() are printed as if fputwc(3C)
444 had been called.
445 The st_ctime and st_mtime fields of the file will be marked for update
448 between the call to a successful execution of fwprintf() or wprintf()
449 and the next successful completion of a call to fflush(3C) or
450 fclose(3C) on the same stream or a call to exit(3C) or abort(3C).
451
453 Upon successful completion, these functions return the number of wide-
454 characters transmitted excluding the terminating null wide-character in
455 the case of swprintf() or a negative value if an output error was
456 encountered.
457 If n or more wide characters were requested to be written, swprintf()
460 returns a negative value.
461
463 For the conditions under which fwprintf() and wprintf() will fail and
464 may fail, refer to fputwc(3C).
465 In addition, all forms of fwprintf() may fail if:
468 EILSEQ A wide-character code that does not correspond to a valid
470 character has been detected.
471 EINVAL There are insufficient arguments.
474 In addition, wprintf() and fwprintf() may fail if:
478 ENOMEM Insufficient storage space is available.
480
483 Example 1 Print Language-dependent Date and Time Format.
484 To print the language-independent date and time format, the following
487 statement could be used:
488 wprintf(format, weekday, month, day, hour, min);
491 For American usage, format could be a pointer to the wide-character
495 string:
496 L"%s, %s %d, %d:%.2d\n"
499 producing the message:
503 Sunday, July 3, 10:02
506 whereas for German usage, format could be a pointer to the wide-charac‐
510 ter string:
511 L"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
514 producing the message:
518 Sonntag, 3. Juli, 10:02
521
524 See attributes(5) for descriptions of the following attributes:
525 ┌─────────────────────────────┬─────────────────────────────┐
530 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
531 ├─────────────────────────────┼─────────────────────────────┤
532 │Interface Stability │Standard │
533 ├─────────────────────────────┼─────────────────────────────┤
534 │MT-Level │MT-Safe with exceptions │
535 └─────────────────────────────┴─────────────────────────────┘
536
538 btowc(3C), fputwc(3C), fwscanf(3C), mbrtowc(3C), setlocale(3C),
539 attributes(5), standards(5)
540
542 The fwprintf(), wprintf(), and swprintf() functions can be used safely
543 in multithreaded applications, as long as setlocale(3C) is not being
544 called to change the locale.
545 If the j length modifier is used, 32-bit applications that were com‐
548 piled using c89 on releases prior to Solaris 10 will experience unde‐
549 fined behavior.
550SunOS 5.11 1 Nov 2003 fwprintf(3C)