mbsrtowcs

mbsrtowcs is a C standard library function used to convert a multibyte sequence into a wide-character string. It is declared in <wchar.h> and is designed for use with multibyte encodings (such as UTF-8) in conjunction with a locale. The function supports streaming conversion, allowing input to be processed piece by piece.

Prototype and parameters

The typical signature is:

size_t mbsrtowcs(wchar_t *restrict pwcs, const char **restrict s, size_t len, mbstate_t *restrict ps);

- pwcs: destination array for wide characters. If pwcs is NULL, no writing occurs and the function computes the number of wide characters that would be produced.

- s: pointer to a pointer to the input multibyte string. The function reads from *s and advances it to the next unconsumed byte on success.

- len: maximum number of wide characters to write to pwcs (if pwcs is non-null).

- ps: a pointer to an mbstate_t object that records the conversion state. The state enables correct handling of partial multibyte sequences across successive calls.

Behavior and return value

mbsrtowcs converts as many complete multibyte characters as possible from the input into wide characters, up to len. It updates the input pointer to reflect consumed bytes. The function returns the number of wide characters written, not counting a terminating null, or (size_t)-1 if an encoding error occurs. On error, errno may be set (commonly to EILSEQ for an invalid sequence or EINVAL for an incomplete shift sequence, depending on the implementation).

Relation to other functions

mbsrtowcs is part of the mbrtowc/mbsrtowcs family, used for converting multibyte strings to wide-character representations. It complements mbstowcs and is often used in conjunction with wcsrtombs for bidirectional streaming between multibyte and wide-character domains.

Portability and usage

The function is provided by standard C libraries on modern systems and is suitable for locale-aware text processing, particularly when dealing with input streams that arrive in chunks.