NAME

mbtowc - converts a multibyte character to a wide character

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS



int mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n)

DESCRIPTION

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:

s == NULL
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.

pwc == NULL
mbtowc() executes the conversion as if pwc is non-NULL, but a result of the conversion is discarded.

n == 0
In this case, the first n bytes of the array pointed to by s never form a complete character. Thus, the mbtowc() always fails.

RETURN VALUES

Normally, the mbtowc() returns:

0
s points to a nul byte (`\0').

positive
Number of bytes for the valid multibyte character pointed to by s. There are no cases that the value returned is greater than the value of the MB_CUR_MAX macro.

-1
s points to an invalid or an incomplete multibyte character. The mbtowc() also sets errno to indicate the error.

When s is equal to NULL, mbtowc() returns:

0
The current encoding is state-independent.

non-zero
The current encoding is state-dependent.

ERRORS

mbtowc() may cause an error in the following case:

[EILSEQ]
s points to an invalid or incomplete multibyte character.

SEE ALSO

mblen(3), mbrtowc(3), setlocale(3)

STANDARDS

The mbtowc() function conforms to ANSI X3.159-1989 (``ANSI C89'') . The restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99'') .