mbrtowc - complete and convert multi-byte string to wide-character string

Syntax	#include <wchar.h> size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);
Description	If s is not a null pointer, mbrtowc() determines how many bytes (starting at the position pointed to by *s) are required to complete the next multi-byte character. Any Shift sequences are also taken into account. A maximum of the next n bytes are tested. If mbrtowc() can compete the multi-byte character, the corresponding wide character is determined and stored in *pwc as long as pwc is not a null pointer. If the corresponding wide character is the null character, the final state corresponds to the “initial conversion” state. If s is a null pointer, mbrtowc() corresponds to the call mbrtowc(NULL, "", 1, ps). In this case the parameters pwc and n are ignored.
Return val.	Depending on the current conversion state, mbrtowc() returns the value of the first condition of the following conditions that is met:
	0	if the next (maximum of n) bytes result in a valid multi-byte character that corresponds to the wide character “null”.
	Number of bytes required to complete the multi-byte character
		if the next (maximum of n) bytes result in a valid multi-byte character. The wide character corresponding to this multi-byte character is stored.
	(size_t)-2	if the next n bytes result in an incomplete, but potentially valid multi-byte character. No value is stored.
	(size_t)-1	if a coding error occurs, i.e. if the next (maximum of n) bytes do not result in a complete and valid multi-byte character. No value is stored an the value of the EILSEQ macro is written in errno. The conversion status is undefined.
Notes	In this version of the C runtime system, only 1-byte characters are supported as wide characters.
See also	mblen(), mbtowc(), wcstombs(), wctomb().