MBTOWC(3) | Library Functions Manual | MBTOWC(3) |
mbtowc
— converts
a multibyte character to a wide character
#include
<stdlib.h>
int
mbtowc
(wchar_t
* restrict pwc, const
char * restrict s, size_t
n);
The
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
s.
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 the LC_CTYPE
category of the current
locale. Calling any other functions in
libc never
changes the internal state of 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.Normally, mbtowc
() returns:
MB_CUR_MAX
macro.When s is NULL
,
mbtowc
() returns:
mbtowc
() will set
errno in the following cases:
EILSEQ
]The 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”)
extension.
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
instead.
February 27, 2016 | OpenBSD-current |