wcsrtombs(3C)

NAME

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

SYNOPSIS

     #include <wchar.h>

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

DESCRIPTION

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

        o  When a code is reached that does not correspond  to  a
           valid character.

        o  When the next character would exceed the limit of  len
           total  bytes  to  be stored in the array pointed to by
           dst (and dst is not a null pointer).

     Each conversion takes place as if by a call to the wcrtomb()
     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  wide-character)
     or  the address just  past the last wide-character converted
     (if any).  If conversion stopped due to reaching a terminat-
     ing  null  wide-character,  the resulting state described is
     the initial conversion state.

     If ps is a null pointer, the wcsrtombs() 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 wcsrtombs().

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

RETURN VALUES

     If conversion stops because a code is reached that does  not
     correspond  to  a valid character, an encoding error occurs.
     In this case, the wcsrtombs() 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  bytes  in  the resulting character sequence, not
     including the terminating null (if any).

ERRORS

     The wcsrtombs() function may fail if:

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

     EILSEQ
           A wide-character code does not correspond to  a  valid
           character.

USAGE

     If ps is not a null pointer, wcsrtombs() 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, wcsrtombs() uses its internal mbstate_t object  and
     the function is Unsafe in multithreaded applications.

ATTRIBUTES

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

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

SEE ALSO

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