size_t mbstowcs(wchar_t *pwcs,
                const char *s,
                size_t n);

mbstowcs converts a sequence of multi-byte characters that begins in the initial shift state from the array pointed to by s into a sequence of corresponding wide characters and stores not more than n wide characters into the array pointed to by pwcs.

No multi-byte characters that follow a null character (which is converted into a null wide character) will be examined or converted. Each multi-byte character is converted as if by a call to the mbtowc function, except that the conversion state of the mbtowc function is not affected.

No more than n elements will be modified in the array pointed to by pwcs. If copying takes place between objects that overlap, the behavior is undefined.

mbstowcs returns −1 if an invalid multi-byte character is encountered, otherwise mbstowcs returns the number of array elements modified (if any), not including a terminating null wide character.