mbsrtowcs - converts a multibyte character string to a wide character
Standard C Library (libc, -lc)
mbsrtowcs(wchar_t * restrict pwcs, const char ** restrict s, size_t n,
mbstate_t * restrict ps);
The mbsrtowcs() converts the multibyte character string indirectly
pointed by s to the corresponding wide character string, and stores it to
the array pointed by pwcs. The conversion stops due to the following
+o The conversion reaches a null byte. In this case, the null byte is
+o The mbsrtowcs() has already stored n wide characters.
+o The conversion encounters an invalid character.
Each characters will be converted as if mbrtowc(3) is continuously
After conversion, if pwcs is not NULL pointer, the pointer object pointed
by s is NULL pointer (if the conversion is stopped due to reach a null
byte) or the first byte of the character just after the last character
If pwcs is not null pointer and the conversion is stopped due to reach a
null byte, the mbsrtowcs() places the state object pointed by ps to an
initial state after the conversion is taken place.
The behaviour of the mbsrtowcs() is affected by LC_CTYPE category of the
There are special cases:
s == NULL || *s == NULL
undefined (may causes the program to crash).
pwcs == NULL The conversion is taken place, but the result wide character
string is discarded. In this case, the pointer object
pointed by s is not modified and n is ignored.
ps == NULL The mbsrtowcs() uses its own internal state object to keep
the conversion state, instead of ps mentioned in this manual
Calling any other functions in the Standard C Library
(libc, -lc) never change the internal state of the
mbsrtowcs(), that is initialized at startup time of the
The mbsrtowcs() returns
0 or positive
The value returned is the number of elements stored to the
array pointed by pwcs, except for a terminate null wide
character (if any). If pwcs is not null and the value
returned is equal to n, the wide character string pointed
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 terminate null wide
(size_t)-1 The array indirectly pointed by s contains a byte sequence
forming invalid character. In this case, the mbsrtowcs()
sets errno to indicate the error.
The mbsrtowcs() may causes an error in the following case:
[EILSEQ] The pointer pointed by s points an invalid or incomplete
[EINVAL] ps points an invalid or uninitialized mbstate_t
mbrtowc(3), mbstowcs(3), setlocale(3)
The mbsrtowcs() function conforms to . The restrict qualifier is added
BSD February 4, 2002 BSD
[ Back ]