NAME
mbtowc —
converts a multibyte character
to a wide character
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
int
mbtowc(
wchar_t *
restrict pwc,
const char *
restrict s,
size_t
n);
DESCRIPTION
mbtowc() usually converts the multibyte character pointed to
by
s to a wide character, and stores it in the wchar_t
object pointed to by
pwc if
pwc is
non-
NULL
and
s points to a valid
character. This function may inspect at most n bytes of the array beginning
from
s.
In state-dependent encodings,
s may point to the special
sequence bytes to change the shift-state. Although such sequence bytes
correspond to no individual wide-character code,
mbtowc()
changes its own state by the sequence bytes and treats them as if they are a
part of the subsequence multibyte character.
Unlike
mbrtowc(3), the first
n bytes pointed to by
s need to
form an entire multibyte character. Otherwise, this function causes an error.
Calling any other functions in
Standard C Library (libc,
-lc) never changes the internal state of
mbtowc(),
except for calling
setlocale(3) with changing
the
LC_CTYPE
category of the current locale. Such
setlocale(3) call causes the
internal state of this function to be indeterminate.
The behaviour of
mbtowc() is affected by the
LC_CTYPE
category of the current locale.
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 to by s never form a complete
character. Thus, the mbtowc() always fails.
RETURN VALUES
Normally, the
mbtowc() returns:
-
-
- 0
- s points to a nul byte
(‘\0’).
-
-
- positive
- Number of bytes for the valid multibyte character pointed
to by s. There are no cases that the value returned
is greater than the value of the
MB_CUR_MAX
macro.
-
-
- -1
- s points to an invalid or an
incomplete multibyte character. The mbtowc() also sets
errno to indicate the error.
When
s is equal to
NULL
,
mbtowc() returns:
-
-
- 0
- The current encoding is state-independent.
-
-
- non-zero
- The current encoding is state-dependent.
ERRORS
mbtowc() may cause an error in the following case:
-
-
- [
EILSEQ
]
- s points to an invalid or incomplete
multibyte character.
SEE ALSO
mblen(3),
mbrtowc(3),
setlocale(3)
STANDARDS
The
mbtowc() function conforms to
ANSI
X3.159-1989 (“ANSI C89”). The restrict qualifier is
added at
ISO/IEC 9899:1999
(“ISO C99”).