Standard C Library Functions                        mbsrtowcs(3C)



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

SYNOPSIS
     #include 

     sizet mbsrtowcs(wchart *restrict dst, const char **restrict src,
          sizet len, mbstatet *restrict 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 continues 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 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 mbsrtowcs().






SunOS 5.11           Last change: 1 Nov 2003                    1






Standard C Library Functions                        mbsrtowcs(3C)



     The behavior of this function is affected  by  the  LCTYPE
     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 (sizet)-1; the conversion
     state is undefined.  Otherwise, it  returns  the  number  of
     characters  successfully  converted,  not including the ter-
     minating null (if any).

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


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
     mbrtowc(3C),  mbsinit(3C),   setlocale(3C),   attributes(5),
     environ(5), standards(5)

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







SunOS 5.11           Last change: 1 Nov 2003                    2