WCRTOMB(B)          Linux Programmer's Manual          WCRTOMB(B)



NAME
       wcrtomb - convert a wide character to a multibyte sequence

SYNOPSIS
       #include <wchar.h>

       size_t wcrtomb(char *s, wchar_t wc, mbstate_t *ps);

DESCRIPTION
       The main case for this function is when s is not NULL  and
       wc  is not L'\0'.  In this case, the wcrtomb function con-
       verts the wide character wc to its  multibyte  representa-
       tion and stores it at the beginning of the character array
       pointed to by s. It  updates  the  shift  state  *ps,  and
       returns  the length of said multibyte representation, i.e.
       the number of bytes written at s.

       A different case is when s is not NULL but wc is L'\0'. In
       this  case  the  wcrtomb  function stores at the character
       array pointed to by s the shift sequence needed  to  bring
       *ps back to the initial state, followed by a '\0' byte. It
       updates the shift state *ps (i.e. brings it into the  ini-
       tial  state), and returns the length of the shift sequence
       plus one, i.e. the number of bytes written at s.

       A third case is when  s  is  NULL.  In  this  case  wc  is
       ignored,   and   the  function  effectively  returns  wcr-
       tomb(buf,L'\0',ps) where  buf  is  an  internal  anonymous
       buffer.

       In  all  of  the  above  cases, if ps is a NULL pointer, a
       static anonymous state only known to the wcrtomb  function
       is used instead.

RETURN VALUE
       The wcrtomb function returns the number of bytes that have
       been or would have been written to the byte array at s. If
       wc can not be represented as a multibyte sequence (accord-
       ing to the current locale), (size_t)(-1) is returned,  and
       errno set to EILSEQ.

CONFORMING TO
       ISO/ANSI C, UNIX98

SEE ALSO
       wcsrtombs(s)

NOTES
       The  behaviour of wcrtomb depends on the LC_CTYPE category
       of the current locale.

       Passing NULL as ps is not multi-thread safe.



GNU                         1999-07-25                 WCRTOMB(B)