c/string/multibyte/mbrtoc32

Converts a single code point from its narrow multibyte character representation to its variable-length 32-bit wide character representation (but typically, UTF-32).

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 32-bit wide character and stores it in  (if  is not null).

If the multibyte character in corresponds to a multi-char32_t sequence (not possible with UTF-32), then after the first call to this function,  is updated in such a way that the next calls to  will write out the additional char32_t, without considering.

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

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

If the macro is defined, the 32-bit encoding used by this function is UTF-32; 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 from a multi- character has now been written to . No bytes are processed from the input in this case.
 * 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 unspecified.