Debian Codegraph @

upstream/debian-trixie/man3/mbrtowc.3

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