mbstowcs(3C)

NAME

     mbstowcs - convert a character string  to  a  wide-character
     string

SYNOPSIS

     #include <stdlib.h>

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

DESCRIPTION

     The mbstowcs() function converts a  sequence  of  characters
     from   the  array  pointed  to  by  s  into  a  sequence  of
     corresponding wide-character codes and stores not more  than
     n wide-character codes into the array pointed to by pwcs. No
     characters that follow a null byte (which is converted  into
     a wide-character code with value 0) will be examined or con-
     verted. Each character is converted  as  if  by  a  call  to
     mbtowc(3C).

     No more than n  elements  will  be  modified  in  the  array
     pointed  to  by pwcs. If copying takes place between objects
     that overlap, the behavior is undefined.

     The behavior of this function is affected  by  the  LC_CTYPE
     category  of  the current locale. If pwcs is a null pointer,
     mbstowcs() returns the length required to convert the entire
     array  regardless  of  the  value  of  n,  but no values are
     stored.

RETURN VALUES

     If an invalid character is encountered,  mbstowcs()  returns
     (size_t)-1  and  may set errno to indicate the error. Other-
     wise, mbstowcs() returns the number of  the  array  elements
     modified (or required if pwcs is NULL), not including a ter-
     minating 0 code,  if  any.  The  array  will  not  be  zero-
     terminated if the value returned is n.

ERRORS

     The mbstowcs() function may fail if:

     EILSEQ
           Invalid byte sequence is detected.

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | CSI                         | Enabled                     |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO

     mblen(3C),    mbtowc(3C),    setlocale(3C),    wcstombs(3C),
     wctomb(3C), attributes(5), standards(5)