1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
10 .\" References consulted:
11 .\" GNU glibc-2 source code and manual
12 .\" Dinkumware C library reference http://www.dinkumware.com/
13 .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
16 .TH WPRINTF 3 2021-03-22 "GNU" "Linux Programmer's Manual"
18 wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
19 wide-character output conversion
25 .BI "int wprintf(const wchar_t *restrict " format ", ...);"
26 .BI "int fwprintf(FILE *restrict " stream ,
27 .BI " const wchar_t *restrict " format ", ...);"
28 .BI "int swprintf(wchar_t *restrict " wcs ", size_t " maxlen ,
29 .BI " const wchar_t *restrict " format ", ...);"
31 .BI "int vwprintf(const wchar_t *restrict " format ", va_list " args );
32 .BI "int vfwprintf(FILE *restrict " stream ,
33 .BI " const wchar_t *restrict " format ", va_list " args );
34 .BI "int vswprintf(wchar_t *restrict " wcs ", size_t " maxlen ,
35 .BI " const wchar_t *restrict " format ", va_list " args );
39 Feature Test Macro Requirements for glibc (see
40 .BR feature_test_macros (7)):
43 All functions shown above:
51 _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
52 || _POSIX_C_SOURCE >= 200112L
57 family of functions is
58 the wide-character equivalent of the
61 It performs formatted output of wide
69 perform wide-character output to
72 must not be byte oriented; see
81 perform wide-character output to
84 must not be byte oriented; see
93 perform wide-character output
94 to an array of wide characters.
95 The programmer must ensure that there is
102 These functions are like
110 functions except for the
111 following differences:
116 string is a wide-character string.
119 The output consists of wide characters, not bytes.
137 argument, but these functions do not return \-1 upon
138 buffer overflow on Linux.)
140 The treatment of the conversion characters
149 modifier is present, the
151 argument is converted to a wide character by a call to the
153 function, and the resulting wide character is written.
156 modifier is present, the
158 (wide character) argument is written.
163 modifier is present: the
165 argument is expected to be a pointer to an array of character type
166 (pointer to a string) containing a multibyte character sequence beginning
167 in the initial shift state.
168 Characters from the array are converted to
169 wide characters (each by a call to the
171 function with a conversion state starting in the initial state before
173 The resulting wide characters are written up to
174 (but not including) the terminating null wide character (L\(aq\e0\(aq).
176 specified, no more wide characters than the number specified are written.
177 Note that the precision determines the number of
179 written, not the number of
182 .IR "screen positions" .
183 The array must contain a terminating null byte (\(aq\e0\(aq),
184 unless a precision is given
185 and it is so small that the number of converted wide characters reaches it
186 before the end of the array is reached.
189 modifier is present: the
190 .I "const\ wchar_t\ *"
191 argument is expected to be a pointer to an array of wide characters.
192 Wide characters from the array are written up to (but not including) a
193 terminating null wide character.
194 If a precision is specified, no more than
195 the number specified are written.
196 The array must contain a terminating null
197 wide character, unless a precision is given and it is smaller than or equal
198 to the number of wide characters in the array.
200 The functions return the number of wide characters written, excluding the
201 terminating null wide character in
202 case of the functions
206 They return \-1 when an error occurs.
208 For an explanation of the terms used in this section, see
216 Interface Attribute Value
224 T} Thread safety MT-Safe locale
230 POSIX.1-2001, POSIX.1-2008, C99.
242 string contains non-ASCII wide characters, the program
243 will work correctly only if the
245 category of the current locale at
246 run time is the same as the
248 category of the current locale at
252 representation is platform- and locale-dependent.
253 (The glibc represents
254 wide characters using their Unicode (ISO-10646) code point, but other
255 platforms don't do this.
256 Also, the use of C99 universal character names
257 of the form \eunnnn does not solve this problem.)
259 internationalized programs, the
261 string should consist of ASCII
262 wide characters only, or should be constructed at run time in an
263 internationalized way (e.g., using