mbtowc(3) Library Functions Manual mbtowc(3)
NAME
mbtowc, mbrtowc - Converts a multibyte character to a wide character
LIBRARY
Standard C Library (libc.so, libc.a)
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);
STANDARDS
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.
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 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 ini-
tial 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.
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
equivalent 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 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.
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.
RELATED INFORMATION
Functions: btowc(3), mblen(3), wctomb(3), mbstowcs(3), wcstombs(3), wctob(3)
Files: locale(4) delim off
mbtowc(3)