NAME    [Toc]    [Back]

     mbsrtowcs - converts a multibyte character string to a wide character
     string (restartable)

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <wchar.h>

     size_t
     mbsrtowcs(wchar_t * restrict pwcs, const char ** restrict s, size_t n,
             mbstate_t * restrict ps);

DESCRIPTION    [Toc]    [Back]

     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
     reasons:

     +o   The conversion reaches a null byte.  In this case, the null byte is
         also converted.

     +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
     called.

     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
     converted.

     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
     current locale.

     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
 page.

                   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
                   program.

RETURN VALUES    [Toc]    [Back]

     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
                   character.

     (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.

ERRORS    [Toc]    [Back]

     The mbsrtowcs() may causes an error in the following case:

     [EILSEQ]           The pointer pointed by s points an invalid or incomplete
 multibyte character.

     [EINVAL]           ps points an invalid or uninitialized mbstate_t
                        object.

SEE ALSO    [Toc]    [Back]

     mbrtowc(3), mbstowcs(3), setlocale(3)

STANDARDS    [Toc]    [Back]

     The mbsrtowcs() function conforms to .  The restrict qualifier is added
     at .

BSD                            February 4, 2002                            BSD