1WPRINTF(3) Linux Programmer's Manual WPRINTF(3)
2
6 wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf - formatted
7 wide-character output conversion
8
10 #include <stdio.h>
11 #include <wchar.h>
12 int wprintf(const wchar_t *format, ...);
14 int fwprintf(FILE *stream, const wchar_t *format, ...);
15 int swprintf(wchar_t *wcs, size_t maxlen,
16 const wchar_t *format, ...);
17 int vwprintf(const wchar_t *format, va_list args);
19 int vfwprintf(FILE *stream, const wchar_t *format, va_list args);
20 int vswprintf(wchar_t *wcs, size_t maxlen,
21 const wchar_t *format, va_list args);
22 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
24 All functions shown above:
26 _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE ||
27 _POSIX_C_SOURCE >= 200112L
28
30 The wprintf() family of functions is the wide-character equivalent of
31 the printf(3) family of functions. It performs formatted output of
32 wide characters.
33 The wprintf() and vwprintf() functions perform wide-character output to
35 stdout. stdout must not be byte oriented; see fwide(3) for more infor‐
36 mation.
37 The fwprintf() and vfwprintf() functions perform wide-character output
39 to stream. stream must not be byte oriented; see fwide(3) for more
40 information.
41 The swprintf() and vswprintf() functions perform wide-character output
43 to an array of wide characters. The programmer must ensure that there
44 is room for at least maxlen wide characters at wcs.
45 These functions are like the printf(3), vprintf(3), fprintf(3),
47 vfprintf(3), sprintf(3), vsprintf(3) functions except for the following
48 differences:
49 · The format string is a wide-character string.
51 · The output consists of wide characters, not bytes.
53 · swprintf() and vswprintf() take a maxlen argument, sprintf(3)
55 and vsprintf(3) do not. (snprintf(3) and vsnprintf(3) take a
56 maxlen argument, but these functions do not return -1 upon buf‐
57 fer overflow on Linux.)
58 The treatment of the conversion characters c and s is different:
60 c If no l modifier is present, the int argument is converted to a
62 wide character by a call to the btowc(3) function, and the
63 resulting wide character is written. If an l modifier is
64 present, the wint_t (wide character) argument is written.
65 s If no l modifier is present: the const char * argument is
67 expected to be a pointer to an array of character type (pointer
68 to a string) containing a multibyte character sequence beginning
69 in the initial shift state. Characters from the array are con‐
70 verted to wide characters (each by a call to the mbrtowc(3)
71 function with a conversion state starting in the initial state
72 before the first byte). The resulting wide characters are writ‐
73 ten up to (but not including) the terminating null wide charac‐
74 ter (L'\0'). If a precision is specified, no more wide charac‐
75 ters than the number specified are written. Note that the pre‐
76 cision determines the number of wide characters written, not the
77 number of bytes or screen positions. The array must contain a
78 terminating null byte ('\0'), unless a precision is given and it
79 is so small that the number of converted wide characters reaches
80 it before the end of the array is reached. If an l modifier is
81 present: the const wchar_t * argument is expected to be a
82 pointer to an array of wide characters. Wide characters from
83 the array are written up to (but not including) a terminating
84 null wide character. If a precision is specified, no more than
85 the number specified are written. The array must contain a ter‐
86 minating null wide character, unless a precision is given and it
87 is smaller than or equal to the number of wide characters in the
88 array.
89
91 The functions return the number of wide characters written, excluding
92 the terminating null wide character in case of the functions swprintf()
93 and vswprintf(). They return -1 when an error occurs.
94
96 For an explanation of the terms used in this section, see
97 attributes(7).
98 ┌─────────────────────────┬───────────────┬────────────────┐
100 │Interface │ Attribute │ Value │
101 ├─────────────────────────┼───────────────┼────────────────┤
102 │wprintf(), fwprintf(), │ Thread safety │ MT-Safe locale │
103 │swprintf(), vwprintf(), │ │ │
104 │vfwprintf(), vswprintf() │ │ │
105 └─────────────────────────┴───────────────┴────────────────┘
106
108 POSIX.1-2001, POSIX.1-2008, C99.
109
111 The behavior of wprintf() et al. depends on the LC_CTYPE category of
112 the current locale.
113 If the format string contains non-ASCII wide characters, the program
115 will work correctly only if the LC_CTYPE category of the current locale
116 at run time is the same as the LC_CTYPE category of the current locale
117 at compile time. This is because the wchar_t representation is plat‐
118 form- and locale-dependent. (The glibc represents wide characters
119 using their Unicode (ISO-10646) code point, but other platforms don't
120 do this. Also, the use of C99 universal character names of the form
121 \unnnn does not solve this problem.) Therefore, in internationalized
122 programs, the format string should consist of ASCII wide characters
123 only, or should be constructed at run time in an internationalized way
124 (e.g., using gettext(3) or iconv(3), followed by mbstowcs(3)).
125
127 fprintf(3), fputwc(3), fwide(3), printf(3), snprintf(3)
128
130 This page is part of release 5.04 of the Linux man-pages project. A
131 description of the project, information about reporting bugs, and the
132 latest version of this page, can be found at
133 https://www.kernel.org/doc/man-pages/.
134GNU 2019-03-06 WPRINTF(3)