mbtowc — convert a multibyte sequence to a wide character
#include <stdlib.h>
int
mbtowc( |
wchar_t * | pwc, |
const char * | s, | |
size_t | n) ; |
The main case for this function is when s
is not NULL and pwc
is not NULL. In this case,
the mbtowc
() function inspects
at most n
bytes of
the multibyte string starting at s
, extracts the next complete
multibyte character, converts it to a wide character and
stores it at *pwc
.
It updates an internal shift state only known to the mbtowc
function. If s
does
not point to a '\0' byte, it returns the number of bytes that
were consumed from s
,
otherwise it returns 0.
If the n
bytes
starting at s
do not
contain a complete multibyte character, or if they contain an
invalid multibyte sequence, mbtowc
() returns −1. This can happen
even if n
>=
MB_CUR_MAX
, if the multibyte
string contains redundant shift sequences.
A different case is when s
is not NULL but pwc
is NULL. In this case the
mbtowc
() function behaves as
above, excepts that it does not store the converted wide
character in memory.
A third case is when s
is NULL. In this case,
pwc
and n
are ignored. The mbtowc
() function resets the shift state,
only known to this function, to the initial state, and
returns non-zero if the encoding has non-trivial shift state,
or zero if the encoding is stateless.
If s
is not NULL,
the mbtowc
() function returns
the number of consumed bytes starting at s
, or 0 if s
points to a null byte, or
−1 upon failure.
If s
is NULL, the
mbtowc
() function returns
non-zero if the encoding has non-trivial shift state, or zero
if the encoding is stateless.
The behavior of mbtowc
()
depends on the LC_CTYPE
category of the current locale.
This function is not multi-thread safe. The function mbrtowc(3) provides a better interface to the same functionality.
MB_CUR_MAX(3), mbrtowc(3), mbstowcs(3)
|