1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" This is free documentation; you can redistribute it and/or
4 .\" modify it under the terms of the GNU General Public License as
5 .\" published by the Free Software Foundation; either version 2 of
6 .\" the License, or (at your option) any later version.
8 .\" References consulted:
9 .\" GNU glibc-2 source code and manual
10 .\" Dinkumware C library reference http://www.dinkumware.com/
11 .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
14 .TH WPRINTF 3 2011-09-17 "GNU" "Linux Programmer's Manual"
16 wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
17 wide-character output conversion
23 .BI "int wprintf(const wchar_t *" format ", ...);"
24 .BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);"
25 .BI "int swprintf(wchar_t *" wcs ", size_t " maxlen ,
26 .BI " const wchar_t *" format ", ...);"
28 .BI "int vwprintf(const wchar_t *" format ", va_list " args );
29 .BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args );
30 .BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen ,
31 .BI " const wchar_t *" format ", va_list " args );
35 Feature Test Macro Requirements for glibc (see
36 .BR feature_test_macros (7)):
40 All functions shown above:
48 _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
50 _ISOC95_SOURCE /* Since glibc 2.12 */ ||
52 _POSIX_C_SOURCE\ >=\ 200112L;
61 family of functions is
62 the wide-character equivalent of the
65 It performs formatted output of wide
73 perform wide-character output to \fIstdout\fP.
74 \fIstdout\fP must not be byte oriented; see
83 perform wide-character output to \fIstream\fP.
84 \fIstream\fP 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
96 room for at least \fImaxlen\fP wide
97 characters at \fIwcs\fP.
99 These functions are like
107 functions except for the
108 following differences:
111 The \fIformat\fP string is a wide-character string.
114 The output consists of wide characters, not bytes.
120 take a \fImaxlen\fP argument,
128 take a \fImaxlen\fP argument, but these functions do not return \-1 upon
129 buffer overflow on Linux.)
131 The treatment of the conversion characters \fBc\fP and \fBs\fP is different:
136 modifier is present, the
138 argument is converted to a wide character by a call to the
140 function, and the resulting wide character is written.
143 modifier is present, the
145 (wide character) argument is written.
150 modifier is present: The
152 argument is expected to be a pointer to an array of character type
153 (pointer to a string) containing a multibyte character sequence beginning
154 in the initial shift state.
155 Characters from the array are converted to
156 wide characters (each by a call to the
158 function with a conversion state starting in the initial state before
160 The resulting wide characters are written up to
161 (but not including) the terminating null wide character.
163 specified, no more wide characters than the number specified are written.
164 Note that the precision determines the number of
166 written, not the number of
169 .IR "screen positions" .
170 The array must contain a terminating null byte, unless a precision is given
171 and it is so small that the number of converted wide characters reaches it
172 before the end of the array is reached.
175 modifier is present: The
176 .I "const\ wchar_t\ *"
177 argument is expected to be a pointer to an array of wide characters.
178 Wide characters from the array are written up to (but not including) a
179 terminating null wide character.
180 If a precision is specified, no more than
181 the number specified are written.
182 The array must contain a terminating null
183 wide character, unless a precision is given and it is smaller than or equal
184 to the number of wide characters in the array.
186 The functions return the number of wide characters written, excluding the
187 terminating null wide character in
188 case of the functions
192 They return \-1 when an error occurs.
204 If the \fIformat\fP string contains non-ASCII wide characters, the program
205 will only work correctly if the
207 category of the current locale at
208 run time is the same as the
210 category of the current locale at
214 representation is platform- and locale-dependent.
215 (The glibc represents
216 wide characters using their Unicode (ISO-10646) code point, but other
217 platforms don't do this.
218 Also, the use of C99 universal character names
219 of the form \\unnnn does not solve this problem.)
221 internationalized programs, the \fIformat\fP string should consist of ASCII
222 wide characters only, or should be constructed at run time in an
223 internationalized way (e.g., using