NAME    [Toc]    [Back]

     mbstowcs - converts a multibyte character string to a wide character
     string

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <stdlib.h>

     size_t
     mbstowcs(wchar_t * restrict pwcs, const char * restrict s, size_t n);

DESCRIPTION    [Toc]    [Back]

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

RETURN VALUES    [Toc]    [Back]

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

ERRORS    [Toc]    [Back]

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

     [EILSEQ]           s points the string containing invalid or incomplete
                        multibyte character.

SEE ALSO    [Toc]    [Back]

     mbtowc(3), setlocale(3)

STANDARDS    [Toc]    [Back]

     The mbstowcs() function conforms to ANSI X3.159-1989 (``ANSI C'').  The
     restrict qualifier is added at .

BSD                            February 3, 2002                            BSD