Converts a sequence of wide characters to a corresponding sequence of multibyte characters.

#include <stdlib.h>

size_t wcsrtombs(char *pmb, const wchar_t **src, size_t n, mbstate_t *mbstate);

Parameters

pmb

The address of a sequence of multibyte characters which have been converted.

src

The address of a sequence of wide characters to convert.

n

The number of bytes to convert.

mbstate

A pointer to an mbstate_t conversion state object.

Remarks

The wcsrtombs function converts a string of wide characters, beginning in the specified conversion state contained in mbstate, from the values indirect pointed to in wcstr, into the address of mbstr. The conversion will continue for each character until: after a null terminating wide character is encountered, when a non corresponding character is encountered or when the next character would exceed the limit contained in count. If wcsrtombs encounters the wide-character null character (L'\0') either before or when count occurs, it converts it to an 8-bit 0 and stops.

Thus, the multibyte character string at mbstr is null-terminated only if wcsrtombs encounters a wide character null character during conversion. If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcsrtombs is undefined.

The wcsrtombs function differs from wcstombs by its restartability. The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions.

If the mbstr argument is NULL, wcsrtombs returns the required size in bytes of the destination string. If mbstate is null, the internal mbstate_t conversion state is used. If the character sequence wchar does not have a corresponding multibyte character representation, a -1 is returned and the errno is set to EILSEQ.

Return Values

Returns the number of bytes successfully converted, not including the null terminating null byte (if any), otherwise -1 if an error occurred.

Requirements