The
mbrtowc() usually converts the multibyte character pointed to by
s to a wide character, and stores the wide character to the wchar_t object pointed to by
pwc if
pwc is non-
NULL and
s points to a valid character. The conversion happens in accordance with, and changes the conversion state described in the mbstate_t object pointed to by
ps. This function may examine at most
n bytes of the array beginning from
s.
If
s points to a valid character and the character corresponds to a nul wide character, then the
mbrtowc() places the mbstate_t object pointed to by
ps to an initial conversion state.
Unlike
mbtowc(3), the
mbrtowc() may accept the byte sequence pointed to by
s not forming a complete multibyte character but which may be part of a valid character. In this case, this function will accept all such bytes and save them into the conversion state object pointed to by
ps. They will be used at subsequent calls of this function to restart the conversion suspended.
The behaviour of
mbrtowc() is affected by the
LC_CTYPE category of the current locale.
These are the special cases:
s == NULL
mbrtowc() sets the conversion state object pointed to by
ps to an initial state and always returns 0. Unlike
mbtowc(3), the value returned does not indicate whether the current encoding of the locale is state-dependent.
In this case,
mbrtowc() ignores
pwc and
n, and is equivalent to the following call:
mbrtowc(NULL, "", 1, ps);
pwc == NULL
The conversion from a multibyte character to a wide character has taken place and the conversion state may be affected, but the resulting wide character is discarded.
ps == NULL
mbrtowc() uses its own internal state object to keep the conversion state, instead of
ps mentioned in this manual page.
Calling any other functions in
Standard C Library (libc, -lc) never changes the internal state of
mbrtowc(), which is initialized at startup time of the program.