c/string/multibyte/mbsrtowcs

@1@ 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 mbrtowc. The conversion stops if: @2@ Same as, except that
 * The multibyte null character was converted and stored. is set to null pointer value 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.
 * the function returns its result as an out-parameter
 * if no null character was written to after  wide characters were written, then  is stored in, which means len+1 total wide characters are written
 * the function clobbers the destination array from the terminating null and until
 * If and  overlap, the behavior is unspecified.
 * the following errors are detected at runtime and call the currently installed constraint handler function:
 * ,, , or is a null pointer
 * or is greater than rsize_max/sizeof(wchar_t) (unless  is null)
 * is not zero (unless is null)
 * There is no null character in the first multibyte characters in the  array and  is greater than  (unless  is null)

Return value
@1@ 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. @2@ zero on success (in which case the number of wide characters excluding terminating zero that were, or would be written to, is stored in ), non-sero on error. In case of a runtime constraint violation, stores in  (unless  is null) and sets  to  (unless  is null or  is zero or greater than rsize_max)