cpp/string/multibyte/mbrtowc

Converts a narrow multibyte character to a wide character.

If is not a null pointer, inspects at most  bytes of the multibyte character string, beginning with the byte pointed to by  to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences). If the function determines that the next multibyte character in is complete and valid, converts it to the corresponding wide character and stores it in  (if  is not null).

If is a null pointer, the values of  and  are ignored and call is equivalent to.

If the wide character produced is the null character, the conversion state stored in is the initial shift state.

Return value
The first of the following that applies:
 * if the character converted from (and stored in  if non-null) was the null character.
 * the number of bytes of the multibyte character successfully converted from.
 * if the next bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to.
 * if encoding error occurs. Nothing is written to, the value eilseq is stored in errno and the value of is left unspecified.