MBSRTOWCS(3) BSD Library Functions Manual MBSRTOWCS(3)
mbsrtowcs -- converts a multibyte character string to a wide-character string (restartable)
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 to by s to the
corresponding wide-character string, and stores it in the array pointed to by pwcs. The
conversion stops due to the following reasons:
o The conversion reaches a nul byte. In this case, the nul byte is also converted.
o The mbsrtowcs() has already stored n wide characters.
o The conversion encounters an invalid character.
Each character will be converted as if mbrtowc(3) is continuously called.
After conversion, if pwcs is not a null pointer, the pointer object pointed to by s is a
null pointer (if the conversion is stopped due to reaching a nul byte) or the first byte of
the character just after the last character converted.
If pwcs is not a null pointer and the conversion is stopped due to reaching a nul byte, the
mbsrtowcs() places the state object pointed to by ps to an initial state after the conver-
sion has taken place.
The behaviour of mbsrtowcs() is affected by the LC_CTYPE category of the current locale.
These are the special cases:
s == NULL || *s == NULL
Undefined (may cause the program to crash).
pwcs == NULL The conversion has taken place, but the resulting wide-character string was
discarded. In this case, the pointer object pointed to 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 page.
Calling any other functions in Standard C Library (libc, -lc) never changes
the internal state of mbsrtowcs(), which is initialized at startup time of the
0 or positive
The value returned is the number of elements stored in the array pointed to by
pwcs, except for a terminating nul 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 nul-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 nul wide character.
(size_t)-1 The array indirectly pointed to by s contains a byte sequence forming invalid
character. In this case, mbsrtowcs() sets errno to indicate the error.
mbsrtowcs() may cause an error in the following case:
[EILSEQ] The pointer pointed to by s points to an invalid or incomplete multibyte
[EINVAL] ps points to an invalid or uninitialized mbstate_t object.
mbrtowc(3), mbstowcs(3), setlocale(3)
The mbsrtowcs() function conforms to ISO/IEC 9899/AMD1:1995 (``ISO C90, Amendment 1''). The
restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99'').
BSD February 4, 2002 BSD