Debian Codegraph @

upstream/debian-unstable/man3/mbrtowc.3

raw
1 '\" t
2 .\" Copyright, Bruno Haible <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH mbrtowc 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mbrtowc \- convert a multibyte sequence to a wide character
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <wchar.h>
16 .P
17 .BR "size_t mbrtowc(" "size_t n;"
18 .BI " wchar_t *restrict " pwc ", const char " s "[restrict " n ],
19 .BI " size_t " n ", mbstate_t *restrict " ps );
20 .fi
21 .SH DESCRIPTION
22 The main case for this function is when
23 .I s
24 is not NULL and
25 .I pwc
26 is
27 not NULL.
28 In this case, the
29 .BR mbrtowc ()
30 function inspects at most
31 .I n
32 bytes of the multibyte string starting at
33 .IR s ,
34 extracts the next complete
35 multibyte character, converts it to a wide character and stores it at
36 .IR *pwc .
37 It updates the shift state
38 .IR *ps .
39 If the converted wide
40 character is not L\[aq]\[rs]0\[aq] (the null wide character),
41 it returns the number of bytes that were consumed
42 from
43 .IR s .
44 If the converted wide character is L\[aq]\[rs]0\[aq], it resets the shift
45 state
46 .I *ps
47 to the initial state and returns 0.
48 .P
49 If the
50 .I n
51 bytes starting at
52 .I s
53 do not contain a complete multibyte
54 character,
55 .BR mbrtowc ()
56 returns
57 .IR "(size_t)\ \-2" .
58 This can happen even if
59 .I n
60 >=
61 .IR MB_CUR_MAX ,
62 if the multibyte string contains redundant shift
63 sequences.
64 .P
65 If the multibyte string starting at
66 .I s
67 contains an invalid multibyte
68 sequence before the next complete character,
69 .BR mbrtowc ()
70 returns
71 .I (size_t)\ \-1
72 and sets
73 .I errno
74 to
75 .BR EILSEQ .
76 In this case,
77 the effects on
78 .I *ps
79 are undefined.
80 .P
81 A different case is when
82 .I s
83 is not NULL but
84 .I pwc
85 is NULL.
86 In this case, the
87 .BR mbrtowc ()
88 function behaves as above, except that it does not
89 store the converted wide character in memory.
90 .P
91 A third case is when
92 .I s
93 is NULL.
94 In this case,
95 .I pwc
96 and
97 .I n
98 are
99 ignored.
100 If the conversion state represented by
101 .I *ps
102 denotes an
103 incomplete multibyte character conversion, the
104 .BR mbrtowc ()
105 function
106 returns
107 .IR "(size_t)\ \-1" ,
108 sets
109 .I errno
110 to
111 .BR EILSEQ ,
112 and
113 leaves
114 .I *ps
115 in an undefined state.
116 Otherwise, the
117 .BR mbrtowc ()
118 function
119 puts
120 .I *ps
121 in the initial state and returns 0.
122 .P
123 In all of the above cases, if
124 .I ps
125 is NULL, a static anonymous
126 state known only to the
127 .BR mbrtowc ()
128 function is used instead.
129 Otherwise,
130 .I *ps
131 must be a valid
132 .I mbstate_t
133 object.
134 An
135 .I mbstate_t
136 object
137 .I a
138 can be initialized to the initial state
139 by zeroing it, for example using
140 .P
141 .in +4n
142 .EX
143 memset(&a, 0, sizeof(a));
144 .EE
145 .in
146 .SH RETURN VALUE
147 The
148 .BR mbrtowc ()
149 function returns the number of bytes parsed from the
150 multibyte sequence starting at
151 .IR s ,
152 if a non-L\[aq]\[rs]0\[aq] wide character
153 was recognized.
154 It returns 0, if a L\[aq]\[rs]0\[aq] wide character was recognized.
155 It returns
156 .I (size_t)\ \-1
157 and sets
158 .I errno
159 to
160 .BR EILSEQ ,
161 if an invalid multibyte sequence was
162 encountered.
163 It returns
164 .I "(size_t)\ \-2"
165 if the consumed
166 .I n
167 bytes form a valid partial character sequence;
168 more subsequent data needs to be fed in.
169 .SH ATTRIBUTES
170 For an explanation of the terms used in this section, see
171 .BR attributes (7).
172 .TS
173 allbox;
174 lbx lb lb
175 l l l.
176 Interface Attribute Value
177 T{
178 .na
179 .nh
180 .BR mbrtowc ()
181 T} Thread safety MT-Unsafe race:mbrtowc/!ps
182 .TE
183 .SH STANDARDS
184 C11, POSIX.1-2008.
185 .SH HISTORY
186 POSIX.1-2001, C99.
187 .SH NOTES
188 The behavior of
189 .BR mbrtowc ()
190 depends on the
191 .B LC_CTYPE
192 category of the
193 current locale.
194 .SH SEE ALSO
195 .BR mbsinit (3),
196 .BR mbsrtowcs (3)