Standard C Library Functions                        wcsrtombs(3C)



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

SYNOPSIS
     #include 

     sizet wcsrtombs(char *restrict dst,
          const wchart **restrict src, sizet len,
          mbstatet *restrict 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 mbstatet object, which is initialized at pro-
     gram startup to the initial  conversion  state.   Otherwise,
     the  mbstatet 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().




SunOS 5.11           Last change: 1 Nov 2003                    1






Standard C Library Functions                        wcsrtombs(3C)



     The behavior of this function is affected  by  the  LCTYPE
     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  (sizet)-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).

ERORS
     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  mbstatet
     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 mbstatet object  and
     the function is Unsafe in multithreaded applications.

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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Standard                    
    
     MT-Level                     See NOTES below             
    


SEE ALSO
     mbsinit(3C),  setlocale(3C),   wcrtomb(3C),   attributes(5),
     environ(5), standards(5)






SunOS 5.11           Last change: 1 Nov 2003                    2