MBTOWC(3)

NAME
mbtowc, mbtowc_l - convert a character to a wide-character code

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
The mbtowc() 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 isoC-99.