size_t
mbrtowc(
wchar_t * restrict pwc
, const char * restrict s
, size_t n
, mbstate_t * restrict ps
)
)
usually converts the multibyte character pointed to by
s
to a wide character, and stores the wide character
to the wchar_t object pointed to by
pwc
if
pwc
is
non-
NULL
and
s
points to a valid character.
The conversion happens in accordance with, and changes the conversion
state described in the mbstate_t object pointed to by
ps
.
This function may examine at most
n
bytes of the array beginning from
s
.
If
s
points to a valid character and the character corresponds to a nul wide
character, then the
mbrtowc()
places the mbstate_t object pointed to by
ps
to an initial conversion state.
Unlike
mbtowc(3),
the
mbrtowc()
may accept the byte sequence pointed to by
s
not forming a complete multibyte character
but which may be part of a valid character.
In this case, this function will accept all such bytes
and save them into the conversion state object pointed to by
ps
.
They will be used at subsequent calls of this function to restart
the conversion suspended.
The behaviour of
mbrtowc()
is affected by the
LC_CTYPE
category of the current locale.
These are the special cases:
)
sets the conversion state object pointed to by
ps
to an initial state and always returns 0.
Unlike
mbtowc(3),
the value returned does not indicate whether the current encoding of
the locale is state-dependent.
In this case,
mbrtowc()
ignores
pwc
and
n
,
and is equivalent to the following call:
mbrtowc(NULL, "", 1, ps);
)
uses its own internal state object to keep the conversion state,
instead of
ps
mentioned in this manual page.
Calling any other functions in
Standard C Library (libc, -lc)
never changes the internal state of
mbrtowc(),
which is initialized at startup time of the program.
)
returns:
s
form a nul character.
s
points to a valid character,
mbrtowc(
)
returns the number of bytes in the character.
s
points to a byte sequence which possibly contains part of a valid
multibyte character, but which is incomplete.
When
n
is at least
MB_CUR_MAX
,
this case can only occur if the array pointed to by
s
contains a redundant shift sequence.
s
points to an illegal byte sequence which does not form a valid multibyte
character.
In this case,
mbrtowc(
)
sets
errno
to indicate the error.
)
may cause an error in the following case:
EILSEQ
]
s
points to an invalid or incomplete multibyte character.
EINVAL
]
ps
points to an invalid or uninitialized mbstate_t object.
)
function conforms to
ISO/IEC 9899/AMD1:1990 (``ISO C90'') .
The restrict qualifier is added at
ISO/IEC 9899:1999 (``ISO C99'') .