C in a Nutshell

Name

wcrtomb

Synopsis

Converts a wide character to a multibyte character

#include <wchar.h>
size_twcrtomb( 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 ...