WCSTOMBS(3)        Linux Programmer's Manual        WCSTOMBS(3)





NAME
       wcstombs  -  convert a wide character string to a multi-
       byte string

SYNOPSIS
       #include <stdlib.h>

       size_t wcstombs (char* dest, const wchar_t* src, size_t n);

DESCRIPTION
       If dest is not a NULL  pointer,  the  wcstombs  function
       converts  the  wide-character  string src to a multibyte
       string starting at dest. At most n bytes are written  to
       dest.  The  conversion  starts in the initial state. The
       conversion can stop for three reasons:

       1. A wide character has been encountered that can not be
       represented  as  a  multibyte sequence (according to the
       current locale). In this case (size_t)(-1) is  returned.

       2. The length limit forces a stop. In this case the num-
       ber of bytes written to dest is returned, but the  shift
       state at this point is lost.

       3.  The  wide-character  string has been completely con-
       verted, including the terminating L'\0'.  In  this  case
       the conversion ends in the initial state.  The number of
       bytes written to dest, excluding  the  terminating  '\0'
       byte, is returned.

       The  programmer  must  ensure  that there is room for at
       least n bytes at dest.

       If dest is NULL, n is ignored, and the  conversion  pro-
       ceeds  as above, except that the converted bytes are not
       written out to memory, and that no length limit  exists.

       In  order  to  avoid  the  case  2 above, the programmer
       should  make   sure   n   is   greater   or   equal   to
       wcstombs(NULL,src,0)+1.

RETURN VALUE
       The  wcstombs  function returns the number of bytes that
       make up the converted part of  multibyte  sequence,  not
       including  the terminating null byte.  If a wide charac-
       ter  was  encountered  which  could  not  be  converted,
       (size_t)(-1) is returned.

CONFORMING TO
       ISO/ANSI C, UNIX98

SEE ALSO
       wcsrtombs(3)

NOTES
       The  behaviour of wcstombs depends on the LC_CTYPE cate-
       gory of the current locale.

       The function wcsrtombs provides a  better  interface  to
       the same functionality.



GNU                      July 25, 1999              WCSTOMBS(3)
