mbsrtowcs(3C)

NAME

     mbsrtowcs - convert a character string to  a  wide-character
     string (restartable)

SYNOPSIS

     #include <wchar.h>

     size_t mbsrtowcs(wchar_t *dst, const char **src, size_t len,
     mbstate_t *ps);

DESCRIPTION

     The mbsrtowcs() function converts a sequence of  characters,
     beginning  in  the  conversion state described by the object
     pointed to by ps, from the array indirectly  pointed  to  by
     src  into  a  sequence of corresponding wide-characters.  If
     dst is not a null  pointer,  the  converted  characters  are
     stored into the array pointed to by  dst. Conversion contin-
     ues up to and including a terminating null character,  which
     is  also  stored.   Conversion  stops early in either of the
     following cases:

        o  When a sequence of bytes is encountered that does  not
           form a valid character.

        o  When len codes have been stored into the array pointed
           to by dst (and  dst is not a null pointer).

     Each conversion takes place as if by a call to the mbrtowc()
     function.

     If dst is not a null pointer, the pointer object pointed  to
     by  src  is  assigned  either  a null pointer (if conversion
     stopped due to reaching a terminating null character) or the
     address just past the last character converted (if any).  If
     conversion stopped due to reaching a terminating null  char-
     acter, and if dst is not a null pointer, the resulting state
     described is the initial conversion state.

     If ps is a null pointer, the mbsrtowcs() function  uses  its
     own  internal mbstate_t object, which is initialized at pro-
     gram startup to the initial  conversion  state.   Otherwise,
     the  mbstate_t object pointed to by ps is used to completely
     describe the current  conversion  state  of  the  associated
     character  sequence.  Solaris  will behave as if no function
     defined in the Solaris Reference Manual calls mbsrtowcs().

     The behavior of this function is affected  by  the  LC_CTYPE
     category of the current locale.  See environ(5).

RETURN VALUES

     If the input conversion encounters a sequence of bytes  that
     do not form a valid character, an encoding error occurs.  In
     this case, the mbsrtowcs() function stores the value of  the
     macro EILSEQ in errno and returns (size_t)-1; the conversion
     state is undefined.  Otherwise, it  returns  the  number  of
     characters  successfully  converted,  not including the ter-
     minating null (if any).

ERRORS

     The mbsrtowcs() function may fail if:

     EINVAL
           The ps argument points to an object that  contains  an
           invalid conversion state.

     EILSEQ
           Invalid character sequence is detected.

ATTRIBUTES

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | See NOTES below             |
    |_____________________________|_____________________________|

SEE ALSO

     mbrtowc(3C),  mbsinit(3C),   setlocale(3C),   attributes(5),
     environ(5)

NOTES

     If ps is not a null pointer, mbsrtowcs() uses the  mbstate_t
     object  pointed to by ps and the function can be used safely
     in multithreaded applications, as long as  setlocale(3C)  is
     not  being  called  to  change  the  locale. If ps is a null
     pointer, mbsrtowcs() uses its internal mbstate_t object  and
     the function is Unsafe in multithreaded applications.