wcstombs  - convert a wide character string to a multibyte
       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  con­
       verts  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 cur­
       rent locale). In this case (size_t)(-1) is returned.

       2. The length limit forces a stop. In this case the number
       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 proceeds
       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 character
       was encountered which could not be converted, (size_t)(-1)
       is returned.


CONFORMING TO

       ISO/ANSI C, UNIX98


SEE ALSO

       wcsrtombs(3)

       The behaviour of wcstombs depends on the LC_CTYPE category
       of the current locale.

       The function wcsrtombs provides a thread safe interface to
       the same functionality.


Man(1) output converted with man2html