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.