wcsrtombs

wcsrtombs is a function in the C standard library that converts a sequence of wide characters to a multibyte character string according to a specified locale. It is the stateful counterpart to wcstombs, allowing incremental conversion across calls by maintaining conversion state in an mbstate_t object. The function uses the current locale or a provided locale to determine how wide characters map to multibyte sequences.

Prototype

size_t wcsrtombs(char *restrict s, const wchar_t **restrict pwcs, size_t len, mbstate_t *restrict ps, locale_t locale);

Parameters

s points to the destination buffer where the resulting multibyte characters are stored. len specifies the maximum number of bytes to write to s. pwcs is a pointer to the source wide-character string; on return, *pwcs is updated to point to the next unwritten wide character, or left unchanged if no input remains. ps is a pointer to an mbstate_t object that stores the conversion state between calls. locale selects the locale used for the conversion; typically this defaults to the program’s current C locale, but a specific locale_t can be supplied for per-call control.

Behavior

The function converts wide characters from the source into their multibyte representations, writing at most len bytes to s. It stops when either len bytes have been written or the input wide string contains a terminating L'\0'. If a complete wide string is converted and s is not NULL, a terminating NUL is stored. The conversion state is updated in ps and can be continued in subsequent calls.

Return value and errors

On success, wcsrtombs returns the number of bytes placed in s, not counting the terminating NUL. If s is NULL, the function returns the number of bytes that would be required to perform the conversion. If a wide character cannot be represented in the destination locale, the function returns (size_t)-1 and sets errno (commonly EILSEQ). Some implementations may leave *pwcs and ps in an unspecified state on error.