Debian Codegraph @

upstream/debian-unstable/man3/mbtowc.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 mbtowc 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mbtowc \- 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 <stdlib.h>
16 .P
17 .BR "int mbtowc(" "size_t size;"
18 .BI " wchar_t *restrict " pwc ", const char " s "[restrict " size ],
19 .BI " size_t " size );
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 mbtowc ()
30 function inspects at most
31 .I size
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 an internal shift state known only to the
38 .BR mbtowc ()
39 function.
40 If
41 .I s
42 does not point to a null byte (\[aq]\[rs]0\[aq]), it returns the number
43 of bytes that were consumed from
44 .IR s ,
45 otherwise it returns 0.
46 .P
47 If the
48 .I size
49 bytes starting at
50 .I s
51 do not contain a complete multibyte
52 character, or if they contain an invalid multibyte sequence,
53 .BR mbtowc ()
54 returns \-1.
55 This can happen even if
56 .I size
57 >=
58 .IR MB_CUR_MAX ,
59 if the multibyte string contains redundant shift sequences.
60 .P
61 A different case is when
62 .I s
63 is not NULL but
64 .I pwc
65 is NULL.
66 In this case, the
67 .BR mbtowc ()
68 function behaves as above, except that it does not
69 store the converted wide character in memory.
70 .P
71 A third case is when
72 .I s
73 is NULL.
74 In this case,
75 .I pwc
76 and
77 .I size
78 are
79 ignored.
80 The
81 .BR mbtowc ()
82 function
83 .\" The Dinkumware doc and the Single UNIX specification say this, but
84 .\" glibc doesn't implement this.
85 resets the shift state, only known to this function,
86 to the initial state, and
87 returns nonzero if the encoding has nontrivial shift state, or zero if the
88 encoding is stateless.
89 .SH RETURN VALUE
90 If
91 .I s
92 is not NULL, the
93 .BR mbtowc ()
94 function returns the number of
95 consumed bytes starting at
96 .IR s ,
97 or 0 if
98 .I s
99 points to a null byte,
100 or \-1 upon failure.
101 .P
102 If
103 .I s
104 is NULL, the
105 .BR mbtowc ()
106 function
107 returns nonzero if the encoding
108 has nontrivial shift state, or zero if the encoding is stateless.
109 .SH ATTRIBUTES
110 For an explanation of the terms used in this section, see
111 .BR attributes (7).
112 .TS
113 allbox;
114 lbx lb lb
115 l l l.
116 Interface Attribute Value
117 T{
118 .na
119 .nh
120 .BR mbtowc ()
121 T} Thread safety MT-Unsafe race
122 .TE
123 .SH VERSIONS
124 This function is not multithread safe.
125 The function
126 .BR mbrtowc (3)
127 provides
128 a better interface to the same functionality.
129 .SH STANDARDS
130 C11, POSIX.1-2008.
131 .SH HISTORY
132 POSIX.1-2001, C99.
133 .SH NOTES
134 The behavior of
135 .BR mbtowc ()
136 depends on the
137 .B LC_CTYPE
138 category of the
139 current locale.
140 .SH SEE ALSO
141 .BR MB_CUR_MAX (3),
142 .BR mblen (3),
143 .BR mbrtowc (3),
144 .BR mbstowcs (3),
145 .BR wcstombs (3),
146 .BR wctomb (3)