mbsrtowcs

size_t mbsrtowcs (wchar_t* dest, const char** src, size_t max, mbstate_t* ps);

Convert multibyte string to wide-character string

Translates the multibyte sequence pointed by src to the equivalent sequence of wide-characters (which is stored in the array pointed by dest), up until either max wide characters have been translated or until a null character is encountered in the multibyte sequence src (which is also translated and stored, but not counted in the length returned by the function).

If max characters are successfully translated, the resulting string stored in dest is not null-terminated.

The function uses (and updates) the shift state described by ps. If ps is a null pointer, the function uses its own internal shift state, which is altered as necessary only by calls to this function.

If the function translates an entire multibyte string (until it finds a null-character), and dest is not a null pointer, the function sets src to a null pointer value and the resulting state is guaranteed to be the initial conversion state.

The behavior of this function depends on the LC_CTYPE category of the selected C locale.

This is the restartable version of mbstowcs (<cstdlib>).

Parameters

dest: Pointer to an array of wchar_t elements long enough to store a string of max wide characters.
If this is a null pointer, the function does not store the resulting string, but still counts how many bytes from src form a valid string (parameter max is ignored in this case).
src: Pointer to a C multibyte character string to be interpreted (an indirect pointer).
This value is modified by the function to point to past the last multibyte character converted if conversion stops prematurely, or to a null pointer if the function reached the terminating null character.
max: Maximum number of wide characters to write to dest.
size_t is an unsigned integral type.
ps: Pointer to a mbstate_t object that defines a conversion state.

Return Value

The number of wide characters written to dest (not including the eventual terminating null character).

If, during the translation, the function encountered a sequence of bytes that does not form a valid multibyte character, the function sets errno to EILSEQ and returns (size_t)-1 (src will point to the first byte that could not be translated.

Notice that size_t is an unsigned integral type, and thus none of the values possibly returned is less than zero.

functions

types

macro constants

mbsrtowcs

Parameters

Return Value

See also