c/string/multibyte/mbstowcs

@1@ Converts a multibyte character string from the array whose first element is pointed to by to its wide character representation. Converted characters are stored in the successive elements of the array pointed to by. No more than wide characters are written to the destination array. @@ Each character is converted as if by a call to mbtowc, except that the mbtowc conversion state is unaffected. The conversion stops if: @@* The multibyte null character was converted and stored. @@* An invalid (in the current C locale) multibyte character was encountered. @@* The next wide character to be stored would exceed. @@If and  overlap, the behavior is undefined @2@ Same as, except that @@* conversion is as-if by mbrtowc, not mbtowc @@* 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 @@* if is a null pointer, the number of wide characters that would be produced is stored in @@* 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 destination array. On conversion error (if invalid multibyte character was encountered), returns. @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-zero 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)