NAME
mbrtowc —
converts a multibyte
character to a wide character (restartable)
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <wchar.h>
size_t
mbrtowc(
wchar_t *
restrict pwc,
const char *
restrict s,
size_t n,
mbstate_t * restrict ps);
DESCRIPTION
The
mbrtowc() 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:
-
-
- s == NULL
- mbrtowc() 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);
-
-
- pwc == NULL
- The conversion from a multibyte character to a wide
character has taken place and the conversion state may be affected, but
the resulting wide character is discarded.
-
-
- ps == NULL
- mbrtowc() 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.
RETURN VALUES
In the usual cases,
mbrtowc() returns:
-
-
- 0
- The next bytes pointed to by s form a
nul character.
-
-
- positive
- If s points to a valid character,
mbrtowc() returns the number of bytes in the
character.
-
-
- (size_t)-2
- 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.
-
-
- (size_t)-1
- 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.
ERRORS
mbrtowc() 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.
SEE ALSO
mbrlen(3),
mbtowc(3),
setlocale(3)
STANDARDS
The
mbrtowc() function conforms to
ISO/IEC
9899/AMD1:1995 (“ISO C90, Amendment 1”). The restrict
qualifier is added at
ISO/IEC 9899:1999
(“ISO C99”).