]>
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 | .\" | |
70225000 | 16 | .TH WPRINTF 3 2011-09-17 "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 MK |
51 | .br |
52 | _ISOC95_SOURCE /* Since glibc 2.12 */ || | |
53 | .br | |
7d9e2c21 | 54 | _POSIX_C_SOURCE\ >=\ 200112L; |
c865a6eb MK |
55 | .br |
56 | or | |
cc4615cc | 57 | .I cc\ -std=c99 |
c865a6eb MK |
58 | .RE |
59 | .ad | |
fea681da | 60 | .SH DESCRIPTION |
60a90ecd MK |
61 | The |
62 | .BR wprintf () | |
63 | family of functions is | |
c13182ef | 64 | the wide-character equivalent of the |
60a90ecd MK |
65 | .BR printf (3) |
66 | family of functions. | |
c13182ef | 67 | It performs formatted output of wide |
fea681da MK |
68 | characters. |
69 | .PP | |
60a90ecd MK |
70 | The |
71 | .BR wprintf () | |
72 | and | |
73 | .BR vwprintf () | |
74 | functions | |
9bef72b5 | 75 | perform wide-character output to \fIstdout\fP. |
9577265c | 76 | \fIstdout\fP 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 | |
d0f17b57 | 85 | perform wide-character output to \fIstream\fP. |
9577265c | 86 | \fIstream\fP must not be byte oriented; see |
60a90ecd MK |
87 | .BR fwide (3) |
88 | for more information. | |
fea681da | 89 | .PP |
60a90ecd MK |
90 | The |
91 | .BR swprintf () | |
92 | and | |
93 | .BR vswprintf () | |
94 | functions | |
d0f17b57 | 95 | perform wide-character output |
fea681da | 96 | to an array of wide characters. |
c13182ef MK |
97 | The programmer must ensure that there is |
98 | room for at least \fImaxlen\fP wide | |
fea681da MK |
99 | characters at \fIwcs\fP. |
100 | .PP | |
c13182ef | 101 | These functions are like |
60a90ecd MK |
102 | the |
103 | .BR printf (3), | |
104 | .BR vprintf (3), | |
105 | .BR fprintf (3), | |
106 | .BR vfprintf (3), | |
107 | .BR sprintf (3), | |
108 | .BR vsprintf (3) | |
c13182ef | 109 | functions except for the |
fea681da MK |
110 | following differences: |
111 | .TP | |
112 | .B \(bu | |
d0f17b57 | 113 | The \fIformat\fP string is a wide-character string. |
fea681da MK |
114 | .TP |
115 | .B \(bu | |
116 | The output consists of wide characters, not bytes. | |
117 | .TP | |
118 | .B \(bu | |
60a90ecd MK |
119 | .BR swprintf () |
120 | and | |
121 | .BR vswprintf () | |
122 | take a \fImaxlen\fP argument, | |
123 | .BR sprintf (3) | |
124 | and | |
125 | .BR vsprintf (3) | |
126 | do not. | |
127 | .RB ( snprintf (3) | |
128 | and | |
129 | .BR vsnprintf (3) | |
fea681da MK |
130 | take a \fImaxlen\fP argument, but these functions do not return \-1 upon |
131 | buffer overflow on Linux.) | |
132 | .PP | |
133 | The treatment of the conversion characters \fBc\fP and \fBs\fP is different: | |
134 | .TP | |
135 | .B c | |
136 | If no | |
137 | .B l | |
138 | modifier is present, the | |
139 | .I int | |
140 | argument is converted to a wide character by a call to the | |
fb186734 | 141 | .BR btowc (3) |
fea681da MK |
142 | function, and the resulting wide character is written. |
143 | If an | |
144 | .B l | |
145 | modifier is present, the | |
146 | .I wint_t | |
147 | (wide character) argument is written. | |
148 | .TP | |
149 | .B s | |
150 | If no | |
151 | .B l | |
152 | modifier is present: The | |
2b0fa182 | 153 | .I "const\ char\ *" |
fea681da MK |
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 | |
c13182ef MK |
156 | in the initial shift state. |
157 | Characters from the array are converted to | |
fea681da | 158 | wide characters (each by a call to the |
fb186734 | 159 | .BR mbrtowc (3) |
fea681da | 160 | function with a conversion state starting in the initial state before |
c13182ef MK |
161 | the first byte). |
162 | The resulting wide characters are written up to | |
163 | (but not including) the terminating null wide character. | |
164 | If a precision is | |
fea681da MK |
165 | specified, no more wide characters than the number specified are written. |
166 | Note that the precision determines the number of | |
167 | .I wide characters | |
168 | written, not the number of | |
169 | .I bytes | |
170 | or | |
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 | |
c13182ef MK |
174 | before the end of the array is reached. |
175 | If an | |
fea681da MK |
176 | .B l |
177 | modifier is present: The | |
2b0fa182 | 178 | .I "const\ wchar_t\ *" |
fea681da MK |
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 | |
c13182ef MK |
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 | |
fea681da MK |
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. | |
47297adb | 187 | .SH RETURN VALUE |
fea681da | 188 | The functions return the number of wide characters written, excluding the |
c13182ef | 189 | terminating null wide character in |
60a90ecd MK |
190 | case of the functions |
191 | .BR swprintf () | |
192 | and | |
193 | .BR vswprintf (). | |
c13182ef | 194 | They return \-1 when an error occurs. |
47297adb | 195 | .SH CONFORMING TO |
68e1685c | 196 | C99. |
fea681da | 197 | .SH NOTES |
d9bfdb9c | 198 | The behavior of |
60a90ecd MK |
199 | .BR wprintf () |
200 | et al. depends | |
1274071a MK |
201 | on the |
202 | .B LC_CTYPE | |
203 | category of the | |
fea681da MK |
204 | current locale. |
205 | .PP | |
206 | If the \fIformat\fP string contains non-ASCII wide characters, the program | |
1274071a MK |
207 | will only work correctly if the |
208 | .B LC_CTYPE | |
209 | category of the current locale at | |
210 | run time is the same as the | |
211 | .B LC_CTYPE | |
212 | category of the current locale at | |
c13182ef MK |
213 | compile time. |
214 | This is because the | |
9ff08aad | 215 | .I wchar_t |
a43eed0c | 216 | representation is platform- and locale-dependent. |
5260fe08 | 217 | (The glibc represents |
fea681da | 218 | wide characters using their Unicode (ISO-10646) code point, but other |
c13182ef | 219 | platforms don't do this. |
68e1685c | 220 | Also, the use of C99 universal character names |
c13182ef MK |
221 | of the form \\unnnn does not solve this problem.) |
222 | Therefore, in | |
fea681da MK |
223 | internationalized programs, the \fIformat\fP string should consist of ASCII |
224 | wide characters only, or should be constructed at run time in an | |
75b94dc3 | 225 | internationalized way (e.g., using |
fb186734 | 226 | .BR gettext (3) |
fea681da | 227 | or |
fb186734 | 228 | .BR iconv (3), |
fea681da | 229 | followed by |
fb186734 | 230 | .BR mbstowcs (3)). |
47297adb | 231 | .SH SEE ALSO |
e37e3282 MK |
232 | .BR fprintf (3), |
233 | .BR fputwc (3), | |
234 | .BR fwide (3), | |
235 | .BR printf (3), | |
44bc0c36 | 236 | .BR snprintf (3) |
988db661 | 237 | .\" .BR wscanf (3) |