]>
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 |
fea681da MK |
14 | .\" http://www.UNIX-systems.org/online.html |
15 | .\" ISO/IEC 9899:1999 | |
16 | .\" | |
460495ca | 17 | .TH MBRTOWC 3 2015-08-08 "GNU" "Linux Programmer's Manual" |
fea681da MK |
18 | .SH NAME |
19 | mbrtowc \- convert a multibyte sequence to a wide character | |
20 | .SH SYNOPSIS | |
21 | .nf | |
22 | .B #include <wchar.h> | |
68e4db0a | 23 | .PP |
3d54a910 MK |
24 | .BI "size_t mbrtowc(wchar_t *" pwc ", const char *" s ", size_t " n \ |
25 | ", mbstate_t *" ps ); | |
fea681da MK |
26 | .fi |
27 | .SH DESCRIPTION | |
40aa0db0 | 28 | The main case for this function is when |
51700fd7 | 29 | .IR s |
40aa0db0 MK |
30 | is not NULL and |
31 | .I pwc | |
32 | is | |
c13182ef | 33 | not NULL. |
60a90ecd MK |
34 | In this case, the |
35 | .BR mbrtowc () | |
40aa0db0 MK |
36 | function inspects at most |
37 | .I n | |
38 | bytes of the multibyte string starting at | |
39 | .IR s , | |
40 | extracts the next complete | |
fea681da | 41 | multibyte character, converts it to a wide character and stores it at |
40aa0db0 MK |
42 | .IR *pwc . |
43 | It updates the shift state | |
44 | .IR *ps . | |
c13182ef | 45 | If the converted wide |
e9c23bc6 MK |
46 | character is not L\(aq\\0\(aq (the null wide character), |
47 | it returns the number of bytes that were consumed | |
40aa0db0 MK |
48 | from |
49 | .IR s . | |
f81fb444 | 50 | If the converted wide character is L\(aq\\0\(aq, it resets the shift |
40aa0db0 MK |
51 | state |
52 | .I *ps | |
53 | to the initial state and returns 0. | |
fea681da | 54 | .PP |
40aa0db0 | 55 | If the |
51700fd7 | 56 | .IR n |
40aa0db0 MK |
57 | bytes starting at |
58 | .I s | |
59 | do not contain a complete multibyte | |
60a90ecd MK |
60 | character, |
61 | .BR mbrtowc () | |
40aa0db0 MK |
62 | returns |
63 | .IR "(size_t)\ \-2" . | |
c13182ef | 64 | This can happen even if |
40aa0db0 MK |
65 | .I n |
66 | >= | |
67 | .IR MB_CUR_MAX , | |
68 | if the multibyte string contains redundant shift | |
fea681da MK |
69 | sequences. |
70 | .PP | |
40aa0db0 MK |
71 | If the multibyte string starting at |
72 | .I s | |
73 | contains an invalid multibyte | |
60a90ecd MK |
74 | sequence before the next complete character, |
75 | .BR mbrtowc () | |
76 | returns | |
40aa0db0 MK |
77 | .IR "(size_t)\ \-1" |
78 | and sets | |
79 | .I errno | |
80 | to | |
81 | .BR EILSEQ . | |
c13182ef | 82 | In this case, |
40aa0db0 MK |
83 | the effects on |
84 | .I *ps | |
85 | are undefined. | |
fea681da | 86 | .PP |
40aa0db0 | 87 | A different case is when |
51700fd7 | 88 | .IR s |
40aa0db0 MK |
89 | is not NULL but |
90 | .I pwc | |
91 | is NULL. | |
90c3966f | 92 | In this case, the |
60a90ecd | 93 | .BR mbrtowc () |
5633d88a | 94 | function behaves as above, except that it does not |
fea681da MK |
95 | store the converted wide character in memory. |
96 | .PP | |
40aa0db0 MK |
97 | A third case is when |
98 | .I s | |
99 | is NULL. | |
100 | In this case, | |
51700fd7 | 101 | .IR pwc |
40aa0db0 MK |
102 | and |
103 | .I n | |
104 | are | |
c13182ef | 105 | ignored. |
40aa0db0 MK |
106 | If the conversion state represented by |
107 | .I *ps | |
108 | denotes an | |
60a90ecd MK |
109 | incomplete multibyte character conversion, the |
110 | .BR mbrtowc () | |
111 | function | |
40aa0db0 MK |
112 | returns |
113 | .IR "(size_t)\ \-1" , | |
114 | sets | |
115 | .I errno | |
116 | to | |
117 | .BR EILSEQ , | |
118 | and | |
119 | leaves | |
120 | .I *ps | |
121 | in an undefined state. | |
60a90ecd MK |
122 | Otherwise, the |
123 | .BR mbrtowc () | |
124 | function | |
40aa0db0 MK |
125 | puts |
126 | .I *ps | |
127 | in the initial state and returns 0. | |
fea681da | 128 | .PP |
40aa0db0 MK |
129 | In all of the above cases, if |
130 | .I ps | |
b437fdd9 | 131 | is NULL, a static anonymous |
a692b189 MK |
132 | state known only to the |
133 | .BR mbrtowc () | |
134 | function is used instead. | |
40aa0db0 | 135 | Otherwise, |
51700fd7 | 136 | .IR *ps |
40aa0db0 MK |
137 | must be a valid |
138 | .I mbstate_t | |
139 | object. | |
140 | An | |
51700fd7 | 141 | .IR mbstate_t |
40aa0db0 MK |
142 | object |
143 | .I a | |
144 | can be initialized to the initial state | |
fea681da | 145 | by zeroing it, for example using |
bdd915e2 | 146 | .PP |
a6e2f128 | 147 | .in +4n |
b9c93deb | 148 | .EX |
fea681da | 149 | memset(&a, 0, sizeof(a)); |
bdd915e2 | 150 | .EE |
a6e2f128 | 151 | .in |
47297adb | 152 | .SH RETURN VALUE |
60a90ecd MK |
153 | The |
154 | .BR mbrtowc () | |
155 | function returns the number of bytes parsed from the | |
40aa0db0 MK |
156 | multibyte sequence starting at |
157 | .IR s , | |
158 | if a non-L\(aq\\0\(aq wide character | |
fea681da | 159 | was recognized. |
f81fb444 | 160 | It returns 0, if a L\(aq\\0\(aq wide character was recognized. |
7d2cb9d5 | 161 | It returns |
009df872 | 162 | .I (size_t)\ \-1 |
40aa0db0 MK |
163 | and sets |
164 | .I errno | |
165 | to | |
166 | .BR EILSEQ , | |
167 | if an invalid multibyte sequence was | |
c13182ef | 168 | encountered. |
40aa0db0 | 169 | It returns |
51700fd7 | 170 | .I "(size_t)\ \-2" |
40aa0db0 MK |
171 | if it couldn't parse a complete multibyte |
172 | character, meaning that | |
173 | .I n | |
174 | should be increased. | |
1ad7b089 | 175 | .SH ATTRIBUTES |
5cf6a734 PH |
176 | For an explanation of the terms used in this section, see |
177 | .BR attributes (7). | |
178 | .TS | |
179 | allbox; | |
180 | lb lb lb | |
181 | l l l. | |
182 | Interface Attribute Value | |
183 | T{ | |
1ad7b089 | 184 | .BR mbrtowc () |
5cf6a734 PH |
185 | T} Thread safety MT-Unsafe race:mbrtowc/!ps |
186 | .TE | |
47297adb | 187 | .SH CONFORMING TO |
c4576455 | 188 | POSIX.1-2001, POSIX.1-2008, C99. |
fea681da | 189 | .SH NOTES |
d9bfdb9c | 190 | The behavior of |
60a90ecd | 191 | .BR mbrtowc () |
1274071a MK |
192 | depends on the |
193 | .B LC_CTYPE | |
194 | category of the | |
fea681da | 195 | current locale. |
47297adb | 196 | .SH SEE ALSO |
9247e95b | 197 | .BR mbsinit (3), |
e37e3282 | 198 | .BR mbsrtowcs (3) |