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