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 http://www.UNIX-systems.org/online.html
16 .TH MBTOWC 3 2021-03-22 "GNU" "Linux Programmer's Manual"
18 mbtowc \- convert a multibyte sequence to a wide character
21 .B #include <stdlib.h>
23 .BI "int mbtowc(wchar_t *restrict " pwc ", const char *restrict " s \
27 The main case for this function is when
35 function inspects at most
37 bytes of the multibyte string starting at
39 extracts the next complete
40 multibyte character, converts it to a wide character and stores it at
42 It updates an internal shift state known only to the
47 does not point to a null byte (\(aq\e0\(aq), it returns the number
48 of bytes that were consumed from
50 otherwise it returns 0.
56 do not contain a complete multibyte
57 character, or if they contain an invalid multibyte sequence,
60 This can happen even if
64 if the multibyte string contains redundant shift sequences.
66 A different case is when
73 function behaves as above, except that it does not
74 store the converted wide character in memory.
88 .\" The Dinkumware doc and the Single UNIX specification say this, but
89 .\" glibc doesn't implement this.
90 resets the shift state, only known to this function,
91 to the initial state, and
92 returns nonzero if the encoding has nontrivial shift state, or zero if the
93 encoding is stateless.
99 function returns the number of
100 consumed bytes starting at
104 points to a null byte,
112 returns nonzero if the encoding
113 has nontrivial shift state, or zero if the encoding is stateless.
115 For an explanation of the terms used in this section, see
123 Interface Attribute Value
126 T} Thread safety MT-Unsafe race
132 POSIX.1-2001, POSIX.1-2008, C99.
141 This function is not multithread safe.
145 a better interface to the same functionality.