wcsrtombs

wcsrtombs

size_t ``wcsrtombs``(char *dst, const wchar_t **src, size_t len, mbstate_t *ps);

The function converts the wide-character string beginning at *src to a sequence of multibyte characters as if by repeated calls of the form:

x = wcrtomb(dst ? dst : buf, *src, ps != 0 ? ps : &internal)

where buf is an array of type char and internal is an object of type mbstate_t, both internal to the wcsrtombs function. At program startup, internal is initialized to the initial conversion state. No other library function alters the value stored in internal.

If dst is not a null pointer, the wcsrtombs function stores len bytes, at most, by calls to wcrtomb. The function effectively increments dst by x and *src by one after each call to wcrtomb that stores a complete converted multibyte character in the remaining space available. After a call that stores a complete null multibyte character at dst (including any shift sequence needed to restore the initial shift state), the function stores a null pointer at *src.

If dst is a null pointer, len is effectively assigned a large value.

The function returns:

• (``size_t``)-1, if a call to wcrtomb returns (``size_t``)-1, indicating that it has detected an invalid wide-character code.
• The number of bytes successfully converted, not including the terminating null byte.