MBTOWC(3) | Library Functions Manual | MBTOWC(3) |
mbtowc
—
#include <stdlib.h>
int
mbtowc
(wchar_t
* restrict pwc, const
char * restrict s, size_t
n);
mbtowc
() usually converts the multibyte character
pointed to by s to a wide character, and stores it in
the wchar_t object pointed to by pwc if
pwc is non-NULL
and
s points to a valid character. This function may inspect
at most n bytes of the array beginning from s.
In state-dependent encodings, s may point to
the special sequence bytes to change the shift-state. Although such sequence
bytes correspond to no individual wide-character code,
mbtowc
() changes its own state by the sequence bytes
and treats them as if they are a part of the subsequence multibyte
character.
Unlike mbrtowc(3), the first n bytes pointed to by s need to form an entire multibyte character. Otherwise, this function causes an error.
Calling any other functions in Standard
C Library (libc, -lc) never changes the internal state of
mbtowc
(), except for calling
setlocale(3) with changing
the LC_CTYPE
category of the current locale. Such
setlocale(3) call causes
the internal state of this function to be indeterminate.
The behaviour of mbtowc
() is affected by
the LC_CTYPE
category of the current locale.
There are special cases:
mbtowc
() initializes its own internal state to an
initial state, and determines whether the current encoding is
state-dependent. This function returns 0 if the encoding is
state-independent, otherwise non-zero. In this case,
pwc is completely ignored.mbtowc
() executes the conversion as if
pwc is non-NULL, but a result of the conversion is
discarded.mbtowc
() always fails.mbtowc
() returns:
MB_CUR_MAX
macro.mbtowc
() also sets
errno to indicate the error.When s is equal to
NULL
, mbtowc
() returns:
mbtowc
() may cause an error in the following case:
EILSEQ
]mbtowc
() function conforms to ANSI
X3.159-1989 (“ANSI C89”). The restrict qualifier
is added at ISO/IEC 9899:1999
(“ISO C99”).
February 3, 2002 | NetBSD 9.0 |