]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) Bruno Haible <haible@clisp.cons.org> |
2 | .\" | |
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. | |
7 | .\" | |
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 | |
12 | .\" ISO/IEC 9899:1999 | |
13 | .\" | |
cc4615cc | 14 | .TH WPRINTF 3 2007-07-26 "GNU" "Linux Programmer's Manual" |
fea681da | 15 | .SH NAME |
c13182ef | 16 | wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted |
d0f17b57 | 17 | wide-character output conversion |
fea681da MK |
18 | .SH SYNOPSIS |
19 | .nf | |
20 | .B #include <stdio.h> | |
21 | .B #include <wchar.h> | |
22 | .sp | |
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 , | |
b9f02710 | 26 | .BI " const wchar_t *" format ", ...);" |
fea681da | 27 | .sp |
fea681da MK |
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 , | |
b9f02710 | 31 | .BI " const wchar_t *" format ", va_list " args ); |
fea681da | 32 | .fi |
cc4615cc MK |
33 | .sp |
34 | .in -4n | |
35 | Feature Test Macro Requirements for glibc (see | |
36 | .BR feature_test_macros (7)): | |
37 | .in | |
38 | .sp | |
39 | .ad l | |
40 | All functions described on this page: | |
41 | .\" .BR wprintf (), | |
42 | .\" .BR fwprintf (), | |
43 | .\" .BR swprintf (), | |
44 | .\" .BR vwprintf (), | |
45 | .\" .BR vfwprintf (), | |
46 | .\" .BR vswprintf (): | |
47 | _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE; or | |
48 | .I cc\ -std=c99 | |
49 | .ad b | |
fea681da | 50 | .SH DESCRIPTION |
60a90ecd MK |
51 | The |
52 | .BR wprintf () | |
53 | family of functions is | |
c13182ef | 54 | the wide-character equivalent of the |
60a90ecd MK |
55 | .BR printf (3) |
56 | family of functions. | |
c13182ef | 57 | It performs formatted output of wide |
fea681da MK |
58 | characters. |
59 | .PP | |
60a90ecd MK |
60 | The |
61 | .BR wprintf () | |
62 | and | |
63 | .BR vwprintf () | |
64 | functions | |
9bef72b5 MK |
65 | perform wide-character output to \fIstdout\fP. |
66 | \fIstdout\fP must not be byte oriented; see function | |
60a90ecd MK |
67 | .BR fwide (3) |
68 | for more information. | |
fea681da | 69 | .PP |
60a90ecd MK |
70 | The |
71 | .BR fwprintf () | |
72 | and | |
73 | .BR vfwprintf () | |
74 | functions | |
d0f17b57 | 75 | perform wide-character output to \fIstream\fP. |
35478399 | 76 | \fIstream\fP must not be byte oriented; see function |
60a90ecd MK |
77 | .BR fwide (3) |
78 | for more information. | |
fea681da | 79 | .PP |
60a90ecd MK |
80 | The |
81 | .BR swprintf () | |
82 | and | |
83 | .BR vswprintf () | |
84 | functions | |
d0f17b57 | 85 | perform wide-character output |
fea681da | 86 | to an array of wide characters. |
c13182ef MK |
87 | The programmer must ensure that there is |
88 | room for at least \fImaxlen\fP wide | |
fea681da MK |
89 | characters at \fIwcs\fP. |
90 | .PP | |
c13182ef | 91 | These functions are like |
60a90ecd MK |
92 | the |
93 | .BR printf (3), | |
94 | .BR vprintf (3), | |
95 | .BR fprintf (3), | |
96 | .BR vfprintf (3), | |
97 | .BR sprintf (3), | |
98 | .BR vsprintf (3) | |
c13182ef | 99 | functions except for the |
fea681da MK |
100 | following differences: |
101 | .TP | |
102 | .B \(bu | |
d0f17b57 | 103 | The \fIformat\fP string is a wide-character string. |
fea681da MK |
104 | .TP |
105 | .B \(bu | |
106 | The output consists of wide characters, not bytes. | |
107 | .TP | |
108 | .B \(bu | |
60a90ecd MK |
109 | .BR swprintf () |
110 | and | |
111 | .BR vswprintf () | |
112 | take a \fImaxlen\fP argument, | |
113 | .BR sprintf (3) | |
114 | and | |
115 | .BR vsprintf (3) | |
116 | do not. | |
117 | .RB ( snprintf (3) | |
118 | and | |
119 | .BR vsnprintf (3) | |
fea681da MK |
120 | take a \fImaxlen\fP argument, but these functions do not return \-1 upon |
121 | buffer overflow on Linux.) | |
122 | .PP | |
123 | The treatment of the conversion characters \fBc\fP and \fBs\fP is different: | |
124 | .TP | |
125 | .B c | |
126 | If no | |
127 | .B l | |
128 | modifier is present, the | |
129 | .I int | |
130 | argument is converted to a wide character by a call to the | |
fb186734 | 131 | .BR btowc (3) |
fea681da MK |
132 | function, and the resulting wide character is written. |
133 | If an | |
134 | .B l | |
135 | modifier is present, the | |
136 | .I wint_t | |
137 | (wide character) argument is written. | |
138 | .TP | |
139 | .B s | |
140 | If no | |
141 | .B l | |
142 | modifier is present: The | |
2b0fa182 | 143 | .I "const\ char\ *" |
fea681da MK |
144 | argument is expected to be a pointer to an array of character type |
145 | (pointer to a string) containing a multibyte character sequence beginning | |
c13182ef MK |
146 | in the initial shift state. |
147 | Characters from the array are converted to | |
fea681da | 148 | wide characters (each by a call to the |
fb186734 | 149 | .BR mbrtowc (3) |
fea681da | 150 | function with a conversion state starting in the initial state before |
c13182ef MK |
151 | the first byte). |
152 | The resulting wide characters are written up to | |
153 | (but not including) the terminating null wide character. | |
154 | If a precision is | |
fea681da MK |
155 | specified, no more wide characters than the number specified are written. |
156 | Note that the precision determines the number of | |
157 | .I wide characters | |
158 | written, not the number of | |
159 | .I bytes | |
160 | or | |
161 | .IR "screen positions" . | |
162 | The array must contain a terminating null byte, unless a precision is given | |
163 | and it is so small that the number of converted wide characters reaches it | |
c13182ef MK |
164 | before the end of the array is reached. |
165 | If an | |
fea681da MK |
166 | .B l |
167 | modifier is present: The | |
2b0fa182 | 168 | .I "const\ wchar_t\ *" |
fea681da MK |
169 | argument is expected to be a pointer to an array of wide characters. |
170 | Wide characters from the array are written up to (but not including) a | |
c13182ef MK |
171 | terminating null wide character. |
172 | If a precision is specified, no more than | |
173 | the number specified are written. | |
174 | The array must contain a terminating null | |
fea681da MK |
175 | wide character, unless a precision is given and it is smaller than or equal |
176 | to the number of wide characters in the array. | |
177 | .SH "RETURN VALUE" | |
178 | The functions return the number of wide characters written, excluding the | |
c13182ef | 179 | terminating null wide character in |
60a90ecd MK |
180 | case of the functions |
181 | .BR swprintf () | |
182 | and | |
183 | .BR vswprintf (). | |
c13182ef | 184 | They return \-1 when an error occurs. |
fea681da | 185 | .SH "CONFORMING TO" |
68e1685c | 186 | C99. |
fea681da | 187 | .SH NOTES |
d9bfdb9c | 188 | The behavior of |
60a90ecd MK |
189 | .BR wprintf () |
190 | et al. depends | |
1274071a MK |
191 | on the |
192 | .B LC_CTYPE | |
193 | category of the | |
fea681da MK |
194 | current locale. |
195 | .PP | |
196 | If the \fIformat\fP string contains non-ASCII wide characters, the program | |
1274071a MK |
197 | will only work correctly if the |
198 | .B LC_CTYPE | |
199 | category of the current locale at | |
200 | run time is the same as the | |
201 | .B LC_CTYPE | |
202 | category of the current locale at | |
c13182ef MK |
203 | compile time. |
204 | This is because the | |
9ff08aad | 205 | .I wchar_t |
c13182ef MK |
206 | representation is platform and locale dependent. |
207 | (The GNU libc represents | |
fea681da | 208 | wide characters using their Unicode (ISO-10646) code point, but other |
c13182ef | 209 | platforms don't do this. |
68e1685c | 210 | Also, the use of C99 universal character names |
c13182ef MK |
211 | of the form \\unnnn does not solve this problem.) |
212 | Therefore, in | |
fea681da MK |
213 | internationalized programs, the \fIformat\fP string should consist of ASCII |
214 | wide characters only, or should be constructed at run time in an | |
75b94dc3 | 215 | internationalized way (e.g., using |
fb186734 | 216 | .BR gettext (3) |
fea681da | 217 | or |
fb186734 | 218 | .BR iconv (3), |
fea681da | 219 | followed by |
fb186734 | 220 | .BR mbstowcs (3)). |
e37e3282 MK |
221 | .SH "SEE ALSO" |
222 | .BR fprintf (3), | |
223 | .BR fputwc (3), | |
224 | .BR fwide (3), | |
225 | .BR printf (3), | |
44bc0c36 | 226 | .BR snprintf (3) |
988db661 | 227 | .\" .BR wscanf (3) |