wcrtomb

wcrtomb is a standard C library function that converts a wide character wc into its multibyte representation in the current locale. It writes the resulting bytes to the array pointed to by s and updates the conversion state described by the mbstate_t object pointed to by ps. The conversion uses the LC_CTYPE category of the active locale, and the maximum possible length of a multibyte sequence is MB_CUR_MAX.

Parameters: s is a pointer to a buffer where the multibyte sequence is stored; wc is the wide character to encode; ps points to an mbstate_t object that maintains conversion state across calls for state-dependent encodings.

Return value: wcrtomb returns the number of bytes written to s (the length of the multibyte sequence). If the wide character cannot be represented in the current locale, the function returns (size_t)-1 and may set errno to an encoding error value such as EILSEQ.

Usage notes: If s is NULL, the function does not write any bytes but may still update the conversion state. The multibyte sequence length is at most MB_CUR_MAX, the macro defining the maximum number of bytes in a multibyte character for the current locale. The locale can be changed with setlocale, which affects how wide characters are mapped to multibyte sequences.

Relation to other functions: wcrtomb is the counterpart to mbrtowc, providing the reverse operation (wide character to multibyte). Together with mbrtowc, these functions support locale-aware conversion between wide-character representations and multibyte sequences in I/O and string-processing code. See also wcstombs, mbstowcs, and setlocale.