mbrtowc

size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

The function determines the number of bytes in a multibyte string that completes the next multibyte character, if possible.

If ps is not a null pointer, the conversion state for the multibyte string is assumed to be *ps. Otherwise, it is assumed to be &internal, where internal is an object of type mbstate_t internal to the mbrtowc function. At program startup, internal is initialized to the initial conversion state. No other library function alters the value stored in internal.

If s is not a null pointer, the function determines x, the number of bytes in the multibyte string s that complete or contribute to the next multibyte character. (x cannot be greater than n.) Otherwise, the function effectively returns mbrtowc(0, "", 1, ps), ignoring pwc and n. (The function thus returns zero only if the conversion state indicates that no incomplete multibyte character is pending from a previous call to mbrlen, mbrtowc, or mbsrtowcs for the same string and conversion state.)

If pwc is not a null pointer, the function converts a completed multibyte character to its corresponding wide-character value and stores that value in *pwc.

The function returns:

• (size_t)-2 if, after converting all n characters, the resulting conversion state indicates an incomplete multibyte character.
• (size_t)-1 if the function detects an encoding error before completing the next multibyte character, in which case the function stores the value EILSEQ in errno and leaves the resulting conversion state undefined.
• Zero, if the next completed character is a null character, in which case the resulting conversion state is the initial conversion state.
• x, the number of bytes needed to complete the next muitibyte character, in which case the resulting conversion state indicates that x bytes have been converted.