NAME
mbrtowc
—
converts a multibyte character to a
wide character (restartable)
LIBRARY
library “libc”
SYNOPSIS
#include
<wchar.h>
size_t
mbrtowc
(wchar_t
* restrict pwc, const
char * restrict s, size_t
n, mbstate_t * restrict
ps);
DESCRIPTION
Thembrtowc
()
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 library “libc” 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
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”).