converts a multibyte character string
to a wide-character string
* restrict pwcs, const
char * restrict s, size_t
converts a null-terminated multibyte character string pointed to by
s to the corresponding wide-character string and
stores up to n wide characters in the array pointed to
by pwcs. Each character will be converted as if
is continuously called, except the internal state of
will not be affected.
For state-dependent encoding,
implies the multibyte character string pointed to by s
always begin with an initial state.
These are the special cases:
- pwcs == NULL
mbstowcs() returns the number of elements to store the whole wide-character string corresponding to the multibyte character string pointed to by s. In this case, n is ignored.
- s == NULL
- Undefined (may cause the program to crash).
- 0 or positive
- The value returned is the number of elements stored in the array pointed to by pwcs, except for a terminating null wide character (if any). If pwcs is not null and the value returned is equal to n, the wide-character string pointed to by pwcs is not null terminated. If pwcs is a null pointer, the value returned is the number of elements to contain the whole string converted, except for a terminating null wide character.
- The array indirectly pointed to by s contains a byte
sequence forming invalid character. In this case,
mbstowcs() sets errno to indicate the error.
mbstowcs() may cause an error in the
- s points to the string containing invalid or incomplete multibyte character.
mbstowcs() function conforms to
ANSI X3.159-1989 (“ANSI C89”).
The restrict qualifier is added at ISO/IEC 9899/199 (“ISO