NAME    [Toc]    [Back]

     wcstombs - converts a wide character string to a multibyte character
     string

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <stdlib.h>

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

DESCRIPTION    [Toc]    [Back]

     The wcstombs() converts the null-terminated wide character string pointed
     by pwcs to the corresponding multibyte character string, and store it to
     the array pointed by s.  This function may modify the first at most n
     bytes of the array pointed by s.  Each characters will be converted as if
     wctomb(3) is continuously called, except the internal state of wctomb(3)
     will not be affected.

     For state-dependent encoding, the wcstombs() implies the result multibyte
     character string pointed by s always to begin with an initial state.

     The behaviour of the wcstombs() is affected by LC_CTYPE category of the
     current locale.

     There are special cases:

     s == NULL     The wcstombs() returns the number of bytes to store the
                   whole multibyte character string corresponding to the wide
                   character string pointed by pwcs.  In this case, n is
                   ignored.

     pwcs == NULL  undefined (may causes the program to crash).

RETURN VALUES    [Toc]    [Back]

     The wcstombs() returns:

     0 or positive
                   number of bytes stored to the array pointed by s.  There is
                   no cases that the value returned is greater than n (unless
                   s is a null pointer).  If the return value is equal to n,
                   the string pointed by s will not be null-terminated.

     (size_t)-1    pwcs points the string containing invalid wide character.
                   The wcstombs() also sets errno to indicate the error.

ERRORS    [Toc]    [Back]

     The wcstombs() may causes an error in the following case:

     [EILSEQ]           pwcs points the string containing invalid wide character.

SEE ALSO    [Toc]    [Back]

     setlocale(3), wctomb(3)

STANDARDS    [Toc]    [Back]

     The wcstombs() function conforms to ANSI X3.159-1989 (``ANSI C'').  The
     restrict qualifier is added at .

BSD                            February 4, 2002                            BSD