wcrtomb

wcrtomb

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

The function determines the number of bytes needed to represent the wide character wc as a multibyte character, if possible. (Not all values representable as type wchar_t are necessarily valid wide-character codes.)

If ps is not a null pointer, the conversion state for the multibyte string is assumed to be *ps. Otherwise, it is assumed to be &internal, where internal is an object of type mbstate_t internal to the wcrtomb function. At program startup, internal is initialized to the initial conversion state. No other library function alters the value stored in internal.

If s is not a null pointer and wc is a valid wide-character code, the function determines x, the number of bytes needed to represent wc as a multibyte character, and stores the converted bytes in the array of char beginning at s. (x cannot be greater than MB_CUR_MAX.) If wc is a null wide character, the function stores any shift sequence needed to restore the initial shift state, followed by a null byte. The resulting conversion state is the initial conversion state.

If s is a null pointer, the function effectively returns wcrtomb(buf, L'\0', ps), where buf is a buffer internal to the function. (The function thus returns the number of bytes needed to restore the initial conversion state and to terminate the multibyte string pending from a previous call to wcrtomb or wcsrtombs for the same string and conversion state.)

The function returns:

• (``size_t``)-1 if wc is an invalid wide-character code, in which case the function stores the value EILSEQ in errno and leaves the resulting conversion state undefined.
• x, the number of bytes needed to complete the next muitibyte character, in which case the resulting conversion state indicates that x bytes have been generated.