]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) Bruno Haible <haible@clisp.cons.org> |
2 | .\" | |
89e3ffe9 | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) |
fea681da MK |
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. | |
fe382ebf | 8 | .\" %%%LICENSE_END |
fea681da MK |
9 | .\" |
10 | .\" References consulted: | |
11 | .\" GNU glibc-2 source code and manual | |
12 | .\" Dinkumware C library reference http://www.dinkumware.com/ | |
008f1ecc | 13 | .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html |
fea681da MK |
14 | .\" ISO/IEC 9899:1999 |
15 | .\" | |
460495ca | 16 | .TH WPRINTF 3 2015-08-08 "GNU" "Linux Programmer's Manual" |
fea681da | 17 | .SH NAME |
c13182ef | 18 | wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted |
d0f17b57 | 19 | wide-character output conversion |
fea681da MK |
20 | .SH SYNOPSIS |
21 | .nf | |
22 | .B #include <stdio.h> | |
23 | .B #include <wchar.h> | |
24 | .sp | |
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 , | |
b9f02710 | 28 | .BI " const wchar_t *" format ", ...);" |
fea681da | 29 | .sp |
fea681da MK |
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 , | |
b9f02710 | 33 | .BI " const wchar_t *" format ", va_list " args ); |
fea681da | 34 | .fi |
cc4615cc MK |
35 | .sp |
36 | .in -4n | |
37 | Feature Test Macro Requirements for glibc (see | |
38 | .BR feature_test_macros (7)): | |
39 | .in | |
40 | .sp | |
41 | .ad l | |
cfc2d88d | 42 | All functions shown above: |
c865a6eb | 43 | .RS 4 |
cc4615cc MK |
44 | .\" .BR wprintf (), |
45 | .\" .BR fwprintf (), | |
46 | .\" .BR swprintf (), | |
47 | .\" .BR vwprintf (), | |
48 | .\" .BR vfwprintf (), | |
49 | .\" .BR vswprintf (): | |
7d9e2c21 | 50 | _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE || |
70225000 | 51 | .br |
7d9e2c21 | 52 | _POSIX_C_SOURCE\ >=\ 200112L; |
c865a6eb MK |
53 | .br |
54 | or | |
cc4615cc | 55 | .I cc\ -std=c99 |
c865a6eb MK |
56 | .RE |
57 | .ad | |
fea681da | 58 | .SH DESCRIPTION |
60a90ecd MK |
59 | The |
60 | .BR wprintf () | |
61 | family of functions is | |
c13182ef | 62 | the wide-character equivalent of the |
60a90ecd MK |
63 | .BR printf (3) |
64 | family of functions. | |
c13182ef | 65 | It performs formatted output of wide |
fea681da MK |
66 | characters. |
67 | .PP | |
60a90ecd MK |
68 | The |
69 | .BR wprintf () | |
70 | and | |
71 | .BR vwprintf () | |
72 | functions | |
e4a0d6cb MK |
73 | perform wide-character output to |
74 | .IR stdout . | |
75 | .I stdout | |
76 | must not be byte oriented; see | |
60a90ecd MK |
77 | .BR fwide (3) |
78 | for more information. | |
fea681da | 79 | .PP |
60a90ecd MK |
80 | The |
81 | .BR fwprintf () | |
82 | and | |
83 | .BR vfwprintf () | |
84 | functions | |
e4a0d6cb MK |
85 | perform wide-character output to |
86 | .IR stream . | |
87 | .I stream | |
88 | must not be byte oriented; see | |
60a90ecd MK |
89 | .BR fwide (3) |
90 | for more information. | |
fea681da | 91 | .PP |
60a90ecd MK |
92 | The |
93 | .BR swprintf () | |
94 | and | |
95 | .BR vswprintf () | |
96 | functions | |
d0f17b57 | 97 | perform wide-character output |
fea681da | 98 | to an array of wide characters. |
c13182ef | 99 | The programmer must ensure that there is |
e4a0d6cb MK |
100 | room for at least |
101 | .I maxlen | |
102 | wide | |
103 | characters at | |
104 | .IR wcs . | |
fea681da | 105 | .PP |
c13182ef | 106 | These functions are like |
60a90ecd MK |
107 | the |
108 | .BR printf (3), | |
109 | .BR vprintf (3), | |
110 | .BR fprintf (3), | |
111 | .BR vfprintf (3), | |
112 | .BR sprintf (3), | |
113 | .BR vsprintf (3) | |
c13182ef | 114 | functions except for the |
fea681da MK |
115 | following differences: |
116 | .TP | |
117 | .B \(bu | |
e4a0d6cb MK |
118 | The |
119 | .I format | |
120 | string is a wide-character string. | |
fea681da MK |
121 | .TP |
122 | .B \(bu | |
123 | The output consists of wide characters, not bytes. | |
124 | .TP | |
125 | .B \(bu | |
60a90ecd MK |
126 | .BR swprintf () |
127 | and | |
128 | .BR vswprintf () | |
e4a0d6cb MK |
129 | take a |
130 | .I maxlen | |
131 | argument, | |
60a90ecd MK |
132 | .BR sprintf (3) |
133 | and | |
134 | .BR vsprintf (3) | |
135 | do not. | |
136 | .RB ( snprintf (3) | |
137 | and | |
138 | .BR vsnprintf (3) | |
e4a0d6cb MK |
139 | take a |
140 | .I maxlen | |
141 | argument, but these functions do not return \-1 upon | |
fea681da MK |
142 | buffer overflow on Linux.) |
143 | .PP | |
e4a0d6cb | 144 | The treatment of the conversion characters |
51700fd7 | 145 | .BR c |
e4a0d6cb MK |
146 | and |
147 | .B s | |
148 | is different: | |
fea681da MK |
149 | .TP |
150 | .B c | |
151 | If no | |
152 | .B l | |
153 | modifier is present, the | |
154 | .I int | |
155 | argument is converted to a wide character by a call to the | |
fb186734 | 156 | .BR btowc (3) |
fea681da MK |
157 | function, and the resulting wide character is written. |
158 | If an | |
159 | .B l | |
160 | modifier is present, the | |
161 | .I wint_t | |
162 | (wide character) argument is written. | |
163 | .TP | |
164 | .B s | |
165 | If no | |
166 | .B l | |
167 | modifier is present: The | |
2b0fa182 | 168 | .I "const\ char\ *" |
fea681da MK |
169 | argument is expected to be a pointer to an array of character type |
170 | (pointer to a string) containing a multibyte character sequence beginning | |
c13182ef MK |
171 | in the initial shift state. |
172 | Characters from the array are converted to | |
fea681da | 173 | wide characters (each by a call to the |
fb186734 | 174 | .BR mbrtowc (3) |
fea681da | 175 | function with a conversion state starting in the initial state before |
c13182ef MK |
176 | the first byte). |
177 | The resulting wide characters are written up to | |
6ac8bf78 | 178 | (but not including) the terminating null wide character (L\(aq\\0\(aq). |
c13182ef | 179 | If a precision is |
fea681da MK |
180 | specified, no more wide characters than the number specified are written. |
181 | Note that the precision determines the number of | |
182 | .I wide characters | |
183 | written, not the number of | |
184 | .I bytes | |
185 | or | |
186 | .IR "screen positions" . | |
6ac8bf78 MK |
187 | The array must contain a terminating null byte (\(aq\\0\(aq), |
188 | unless a precision is given | |
fea681da | 189 | and it is so small that the number of converted wide characters reaches it |
c13182ef MK |
190 | before the end of the array is reached. |
191 | If an | |
fea681da MK |
192 | .B l |
193 | modifier is present: The | |
2b0fa182 | 194 | .I "const\ wchar_t\ *" |
fea681da MK |
195 | argument is expected to be a pointer to an array of wide characters. |
196 | Wide characters from the array are written up to (but not including) a | |
c13182ef MK |
197 | terminating null wide character. |
198 | If a precision is specified, no more than | |
199 | the number specified are written. | |
200 | The array must contain a terminating null | |
fea681da MK |
201 | wide character, unless a precision is given and it is smaller than or equal |
202 | to the number of wide characters in the array. | |
47297adb | 203 | .SH RETURN VALUE |
fea681da | 204 | The functions return the number of wide characters written, excluding the |
c13182ef | 205 | terminating null wide character in |
60a90ecd MK |
206 | case of the functions |
207 | .BR swprintf () | |
208 | and | |
209 | .BR vswprintf (). | |
c13182ef | 210 | They return \-1 when an error occurs. |
9534c08c ZL |
211 | .SH ATTRIBUTES |
212 | For an explanation of the terms used in this section, see | |
213 | .BR attributes (7). | |
214 | .TS | |
215 | allbox; | |
216 | lbw24 lb lb | |
217 | l l l. | |
218 | Interface Attribute Value | |
219 | T{ | |
220 | .BR wprintf (), | |
221 | .BR fwprintf (), | |
222 | .br | |
223 | .BR swprintf (), | |
224 | .BR vwprintf (), | |
225 | .br | |
226 | .BR vfwprintf (), | |
227 | .BR vswprintf () | |
228 | T} Thread safety MT-Safe locale | |
229 | .TE | |
230 | ||
47297adb | 231 | .SH CONFORMING TO |
72836d51 | 232 | POSIX.1-2001, POSIX.1-2008, C99. |
fea681da | 233 | .SH NOTES |
d9bfdb9c | 234 | The behavior of |
60a90ecd MK |
235 | .BR wprintf () |
236 | et al. depends | |
1274071a MK |
237 | on the |
238 | .B LC_CTYPE | |
239 | category of the | |
fea681da MK |
240 | current locale. |
241 | .PP | |
e4a0d6cb MK |
242 | If the |
243 | .I format | |
244 | string contains non-ASCII wide characters, the program | |
33a0ccb2 | 245 | will work correctly only if the |
1274071a MK |
246 | .B LC_CTYPE |
247 | category of the current locale at | |
248 | run time is the same as the | |
249 | .B LC_CTYPE | |
250 | category of the current locale at | |
c13182ef MK |
251 | compile time. |
252 | This is because the | |
9ff08aad | 253 | .I wchar_t |
a43eed0c | 254 | representation is platform- and locale-dependent. |
5260fe08 | 255 | (The glibc represents |
fea681da | 256 | wide characters using their Unicode (ISO-10646) code point, but other |
c13182ef | 257 | platforms don't do this. |
68e1685c | 258 | Also, the use of C99 universal character names |
c13182ef MK |
259 | of the form \\unnnn does not solve this problem.) |
260 | Therefore, in | |
e4a0d6cb MK |
261 | internationalized programs, the |
262 | .I format | |
263 | string should consist of ASCII | |
fea681da | 264 | wide characters only, or should be constructed at run time in an |
75b94dc3 | 265 | internationalized way (e.g., using |
fb186734 | 266 | .BR gettext (3) |
fea681da | 267 | or |
fb186734 | 268 | .BR iconv (3), |
fea681da | 269 | followed by |
fb186734 | 270 | .BR mbstowcs (3)). |
47297adb | 271 | .SH SEE ALSO |
e37e3282 MK |
272 | .BR fprintf (3), |
273 | .BR fputwc (3), | |
274 | .BR fwide (3), | |
275 | .BR printf (3), | |
44bc0c36 | 276 | .BR snprintf (3) |
988db661 | 277 | .\" .BR wscanf (3) |