mbsrtowcs()

Convert a character string to a wide-character string

Synopsis:

#include <wchar.h>

size_t mbsrtowcs( wchar_t * dst, 
                  const char ** src,
                  size_t n, 
                  mbstate_t * ps );

Library:

libc

Description:

The mbsrtowcs() function converts a string of multibyte characters pointed to by src into the corresponding wide characters pointed to by dst, to a maximum of n bytes, including the terminating NULL character.

The function converts each character as if by a call to mbtowc() and stops early if:

• A sequence of bytes doesn't conform to a valid character

Or:

• Converting the next character would exceed the limit of n total bytes.

The ps variable is an internal pointer that allows mbsrtowcs() to be a restartable version of mbstowcs(); if ps is a NULL pointer, mbsrtowcs() uses its own internal pointer.

This function is affected by LC_TYPE.

The mbsrtowcs() function is the restartable version of mbstowcs().

Returns:

(size_t)-1

Failure; invalid wide-character code.

x

Success; the number of total bytes successfully converted, not including the terminating NULL byte.

Errors:

EILSEQ

Invalid character sequence.

EINVAL

The ps argument points to an invalid object.

Classification:

ANSI

See also:

errno()

"Multibyte character functions" and "Wide-character functions" in the summary of functions chapter.