converts a multibyte character to a wide
* restrict pwc
const char * restrict
() function converts the multibyte
character pointed to by s
to a wide
character, and stores it in the wchar_t object pointed to by
. This function may inspect at most
bytes of the array pointed to by
, the first
bytes pointed to by
need to form an entire multibyte character.
Otherwise, this function returns an error and the internal state will be
If a call to
() resulted in an
undefined internal state,
() must be
called with s
to reset the internal state before it
can safely be used again.
The behaviour of
() is affected by the
category of the current locale.
Calling any other functions in libc
the internal state of
(), except for
category set to a different
locale. Such setlocale(3)
calls cause the internal state of this function to be undefined.
In state-dependent encodings such as ISO/IEC 2022-JP,
may point to the special sequence of bytes
to change the shift-state. Because such sequence bytes do not correspond to
any individual wide character,
treats them as if they were part of the subsequent multibyte character.
The following special cases apply to the arguments:
- s == NULL
mbtowc() initializes its own internal
state to the initial state, and determines whether the current encoding is
mbtowc() returns 0 if
the encoding is state-independent, otherwise non-zero.
pwc is ignored.
- pwc == NULL
mbtowc() behaves just as if
pwc was not
NULL, including modifications to
internal state, except that the result of the conversion is discarded.
This can be used to determine the size of the wide character
representation of a multibyte string. Another use case is a check for
illegal or incomplete multibyte sequences.
- n == 0
- In this case, the first n bytes of the
array pointed to by s never form a
complete character and
- s points to a null byte
- Number of bytes for the valid multibyte character pointed to by
s. There are no cases where the value
returned is greater than the value of the
- s points to an invalid or an incomplete
multibyte character. errno is set to
indicate the error.
- The current encoding is state-independent.
- The current encoding is state-dependent.
() will set
in the following cases:
- s points to an invalid or incomplete
() function conforms to
. The restrict qualifier is added at
is an IEEE
Std 1003.1-2008 (“POSIX.1”)
On error, callers of
() cannot tell
whether the multibyte character was invalid or incomplete. To treat incomplete
data differently from invalid data the
function can be used