int
mbtowc(
wchar_t * restrict pwc
, const char * restrict s
, size_t n
)
)
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:
)
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.
)
executes the conversion as if
pwc
is non-NULL, but a result of the conversion is discarded.
n
bytes of the array pointed to by
s
never form a complete character.
Thus, the
mbtowc(
)
always fails.
)
returns:
s
points to a nul byte
(`\0').
s
.
There are no cases that the value returned is greater than
the value of the
MB_CUR_MAX
macro.
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:
)
may cause an error in the following case:
EILSEQ
]
s
points to an invalid or incomplete multibyte character.
)
function conforms to
ANSI X3.159-1989 (``ANSI C89'') .
The restrict qualifier is added at
ISO/IEC 9899:1999 (``ISO C99'') .