Debian Codegraph @

upstream/debian-unstable/man3/wprintf.3

raw
1 '\" t
2 .\" Copyright, Bruno Haible <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH wprintf 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
10 wide-character output conversion
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <stdio.h>
17 .B #include <wchar.h>
18 .P
19 .BI "int wprintf(const wchar_t *restrict " format ", ...);"
20 .BI "int fwprintf(FILE *restrict " stream ,
21 .BI " const wchar_t *restrict " format ", ...);"
22 .BR "int swprintf(" "size_t n;"
23 .BI " wchar_t " wcs "[restrict " n "], size_t " n ,
24 .BI " const wchar_t *restrict " format ", ...);"
25 .P
26 .BI "int vwprintf(const wchar_t *restrict " format ", va_list " args );
27 .BI "int vfwprintf(FILE *restrict " stream ,
28 .BI " const wchar_t *restrict " format ", va_list " args );
29 .BR "int vswprintf(" "size_t n;"
30 .BI " wchar_t " wcs "[restrict " n "], size_t " n ,
31 .BI " const wchar_t *restrict " format ", va_list " args );
32 .fi
33 .P
34 .RS -4
35 Feature Test Macro Requirements for glibc (see
36 .BR feature_test_macros (7)):
37 .RE
38 .P
39 All functions shown above:
40 .\" .BR wprintf (),
41 .\" .BR fwprintf (),
42 .\" .BR swprintf (),
43 .\" .BR vwprintf (),
44 .\" .BR vfwprintf (),
45 .\" .BR vswprintf ():
46 .nf
47 _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
48 || _POSIX_C_SOURCE >= 200112L
49 .fi
50 .SH DESCRIPTION
51 The
52 .BR wprintf ()
53 family of functions is
54 the wide-character equivalent of the
55 .BR printf (3)
56 family of functions.
57 It performs formatted output of wide
58 characters.
59 .P
60 The
61 .BR wprintf ()
62 and
63 .BR vwprintf ()
64 functions
65 perform wide-character output to
66 .IR stdout .
67 .I stdout
68 must not be byte oriented;
69 see
70 .BR fwide (3)
71 for more information.
72 .P
73 The
74 .BR fwprintf ()
75 and
76 .BR vfwprintf ()
77 functions
78 perform wide-character output to
79 .IR stream .
80 .I stream
81 must not be byte oriented;
82 see
83 .BR fwide (3)
84 for more information.
85 .P
86 The
87 .BR swprintf ()
88 and
89 .BR vswprintf ()
90 functions
91 perform wide-character output
92 to an array of wide characters.
93 The programmer must ensure that there is
94 room for at least
95 .I n
96 wide
97 characters at
98 .IR wcs .
99 .P
100 These functions are like
101 the
102 .BR printf (3),
103 .BR vprintf (3),
104 .BR fprintf (3),
105 .BR vfprintf (3),
106 .BR sprintf (3),
107 .BR vsprintf (3)
108 functions except for the
109 following differences:
110 .TP
111 .B \[bu]
112 The
113 .I format
114 string is a wide-character string.
115 .TP
116 .B \[bu]
117 The output consists of wide characters, not bytes.
118 .TP
119 .B \[bu]
120 .BR swprintf ()
121 and
122 .BR vswprintf ()
123 take a
124 .I n
125 argument,
126 .BR sprintf (3)
127 and
128 .BR vsprintf (3)
129 do not.
130 .RB ( snprintf (3)
131 and
132 .BR vsnprintf (3)
133 take a
134 .I n
135 argument, but these functions do not return \-1 upon
136 buffer overflow on Linux.)
137 .P
138 The treatment of the conversion characters
139 .B c
140 and
141 .B s
142 is different:
143 .TP
144 .B c
145 If no
146 .B l
147 modifier is present, the
148 .I int
149 argument is converted to a wide character by a call to the
150 .BR btowc (3)
151 function, and the resulting wide character is written.
152 If an
153 .B l
154 modifier is present, the
155 .I wint_t
156 (wide character) argument is written.
157 .TP
158 .B s
159 If no
160 .B l
161 modifier is present: the
162 .I "const\ char\ *"
163 argument is expected to be a pointer to an array of character type
164 (pointer to a string) containing a multibyte character sequence beginning
165 in the initial shift state.
166 Characters from the array are converted to
167 wide characters (each by a call to the
168 .BR mbrtowc (3)
169 function with a conversion state starting in the initial state before
170 the first byte).
171 The resulting wide characters are written up to
172 (but not including) the terminating null wide character (L\[aq]\[rs]0\[aq]).
173 If a precision is
174 specified, no more wide characters than the number specified are written.
175 Note that the precision determines the number of
176 .I wide characters
177 written, not the number of
178 .I bytes
179 or
180 .IR "screen positions" .
181 The array must contain a terminating null byte (\[aq]\[rs]0\[aq]),
182 unless a precision is given
183 and it is so small that the number of converted wide characters reaches it
184 before the end of the array is reached.
185 If an
186 .B l
187 modifier is present: the
188 .I "const\ wchar_t\ *"
189 argument is expected to be a pointer to an array of wide characters.
190 Wide characters from the array are written up to (but not including) a
191 terminating null wide character.
192 If a precision is specified, no more than
193 the number specified are written.
194 The array must contain a terminating null
195 wide character, unless a precision is given and it is smaller than or equal
196 to the number of wide characters in the array.
197 .SH RETURN VALUE
198 The functions return the number of wide characters written, excluding the
199 terminating null wide character in
200 case of the functions
201 .BR swprintf ()
202 and
203 .BR vswprintf ().
204 On error,
205 \-1 is returned,
206 and
207 .I errno
208 is set to indicate the error.
209 .SH ERRORS
210 See
211 .BR write (2)
212 and
213 .BR putwc (3).
214 In addition, the following error may occur:
215 .TP
216 .B EOVERFLOW
217 The value to be returned is greater than
218 .BR INT_MAX .
219 .P
220 The
221 .BR fwprintf ()
222 and
223 .BR wprintf ()
224 functions may fail additionally if:
225 .TP
226 .B ENOMEM
227 Insufficient storage space is available.
228 .SH ATTRIBUTES
229 For an explanation of the terms used in this section, see
230 .BR attributes (7).
231 .TS
232 allbox;
233 lbx lb lb
234 l l l.
235 Interface Attribute Value
236 T{
237 .na
238 .nh
239 .BR wprintf (),
240 .BR fwprintf (),
241 .BR swprintf (),
242 .BR vwprintf (),
243 .BR vfwprintf (),
244 .BR vswprintf ()
245 T} Thread safety MT-Safe locale
246 .TE
247 .SH STANDARDS
248 C11, POSIX.1-2008.
249 .SH HISTORY
250 POSIX.1-2001, C99.
251 .SH NOTES
252 The behavior of
253 .BR wprintf ()
254 et al.\& depends
255 on the
256 .B LC_CTYPE
257 category of the
258 current locale.
259 .P
260 If the
261 .I format
262 string contains non-ASCII wide characters, the program
263 will work correctly only if the
264 .B LC_CTYPE
265 category of the current locale at
266 run time is the same as the
267 .B LC_CTYPE
268 category of the current locale at
269 compile time.
270 This is because the
271 .I wchar_t
272 representation is platform- and locale-dependent.
273 (The glibc represents
274 wide characters using their Unicode (ISO/IEC 10646) code point, but other
275 platforms don't do this.
276 Also, the use of C99 universal character names
277 of the form \[rs]unnnn does not solve this problem.)
278 Therefore, in
279 internationalized programs, the
280 .I format
281 string should consist of ASCII
282 wide characters only, or should be constructed at run time in an
283 internationalized way (e.g., using
284 .BR gettext (3)
285 or
286 .BR iconv (3),
287 followed by
288 .BR mbstowcs (3)).
289 .SH SEE ALSO
290 .BR fprintf (3),
291 .BR fputwc (3),
292 .BR fwide (3),
293 .BR printf (3),
294 .BR snprintf (3)
295 .\" .BR wscanf (3)