mbstowcs - converts a multibyte character string to a wide character
Standard C Library (libc, -lc)
mbstowcs(wchar_t * restrict pwcs, const char * restrict s, size_t n);
The mbstowcs() converts a null-terminated multibyte character string
pointed by s to the corresponding wide character string and stores it to
the array pointed by pwcs. This function may modify the first at most n
elements of the array pointed by pwcs. Each characters will be converted
as if mbtowc(3) is continuously called, except the internal state of
mbtowc(3) will not be affected.
For state-dependent encoding, the mbstowcs() implies the multibyte character
string pointed by s always to begin with an initial state.
There are special cases:
pwcs == NULL The mbstowcs() returns the number of elements to store the
whole wide character string corresponding to the multibyte
character string pointed by s. In this case, n is ignored.
s == NULL undefined (may causes the program to crash).
The mbstowcs() returns:
0 or positive
Number of elements stored to the array pointed by pwcs.
There is no cases that the value returned is greater than n
(unless pwcs is a null pointer) or the value of MB_CUR_MAX
macro. If the return value is equal to n, the string
pointed by pwcs will not be null-terminated.
(size_t)-1 s points the string containing invalid or incomplete multibyte
character. The mbstowcs() also sets errno to indicate
The mbstowcs() may causes an error in the following case:
[EILSEQ] s points the string containing invalid or incomplete
The mbstowcs() function conforms to ANSI X3.159-1989 (``ANSI C''). The
restrict qualifier is added at .
BSD February 3, 2002 BSD
[ Back ]