Standard C Library Functions                          wcrtomb(3C)



NAME
     wcrtomb - convert a wide-character code to a character (res-
     tartable)

SYNOPSIS
     #include 

     sizet wcrtomb(char *restrict s, wchart wc, mbstatet *restrict ps);


DESCRIPTION
     If s is a null pointer, the wcrtomb() function is equivalent
     to the call:


     wcrtomb(buf, L'\0', ps)


     where buf is an internal buffer.


     If s is not a null pointer, the  wcrtomb()  function  deter-
     mines  the number of bytes needed to represent the character
     that corresponds to the wide-character given by wc  (includ-
     ing  any shift sequences), and stores the resulting bytes in
     the array whose first element is pointed to by  s.  At  most
     MBCURMAX  bytes  are  stored.   If  wc  is  a  null  wide-
     character, a null byte is  stored,  preceded  by  any  shift
     sequence  needed  to  restore  the  initial shift state. The
     resulting state described is the initial conversion state.


     If ps is a null pointer, the wcrtomb() function uses its own
     internal  mbstatet  object, which is initialized at program
     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 wcrtomb().


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

RETURN VALUES
     The wcrtomb() function returns the number of bytes stored in
     the  array  object (including any shift sequences).  When wc
     is not a valid wide-character, an encoding error occurs.  In
     this  case, the function stores the value of the macros EIL-
     SEQ in errno and returns (sizet)-1; the conversion state is
     undefined.




SunOS 5.11           Last change: 1 Nov 2003                    1






Standard C Library Functions                          wcrtomb(3C)



ERORS
     The wcrtomb() function may fail if:

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


     EILSEQ    Invalid wide-character code is detected.


USAGE
     If ps is not a null pointer, wcrtomb()  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, wcrtomb() 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),  attributes(5),   standards(5),
     environ(5)



















SunOS 5.11           Last change: 1 Nov 2003                    2