Converts a wide character to a multibyte character

#include <wchar.h>
size_t wcrtomb ( char restrict *dest , wchar_t wc ,
                mbstate_t * restrict state  );

The wcrtomb( ) function is the restartable version of wctomb( ). The third argument is a pointer to a variable with type mbstate_t, which holds the current parse state of a multibyte string being formed in the buffer that the first argument by successive function calls. Each call to wcrtomb( ) converts a wide character into a multibyte character, and stores the result in the buffer pointed to by its first argument. The return value indicates the number of bytes written to the output buffer. The maximum number of bytes that wcrtomb( ) writes to the buffer is the value of MB_CUR_MAX. wcrtomb( ) also updates the state variable referenced by the third argument to represent the new parse state of the string written. The locations that wcrtomb( ) reads from and writes to using its restricted pointer parameters must not overlap.

If the wide character is the null character (L'\0'), then wcrtomb( ) writes to the buffer a shift sequence, if necessary, to restore the multibyte string to the initial parse state, then writes a null character. The state variable is updated to represent the initial state. If the second argument is not a valid wide character, wcrtomb( ) returns -1, sets the errno variable to EILSEQ, and leaves the parse state variable in an undefined state. If the first argument is a null pointer, then wcrtomb( ) only sets the state variable to represent the initial state. The return value is then the number of bytes that would have been written to the output buffer.

Example

See the example for mbrtowc( ) in this chapter.

See Also

wctomb( ), mbrtowc( ), wctob( ), and btowc( ); wcsrtombs( ), wcstombs( ), and mbstowcs( )