The mbstowcs function

Name

mbstowcs -- 

Synopsis

#include <stdlib.h>

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

Description

The mbstowcs function converts a sequence of multi-byte characters that begin the initial shift state from the array pointed to by s into a sequence of corresponding codes and stores not more than n codes into the array pointed to by pwcs. No multi-byte characters that follow a null character (which is converted into a code with value zero) will be examined or converted. Each multi-byte character is converted as if by a call to the mbtowc function, except the shift state of the mbtowc function is not affected.

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

Returns

If an invalid multi-byte character is encountered, the mbstowcs function returns (size_t) -1. Otherwise the mbstowcs function returns the number of array elements modified, not including a terminating zero code, if any.

See Also

The mbtowc function.

Implementation Notes

The mbstowcs function behaves like strncpy.