MBLEN(3) Library Functions Manual MBLEN(3)
mblen, mbstowcs, mbtowc, wcstombs, wctomb - multibyte character han-
int mblen(s, n)
size_t mbstowcs(s, pwcs, n)
int mbtowc(pwc, s, n)
int wcstombs(s, pwcs, n)
int wctomb(s, wchar)
The behavior of these functions is affected by the LC_CTYPE category of
the program's locale. For a stat-dependent encoding, each function is
placed into its initial state by a call for which its character pointer
argument, s, is a NULL pointer. Subsequent calls with s as other than
a NULL pointer cause the internal stste of the function to be altered
as necessary. A call with a s as a NULL pointer causes these functions
to return a nonzero value if encodings have state dependency, and zero
otherwise. After the LC_CTYPE category is changed, the shift state of
these functions is indeterminate.
If s is not a NULL pointer, these functions work as follows:
Determines the number of bytes comprising the multibyte charac-
ter pointed to by s.
Converts a sequence of multibyte characters that begins in the
initial shift state from the array pointed to by s into a
sequence of corresponding codes and stores no more than n codes
into the array pointed to by pwcs. No multibyte characters that
follow a null character (which is converted into a code with
value zero) will be examined or converted. Each multibyte char-
acter is converted as if by a call to mbtowc(), except that the
shift state of mbtowc() is not affected.
No more than n elements will be modified in the array pointed to
by pwcs. If copying takes place between objects that overlap,
the behavior is undefined.
Determines the number of bytes that comprise the multibyte char-
acter pointed to by s. mbtowc() then determines the code for
value of type wchar_t that corresponds to that multibyte charac-
ter. The value of the code corresponding to the null caharacter
is zero. If the multibyte character is valid and pwc is not a
null pointer, mbtowc() stores the code in the object pointed to
by pwc. At most n bytes of the array pointed to by s will be
Converts a sequence of codes that correspond to multibyte char-
acters from the array pointed to by pwcs into a sequence of
multibyte characters that begins in the initial shift state and
stores these multibyte characters into the array pointed to by
s, stopping if a multibyte character would exceed the limit of n
total bytes or if a null character is stored. Each code is con-
verted as if by a call to wctomb(), except that the shift state
of wctomb() is not affected.
Determines the number of bytes needed to represent the multibyte
character corresponding to the code whose value is wchar
(including any change in shift state). wctomb() stores the
multibyte character representation in the array object pointed
to by s (if s is not a null pointer). At most, MB_CUR_MAX char-
acters are stored. If the value of wchar is zero, wctomb() is
left in the initial shift state.
If s is a null pointer, mblen(), mbtowc(), and wctomb() return a
nonzero or zero value, if multibyte character encodings, respectively,
do or do not have state dependent encodings.
If s is not a null pointer, mblen() and mbtowc() either return 0 (if s
points to the null character), or return the number of bytes that com-
prise the converted multibyte character (if the next n or fewer bytes
form a valid multibyte character), or return -1 (if they do not form a
valid multibyte character).
In no case will the value returned by mbtowc() be greater than n or the
value of the MB_CUR_MAX macro. If s is not a null pointer, wctomb()
returns -1 (if the value does not correspond to a valid multibyte char-
acter), or returns the number of bytes that comprise the multibyte
character corresponding to wchar.
If an invalid multibyte character is encountered, mbstowcs() and
wcstombs() return (size_t) -1. Otherwise, they return the number of
bytes modified, not including a terminating null character, if any.
When an application program using these routines is statically linked,
user defined multibyte character handling routines in a user provided
shared library will not be used.
6 June 1991 MBLEN(3)