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 2011-09-17 "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 *" format ", ...);"
26 .BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);"
27 .BI "int swprintf(wchar_t *" wcs ", size_t " maxlen ,
28 .BI " const wchar_t *" format ", ...);"
30 .BI "int vwprintf(const wchar_t *" format ", va_list " args );
31 .BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args );
32 .BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen ,
33 .BI " const wchar_t *" format ", va_list " args );
37 Feature Test Macro Requirements for glibc (see
38 .BR feature_test_macros (7)):
42 All functions shown above:
50 _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
52 _ISOC95_SOURCE /* Since glibc 2.12 */ ||
54 _POSIX_C_SOURCE\ >=\ 200112L;
63 family of functions is
64 the wide-character equivalent of the
67 It performs formatted output of wide
75 perform wide-character output to \fIstdout\fP.
76 \fIstdout\fP must not be byte oriented; see
85 perform wide-character output to \fIstream\fP.
86 \fIstream\fP must not be byte oriented; see
95 perform wide-character output
96 to an array of wide characters.
97 The programmer must ensure that there is
98 room for at least \fImaxlen\fP wide
99 characters at \fIwcs\fP.
101 These functions are like
109 functions except for the
110 following differences:
113 The \fIformat\fP string is a wide-character string.
116 The output consists of wide characters, not bytes.
122 take a \fImaxlen\fP argument,
130 take a \fImaxlen\fP argument, but these functions do not return \-1 upon
131 buffer overflow on Linux.)
133 The treatment of the conversion characters \fBc\fP and \fBs\fP is different:
138 modifier is present, the
140 argument is converted to a wide character by a call to the
142 function, and the resulting wide character is written.
145 modifier is present, the
147 (wide character) argument is written.
152 modifier is present: The
154 argument is expected to be a pointer to an array of character type
155 (pointer to a string) containing a multibyte character sequence beginning
156 in the initial shift state.
157 Characters from the array are converted to
158 wide characters (each by a call to the
160 function with a conversion state starting in the initial state before
162 The resulting wide characters are written up to
163 (but not including) the terminating null wide character.
165 specified, no more wide characters than the number specified are written.
166 Note that the precision determines the number of
168 written, not the number of
171 .IR "screen positions" .
172 The array must contain a terminating null byte, unless a precision is given
173 and it is so small that the number of converted wide characters reaches it
174 before the end of the array is reached.
177 modifier is present: The
178 .I "const\ wchar_t\ *"
179 argument is expected to be a pointer to an array of wide characters.
180 Wide characters from the array are written up to (but not including) a
181 terminating null wide character.
182 If a precision is specified, no more than
183 the number specified are written.
184 The array must contain a terminating null
185 wide character, unless a precision is given and it is smaller than or equal
186 to the number of wide characters in the array.
188 The functions return the number of wide characters written, excluding the
189 terminating null wide character in
190 case of the functions
194 They return \-1 when an error occurs.
206 If the \fIformat\fP string contains non-ASCII wide characters, the program
207 will work correctly only if the
209 category of the current locale at
210 run time is the same as the
212 category of the current locale at
216 representation is platform- and locale-dependent.
217 (The glibc represents
218 wide characters using their Unicode (ISO-10646) code point, but other
219 platforms don't do this.
220 Also, the use of C99 universal character names
221 of the form \\unnnn does not solve this problem.)
223 internationalized programs, the \fIformat\fP string should consist of ASCII
224 wide characters only, or should be constructed at run time in an
225 internationalized way (e.g., using