wcrtomb - converts a wide character to a multibyte character
Standard C Library (libc, -lc)
wcrtomb(const char * restrict s, wchar_t wc, mbstate_t * restrict ps);
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
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
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.
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.
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
The wcrtomb() function conforms to . The restrict qualifier is added at
BSD February 4, 2002 BSD
[ Back ]