NAME
mbtowc, mbtowc_l
— convert a character to a
wide-character code
LIBRARY
library “libc”
SYNOPSIS
#include
<stdlib.h>
int
mbtowc(wchar_t * restrict
wcharp, const char * restrict mbchar,
size_t nbytes);
#include
<xlocale.h>
int
mbtowc_l(wchar_t * restrict
wcharp, const char * restrict mbchar,
size_t nbytes, locale_t
locale);
DESCRIPTION
Thembtowc()
and mbtowc_l() functions convert a multibyte character
mbchar into a wide character according to the current
conversion state, and stores the result in the object pointed to by
wcharp. Up to nbytes bytes are
examined.
A call with a null mbchar pointer returns nonzero if the current encoding requires shift states, zero otherwise; if shift states are required, the shift state is reset to the initial state.
The
mbtowc_l()
function takes an explicit locale argument, whereas
the mbtowc() function uses the current global or
per-thread locale.
RETURN VALUES
If mbchar is NULL,
the mbtowc() and mbtowc_l()
functions return nonzero if shift states are supported, zero otherwise.
Otherwise, if mbchar is not a null pointer,
mbtowc() and mbtowc_l()
either return 0 if mbchar represents the null wide
character, or return the number of bytes processed in
mbchar, or return -1 if no multibyte character could
be recognized or converted. In this case, mbtowc()'s
and mbtowc_l()'s internal conversion states are
undefined.
ERRORS
The mbtowc() and
mbtowc_l() functions will fail if:
- [
EILSEQ] - An invalid multibyte sequence was detected.
- [
EINVAL] - The internal conversion state is invalid.
SEE ALSO
btowc(3), mbintowcr(3), mblen(3), mbrtowc(3), mbstowcs(3), multibyte(3), utf8towcr(3), wctomb(3), xlocale(3)
STANDARDS
The mbtowc() function conforms to
ISO/IEC 9899:1999
(“ISO C99”).