cpp/string/multibyte/mbsrtowcs

Converts a null-terminated multibyte character sequence, which begins in the conversion state described by, from the array whose first element is pointed to by to its wide character representation. If is not null, converted characters are stored in the successive elements of the wchar_t array pointed to by. No more than wide characters are written to the destination array.

Each multibyte character is converted as if by a call to std. The conversion stops if:
 * The multibyte null character was converted and stored. is set to a null pointer and  represents the initial shift state.
 * An invalid multibyte character (according to the current C locale) was encountered. is set to point at the beginning  of the first unconverted multibyte character.
 * The next wide character to be stored would exceed . is set to point at the beginning of the first unconverted multibyte character. This condition is not checked if  is a null pointer.

Return value
On success, returns the number of wide characters, excluding the terminating, written to the character array. If is a null pointer, returns the number of wide characters that would have been written given unlimited length.

On conversion error (if invalid multibyte character was encountered), returns, stores eilseq in errno, and leaves in unspecified state.