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