1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
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.
10 .\" References consulted:
11 .\" GNU glibc-2 source code and manual
12 .\" Dinkumware C library reference http://www.dinkumware.com/
13 .\" OpenGroup's Single UNIX specification
14 .\" http://www.UNIX-systems.org/online.html
17 .TH MBRTOWC 3 2019-03-06 "GNU" "Linux Programmer's Manual"
19 mbrtowc \- convert a multibyte sequence to a wide character
24 .BI "size_t mbrtowc(wchar_t *" pwc ", const char *" s ", size_t " n \
28 The main case for this function is when
36 function inspects at most
38 bytes of the multibyte string starting at
40 extracts the next complete
41 multibyte character, converts it to a wide character and stores it at
43 It updates the shift state
46 character is not L\(aq\e0\(aq (the null wide character),
47 it returns the number of bytes that were consumed
50 If the converted wide character is L\(aq\e0\(aq, it resets the shift
53 to the initial state and returns 0.
59 do not contain a complete multibyte
64 This can happen even if
68 if the multibyte string contains redundant shift
71 If the multibyte string starting at
73 contains an invalid multibyte
74 sequence before the next complete character,
87 A different case is when
94 function behaves as above, except that it does not
95 store the converted wide character in memory.
106 If the conversion state represented by
109 incomplete multibyte character conversion, the
113 .IR "(size_t)\ \-1" ,
121 in an undefined state.
127 in the initial state and returns 0.
129 In all of the above cases, if
131 is NULL, a static anonymous
132 state known only to the
134 function is used instead.
144 can be initialized to the initial state
145 by zeroing it, for example using
149 memset(&a, 0, sizeof(a));
155 function returns the number of bytes parsed from the
156 multibyte sequence starting at
158 if a non-L\(aq\e0\(aq wide character
160 It returns 0, if a L\(aq\e0\(aq wide character was recognized.
167 if an invalid multibyte sequence was
171 if it couldn't parse a complete multibyte
172 character, meaning that
176 For an explanation of the terms used in this section, see
182 Interface Attribute Value
185 T} Thread safety MT-Unsafe race:mbrtowc/!ps
188 POSIX.1-2001, POSIX.1-2008, C99.