Convert a multibyte character in the current locale into the equivalent wide character, with the capability of restarting in the middle of a multibyte character.

#include <wchar.h>

size_t mbrtowc(wchar_t *pwc, const char *mbchar, size_t n, mbstate_t *ps);

Parameters

wchar

Address of a wide character to receive the converted wide character string (type wchar_t). This value can be a null pointer if no return wide character is required.

mbchar

A pointer to a sequence of bytes (a multibyte character).

count

The number of bytes to check.

mbstate

Pointer to conversion state object. If this value is a null pointer, the function uses a static internal conversion state object. Because the internal mbstate_t object is not thread-safe, we recommend that you always pass your own mbstate argument.

Remarks

If mbchar is a null pointer, the function is equivalent to the call:
mbrtowc(NULL, "", 1, &mbstate)

In this case, the value of the arguments wchar and count are ignored.

If mbchar is not a null pointer, the function examines count bytes from mbchar to determine the required number of bytes that are required to complete the next multibyte character. If the next character is valid, the corresponding multibyte character is stored in wchar if it is not a null pointer. If the character is the corresponding wide null character, the resulting state of mbstate is the initial conversion state.

The mbrtowc function differs from mbtowc, _mbtowc_l 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 wcsrlen instead of wcslen if a subsequent call to wcsrtombs is used instead of wcstombs.

Return Values

0

The next count or fewer bytes complete the multibyte character that represents the null wide character, which is stored in wchar, if wchar is not a null pointer.

1 to count, inclusive

The next count or fewer bytes complete a valid multibyte character. The value returned is the number of bytes that complete the multibyte character. The wide character equivalent is stored in wchar, if wchar is not a null pointer.

(size_t)(-1)

An encoding error occurred. The next count or fewer bytes do not contribute to a complete and valid multibyte character. In this case, errno is set to EILSEQ and the conversion shift state in mbstate is unspecified.

(size_t)(-2)

The next count bytes contribute to an incomplete but potentially valid multibyte character, and all count bytes have been processed. No value is stored in wchar, but mbstate is updated to restart the function.

Requirements