|MBTOWC(3)||Library Functions Manual||MBTOWC(3)|
mbtowc — converts
a multibyte character to a wide character
* restrict pwc, const
char * restrict s, size_t
mbtowc() function converts the
multibyte character pointed to by s to a wide
character, and stores it in the wchar_t object pointed to by
pwc. This function may inspect at most
n bytes of the array pointed to by
Unlike mbrtowc(3), the first n bytes pointed to by s need to form an entire multibyte character. Otherwise, this function returns an error and the internal state will be undefined.
If a call to
mbtowc() resulted in an
undefined internal state,
mbtowc() must be called
with s set to
NULL to reset
the internal state before it can safely be used again.
The behaviour of
mbtowc() is affected by
LC_CTYPE category of the current locale. Calling
any other functions in libc never changes the internal
mbtowc(), except for calling
setlocale(3) with the
LC_CTYPE 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,
s 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,
mbtowc() treats them as
if they were part of the subsequent multibyte character.
The following special cases apply to the arguments:
mbtowc() initializes its own internal state to the initial state, and determines whether the current encoding is state-dependent.
mbtowc() returns 0 if the encoding is state-independent, otherwise non-zero. pwc is ignored.
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.
mbtowc() always fails.
When s is
mbtowc() will set
errno in the following cases:
mbtowc() function conforms to
ANSI X3.159-1989 (“ANSI C89”).
The restrict qualifier is added at ISO/IEC 9899:1999
(“ISO C99”). Setting errno
is an IEEE Std 1003.1-2008 (“POSIX.1”)
On error, callers of
mbtowc() cannot tell
whether the multibyte character was invalid or incomplete. To treat
incomplete data differently from invalid data the
mbrtowc(3) function can be used
|February 27, 2016||OpenBSD-current|