mbrchar(3S)mbrchar(3S)NAME
mbrchar: mbrlen, mbrtowc, wcrtomb, btowc, wctob, mbsinit - multibyte
character handling (restartable)
SYNOPSIS
#include <wchar.h>
size_t mbrlen (const char *s, size_t n, mbstate_t *ps);
size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);
size_t wcrtomb (char *s, wchar_t wchar, mbstate_t *ps);
wint_t btowc(int c);
int wctob(wint_t c);
int mbsinit(const mbstate_t *ps);
DESCRIPTION
The mbrlen function determines the number of bytes that comprise the
multibyte character pointed to by s, if s is not a null pointer. The
mbrlen function uses its own internal mbstate_t object if ps is a null
pointer, which is initialized at program startup. Otherwise, the
mbstate_t object pointed to by ps is used to retain the current
conversion state of the multibyte character sequence. The mbrlen
function returns 0 if the next n or fewer bytes comprise the character
that corresponds to the null wide character, or it returns the positive
value of the number of bytes if the next n or fewer bytes comprise a
valid multibyte character. Also, if all n bytes have been processed and
the n bytes contribute to an incomplete but potentially valid multibyte
character, it returns (size_t)-2. When an encoding error occurs, and the
next n or fewer bytes do not contribute to a valid multibyte character,
it returns (size_t)-1, EILSEQ is stored in errno and the conversion state
is undefined.
The mbrtowc function converts the multibyte character to a wide character
and places the result in the object pointed to by pwc. (The value of the
wide character corresponding to the null character is zero.)
The mbrtowc function is equivalent to the call:
mbrtowc(NULL, "", 1, ps);
if s is a null pointer. The values of pwc and n are ignored.
If s is not a null pointer, the mbrtowc function processes at most n
bytes beginning at the byte pointed to by s to calculate the number of
bytes needed to comprise the next multibyte character. If mbrtowc finds
that the next multibyte character is valid, it determines the
corresponding wide character value and stores the value in the wide
character string object pointed to by pwc, if pwc is not a null pointer.
If the corresponding wide character is a null wide character, the
conversion state is initialized. The mbrtowc function uses its own
internal mbstate_t object if ps is a null pointer, which is initialized
at program startup. Otherwise, the mbstate_t object pointed to by ps is
used to retain the current conversion state of the multibyte character
sequence.
The mbrtowc function returns 0, if the next n or fewer bytes comprise the
character that corresponds to a null wide character, or it returns the
positive value of the number of bytes if the next n or fewer bytes
Page 1
mbrchar(3S)mbrchar(3S)
comprise a valid multibyte character. The corresponding wide character
value is stored in the object pointed to by pwc, in those cases.
Also, if all n bytes have been processed and the n bytes contribute to an
incomplete but potentially valid multibyte character, it returns
(size_t)-2. When an encoding error occurs, and the next n or fewer bytes
do not contribute to a valid multibyte character, it returns (size_t)-1,
EILSEQ is stored in errno and the conversion state is undefined. In those
cases, no value is stored in the object pointed to by pwc.
The wcrtomb function determines the number of bytes needed to represent
the multibyte character corresponding to the code whose value is wchar,
and, if s is not a null pointer, stores the multibyte character
representation in the array pointed to by s. The wcrtomb function is
equivalent to the call:
wcrtomb(buf, L' ', ps);
if s is a null pointer. (Where buf is an internal buffer.)
If s is not a null pointer, wcrtomb calculates the number of bytes needed
to represent the character corresponding to the wide character wchar, and
stores the resulting bytes in the multibyte string object pointed to by
s. At most MB_CUR_MAX bytes are stored. If wchar is a null wide
character, a null byte is stored and the conversion state is initialized.
If ps is a null pointer, wcrtomb uses its own internal mbstate_t object,
which is initialised at program startup. Otherwise, the mbstate_t object
pointed to by ps is used. The wcrtomb function returns the number of
bytes stored in the multibyte string object. When wchar is not a valid
wide character, an encoding error occurs, and the function returns
(size_t)-1. In that case, EILSEQ is stored in errno and the conversion
state is undefined.
The btowc function determines if c comprises a valid multibyte character
which has only one byte. If c has the value of EOF or does not comprise a
valid character, the function returns WEOF. Otherwise, it returns the
wide character value of the character.
The wctob function determines if c corresponds to one of the extended
character sets in which the multibyte character has only one byte. If c
does not correspond to a multibyte character that has only one byte, it
returns EOF. Otherwise, it returns the single byte character value of
the character.
The mbsinit function determines if the mbstate_t object pointed to by ps
describes an initial conversion state. It returns a nonzero value if ps
is a null pointer or if the conversion state object describes an initial
state. Otherwise, it returns zero.
NOTES
The behaviour of those functions is affected by the LC_CTYPE category of
the current locale. (Stateful encodings are not supported in IRIX.)
Those functions are supported in n32 and 64 bit C Libraries for IRIX
6.5.17 and later versions.
Page 2
mbrchar(3S)mbrchar(3S)SEE ALSOwchrtbl(1M), mbchar(3C), mbstring(3C), mbrstring(3S), setlocale(3C),
environ(5).
Page 3