mbrtowc - converts a multibyte character to a wide character
Standard C Library (libc, -lc)
mbrtowc(wchar_t * restrict pwc, const char * restrict s, size_t n,
mbstate_t * restrict ps);
The mbrtowc() usually converts the multibyte character pointed by s to
the wide character, and store the wide character to the wchar_t object
pointed by pwc if pwc is non-null and s points a valid character. The
conversion is taken place with conforming to and changing the conversion
state described in the mbstate_t object pointed by ps. This function may
examine at most n bytes of the array beginning from s.
If s points a valid character and the character corresponds to a null
wide character, then the mbrtowc() places the mbstate_t object pointed by
ps to an initial conversion state.
Unlike mbtowc(3), the mbrtowc() may accept the byte sequence pointed by s
not forming complete multibyte character but being possible for a part of
a valid character. In this case, this function will accept the all of
such bytes and save them into the conversion state object pointed by ps.
They will be used at the subsequent call of this function to restart the
The behaviour of the mbrtowc() is affected by LC_CTYPE category of the
There are the special cases:
s == NULL The mbrtowc() sets the conversion state object pointed by
ps to an initial state and always return 0. Unlike
mbtowc(3), the value returned does not indicate whether the
current encoding of the locale is state-dependent.
In this case, The mbrtowc() ignores pwc and n, and is
equivalent to the following call:
mbrtowc(NULL, "", 1, ps);
pwc == NULL The conversion from a multibyte character to a wide character
is taken place and the conversion state may be
affected, but the result wide character is discarded.
ps == NULL The mbrtowc() uses its own internal state object to keep
the conversion state, instead of ps mentioned in this manual
Calling any other functions in the Standard C Library
(libc, -lc) never change the internal state of the
mbrtowc(), that is initialized at startup time of the program.
In the usual cases, the mbrtowc() returns:
0 The next bytes pointed by s forms a null character.
positive If s is points an valid character, the mbrtowc() returns
the number of bytes consisting the character.
(size_t)-2 s points the byte sequence which is possible to consist a
part of valid multibyte character but incomplete. When n
is at least MB_CUR_MAX, this case can only occur if the
array pointed s contains redundant shift sequence.
(size_t)-1 s points a illegal byte sequence which does not form a
valid multibyte character. In this case, the mbrtowc()
sets errno to indicate the error.
The mbrtowc() may causes an error in the following case:
[EILSEQ] s points an invalid or incomplete multibyte character.
[EINVAL] ps points an invalid or uninitialized mbstate_t
mbrlen(3), mbtowc(3), setlocale(3)
The mbrtowc() function conforms to . The restrict qualifier is added at
BSD February 4, 2002 BSD
[ Back ]