Converts a wide character to the corresponding multibyte character and stores it in a specified location.

#include <stdlib.h>

int wcrtomb(char *mbchar, wchar_t wchar, mbstate_t *mbstate);

Parameters

mbchar

The address of a converted multibyte character.

wchar

A wide character to convert.

mbstate

A pointer to an mbstate_t object.

Remarks

The wcrtomb function converts a wide character, beginning in the specified conversion state contained in mbstate, from the value contained in wchar, into the address represented by mbchar. The return value is the number of bytes required to represent the corresponding multibyte character, but it will not return more than MB_CUR_MAX bytes.

If mbstate is null, the internal mbstate_t object containing the conversion state of mbchar is used. If the character sequence wchar does not have a corresponding multibyte character representation, a -1 is returned and the errno is set to EILSEQ.

The wcrtomb function differs from wctomb by its restartability. The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use wcsrlen rather than wcsnlen, if a subsequent call to wcsrtombs were used instead of wcstombs.

Return Values

The number of bytes, never greater than MB_CUR_MAX, in the wide character.

Success.

0 if wchar is the wide-character null.
-1 if the conversion is not possible in the current locale.

Failure.

Requirements