mbrtowc()

Convert a character to a wide-character code

Synopsis:

#include <wchar.h>

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

Library:

libc

Description:

The mbrtowc() function converts single multibyte characters pointed to by s into wide characters pointed to by pwc, to a maximum of n bytes (not characters).

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

This function is affected by LC_TYPE.

Returns:

(size_t)-2: After converting all n characters, the resulting conversion state indicates an incomplete multibyte character.
(size_t)-1: The function detects an encoding error before completing the next multibyte character; the function stores the value EILSEQ in errno and leaves the resulting conversion state undefined.
0: The next completed character is a null character; the resulting conversion state is the same as the initial one.
x: The number of bytes needed to complete the next multibyte character, in which case the resulting conversion state indicates that x bytes have been converted.

Errors:

EILSEQ: Invalid character sequence.
EINVAL: The ps argument points to an invalid object.

Classification:

ANSI

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes