c/string/multibyte/mbrtowc

Converts a narrow multibyte character to its wide character representation.

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, and taking into account the current multibyte conversion state ). 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.

If the environment macro is defined, the values of type  are the same as the short identifiers of the characters in the Unicode required set (typically UTF-32 encoding); otherwise, it is implementation-defined. In any case, the multibyte character encoding used by this function is specified by the currently active C locale.

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.