mbtowc - converts a multibyte character to a wide character
Standard C Library (libc, -lc)
mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n);
The mbtowc() usually converts the multibyte character pointed by s to the
wide character, and store it to the wchar_t object pointed by pwc if pwc
is non-null and s points a valid character. This function may inspect at
most n bytes of the array beginning from s.
In state-dependent encodings, s may point the special sequence bytes to
change the shift-state. Although such sequence bytes corresponds to no
individual wide-character code, the mbtowc() changes its own state by the
sequence bytes and treats them as if they are a part of the subsequence
Unlike mbrtowc(3), the first n bytes pointed by s need to form an entire
multibyte character. Otherwise, this function causes an error.
Calling any other functions in the Standard C Library (libc, -lc) never
change the internal state of the mbtowc(), except for calling
setlocale(3) with changing LC_CTYPE category of the current locale. Such
setlocale(3) call causes the internal state of this function to be indeterminate.
The behaviour of the mbtowc() is affected by LC_CTYPE category of the
There are special cases:
s == NULL mbtowc() initializes its own internal state to an initial
state, and determines whether the current encoding is
state-dependent. This function returns 0 if the encoding
is state-independent, otherwise non-zero. In this case,
pwc is completely ignored.
pwc == NULL mbtowc() executes the conversion as if pwc is non-null, but
a result of the conversion is discarded.
n == 0 In this case, the first n bytes of the array pointed by s
never form a complete character. Thus, the mbtowc() always
In the usual cases, the mbtowc() returns:
0 s points a null byte ('\0').
positive number of bytes for the valid multibyte character pointed
by s. There is no cases that the value returned is greater
than the value of MB_CUR_MAX macro.
-1 s points an invalid or an incomplete multibyte character.
The mbtowc() also sets errno to indicate the error.
In the case that s is equal to NULL, the mbtowc() returns:
0 The current encoding is state-independent.
non-zero The current encoding is state-dependent.
The mbtowc() may causes an error in the following case:
[EILSEQ] s points an invalid or incomplete multibyte character.
mblen(3), mbrtowc(3), setlocale(3)
The mbtowc() function conforms to ANSI X3.159-1989 (``ANSI C''). The
restrict qualifier is added at .
BSD February 3, 2002 BSD
[ Back ]