NAME    [Toc]    [Back]

     wcrtomb - converts a wide character to a multibyte character
     (restartable)

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <wchar.h>

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

DESCRIPTION    [Toc]    [Back]

     The wcrtomb() converts the wide character given by wc to the corresponding
 multibyte character, and stores it to the array pointed by s unless s
     is null pointer.  This function will modify the first at most MB_CUR_MAX
     bytes of the array pointed by s.

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

     There are the special cases:

     wc == 0       For state-dependent encodings, the wcrtomb() stores a null
                   byte preceded by special byte sequence (if any) to back to
                   a initial state to the array pointed by s, and the state
                   object pointed by ps also back to a initial state.

     s == NULL     The wcrtomb() just places ps into a initial state.  It is
                   equivalent to the following call:

                   wcrtomb(buf, L'\0', ps);

                   Here, buf is a dummy buffer.  In this case, wc is ignored.

     ps == NULL    The mbrtowc() uses its own internal state object to keep
                   the conversion state, instead of ps mentioned in this manual
 page.

                   Calling any other functions in the Standard C Library
                   (libc, -lc) never change the internal state of the
                   mbrtowc(), that is initialized at startup time of the program.

RETURN VALUES    [Toc]    [Back]

     The wcrtomb() returns

     positive      The number of bytes (including any shift sequences) which
                   is stored in the array.

     (size_t)-1    wc is not valid wide character.  In this case, the
                   wcrtomb() also sets errno to indicate error.

ERRORS    [Toc]    [Back]

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

     [EILSEQ]           wc is not valid wide character.

     [EINVAL]           ps points an invalid or uninitialized mbstate_t
                        object.

SEE ALSO    [Toc]    [Back]

     setlocale(3), wctomb(3)

STANDARDS    [Toc]    [Back]

     The wcrtomb() function conforms to .  The restrict qualifier is added at
     .

BSD                            February 4, 2002                            BSD