wcstombs(3C)

NAME

     wcstombs - convert a wide-character string  to  a  character
     string

SYNOPSIS

     #include <stdlib.h>

     size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);

DESCRIPTION

     The wcstombs()  function  converts  the  sequence  of  wide-
     character  codes  from  the  array pointed to by pwcs into a
     sequence of characters and stores these characters into  the
     array  pointed to by s, stopping if a character would exceed
     the limit of n total bytes or if a null byte is stored. Each
     wide-character  code  is  converted  as  if  by  a  call  to
     wctomb(3C).

     The behavior of this function is affected  by  the  LC_CTYPE
     category of the current locale.

     No more than n bytes will be modified in the  array  pointed
     to  by  s. If copying takes place between objects that over-
     lap, the behavior is undefined. If  s  is  a  null  pointer,
     wcstombs() returns the length required to convert the entire
     array regardless of the  value  of  n,  but  no  values  are
     stored.

RETURN VALUES

     If a  wide-character  code  is  encountered  that  does  not
     correspond to a valid character (of one or more bytes each),
     wcstombs()  returns   (size_t)-1.    Otherwise,   wcstombs()
     returns  the  number of bytes stored in the character array,
     not including any terminating null byte. The array will  not
     be null-terminated if the value returned is n.

ERRORS

     The wcstombs() function may fail if:

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

ATTRIBUTES

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | MT-Level                    | MT-Safe                     |
    | CSI                         | Enabled                     |
    |_____________________________|_____________________________|

SEE ALSO

     mblen(3C),    mbstowcs(3C),    mbtowc(3C),    setlocale(3C),
     wctomb(3C), attributes(5)