Converts a multibyte character string in the current locale to a corresponding wide character string, with the capability of restarting in the middle of a multibyte character.

#include <wchar.h>

size_t mbsrtowcs(wchar_t *wcstr, const char **mbstr, size_t count, mbstate_t *mbstate);

Parameters

wcstr

Address to store the resulting converted wide character string.

mbstr

Indirect pointer to the location of the multibyte character string to convert.

count

The maximum number of characters (not bytes) to convert and store in wcstr.

mbstate

A pointer to an mbstate_t conversion state object. If this value is a null pointer, a static internal conversion state object is used. Because the internal mbstate_t object is not thread-safe, we recommend that you always pass your own mbstate parameter.

Remarks

The mbsrtowcs function converts a string of multibyte characters indirectly pointed to by mbstr, into wide characters stored in the buffer pointed to by wcstr, by using the conversion state contained in mbstate. The conversion continues for each character until either a terminating null multibyte character is encountered, a multibyte sequence that does not correspond to a valid character in the current locale is encountered, or until count characters have been converted. If mbsrtowcs encounters the multibyte null character ('\0') either before or when count occurs, it converts it to a 16-bit terminating null character and stops.

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

The mbsrtowcs function differs from mbstowcs by its restartability. The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application should use mbsrlen instead of mbslen, if a subsequent call to mbsrtowcs is used instead of mbstowcs.

If wcstr is not a null pointer, the pointer object pointed to by mbstr is assigned a null pointer if conversion stopped because a terminating null character was reached. Otherwise, it is assigned the address just past the last multibyte character converted, if any. This allows a subsequent function call to restart conversion where this call stopped.

If the wcstr argument is a null pointer, the count argument is ignored and mbsrtowcs returns the required size in wide characters for the destination string. If mbstate is a null pointer, the function uses a non-thread-safe static internal mbstate_t conversion state object. If the character sequence mbstr does not have a corresponding multibyte character representation, a -1 is returned and the errno is set to EILSEQ.

If mbstr is a null pointer, this function sets errno to EINVAL and returns -1.

Return Values

Returns the number of characters successfully converted, not including the terminating null character, if any. Returns (size_t)(-1) if an error occurred, and sets errno to EILSEQ.

Requirements