mbtowc(3)mbtowc(3)NAME
mbtowc, mbrtowc - Convert a multibyte character to a wide character
SYNOPSIS
#include <stdlib.h>
int mbtowc(
wchar_t *pwc,
const char *s,
size_t n ); #include <wchar.h>
size_t mbrtowc(
wchar_t *pwc,
const char *s,
size_t n,
mbstate_t *ps );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
mbtowc(): ISO C, XPG4
mbrtowc(): ISO C
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Points to the location of a variable containing the wide-character
value. Points to a byte array containing the multibyte character to be
converted. Specifies the maximum number of bytes to evaluate. Points
to the mbstate_t structure that contains the conversion state of the
multibyte character in s (for mbrtowc() only).
DESCRIPTION
The mbtowc() function converts a multibyte character to a wide charac‐
ter and returns the number of bytes of the multibyte character, which
is stored as an output variable.
In locales with shift-state character encoding, a call to mbtowc() with
a null pointer as the s parameter places the function in the initial
shift state. A call to mbtowc() with an s parameter that is not a null
pointer may change the shift state for subsequent calls to mbtowc(),
depending on the character examined. Changing the LC_CTYPE category of
the locale causes the shift state of the function to be indeterminate.
The implementation behaves as though no other function calls the
mbtowc() function.
In the case of nonrestartable functions, such as mbtowc(), conversion
of shift-state encoding must first be enabled by calling the function
with a null pointer parameter and then calling the function again with
the multibyte value to be converted. The status of the conversion oper‐
ation after the call is not available to subsequent calls.
The mbrtowc() function is a restartable version of mbtowc(), which
means that the shift state for the character in s is maintained in the
mbstate_t structure and is therefore available to subsequent calls by
mbrtowc() and other restartable conversion functions.
RESTRICTIONS
The mbrtowc() and other restartable conversion routines are functional
only when used with locales that support shift-state encoding. Cur‐
rently, the Tru64 UNIX product does not provide locales that use shift-
state encoding. Therefore, the run-time behavior of mbrtowc() is equiv‐
alent to mbtowc(), and neither function returns values listed for
state-dependent conditions.
RETURN VALUES
If *s is not a null pointer, the mbtowc() function returns the follow‐
ing values: A positive value indicating the number of bytes in the
multibyte character, if the next n or fewer bytes in s constitutes a
valid multibyte character other than the null character Zero, if s con‐
tains a null character -1, if s does not contain a valid multibyte
character or contains a character having more than the number of bytes
expressed by the n parameter. In this case, mbtowc() sets errno to
indicate the error.
If s is not a null pointer, the mbrtowc() function returns the first
value that applies in the following list: Zero, if the next n or fewer
bytes are converted to a null wide character, which is then stored in
pwc A positive value indicating the number of bytes in the converted
multibyte character, if the next n or fewer bytes constitute a valid
multibyte character. The counterpart wide-character value is then
stored in pwc. (size_t)-2, if the next n bytes contribute to an incom‐
plete (but potentially valid) multibyte character. In this case, no
value is stored in pwc. (size_t)-1, if an encoding error occurs, in
which case the next n or fewer bytes do not contribute to a complete
and valid multibyte character. In this case, no value is stored in pwc,
the function sets errno to EILSEQ, and the conversion state is unde‐
fined.
If *s is a null pointer, both the mbtowc() and mbrtowc() functions
return one of the following values, depending on whether the character
encoding in the current locale is shift-state dependent: A nonzero
value, if the character encoding is shift-state dependent Zero, if the
character encoding is not shift-state dependent
The return values for these functions is never greater than the value
specified by the n parameter or the value of MB_CUR_MAX.
ERRORS
If the following condition occurs, the mbtowc() and mbrtowc() functions
set errno to the corresponding value. The s parameter points to an
invalid multibyte character.
SEE ALSO
Functions: btowc(3), mblen(3), wctomb(3), mbstowcs(3), wcstombs(3),
wctob(3)
Files: locale(4)mbtowc(3)