mbtowc, mbrtowc - Convert a multibyte character to a wide
character
#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 );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards 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.
Points to the location of a variable containing the widecharacter
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).
The mbtowc() function converts a multibyte character to a
wide character 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 operation
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.
The mbrtowc() and other restartable conversion routines
are functional only when used with locales that support
shift-state encoding. Currently, the Tru64 UNIX product
does not provide locales that use shift-state encoding.
Therefore, the run-time behavior of mbrtowc() is equivalent
to mbtowc(), and neither function returns values
listed for state-dependent conditions.
If *s is not a null pointer, the mbtowc() function returns
the following 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 contains 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 incomplete (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 undefined.
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.
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.
Functions: btowc(3), mblen(3), wctomb(3), mbstowcs(3),
wcstombs(3), wctob(3)
Files: locale(4)
mbtowc(3)
[ Back ] |
