mbchar(3C)                                                       mbchar(3C)

NAME
     mbchar: mbtowc, mblen, wctomb, mbrlen, mbrtowc, wcrtomb - multibyte
     character conversion

SYNOPSIS
     #include <stdlib.h>
     #include <wchar.h>

     int mbtowc(wchart *pwc, const char *s, sizet n);

     int mblen(const char *s, sizet n);

     int wctomb(char *s, wchart wchar);

     sizet mbrlen(const char *s, sizet n, mbstatet *ps);

     sizet mbrtowc(wchart *pwc, const char *s, sizet n, mbstatet *ps);

     sizet wcrtomb(char *s, wchart wc, mbstatet *ps);

DESCRIPTION
     Multibyte characters are used to represent characters in an extended
     character set. This is needed for locales where 8 bits are not enough
     to represent all the characters in the character set.

     These functions are allow multibyte characters to be translated into
     wide-characters and vice versa. Wide-characters have type wchart
     (defined in stdlib.h), which is an integral type whose range of values
     can represent distinct codes for all members of the largest extended
     character set specified among the supported locales.

     A maximum of 3 extended character sets are supported for each locale.
     The number of bytes in an extended character set is defined by the
     LCCTYPE category of the locale [see setlocale(3C)]. However, the max-
     imum number of bytes in any multibyte character will never be greater
     than MBLENMAX, a constant defined in limits.h. The maximum number of
     bytes in a character in an extended character set in the current
     locale is given by the macro MBCURMAX, which is defined in stdlib.h.

     mbtowc() determines the number of bytes that comprise the multibyte
     character pointed to by s. Also, if pwc is not a null pointer,
     mbtowc() 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. At most n
     characters will be examined, starting at the character pointed to by s.

     If s is a null pointer, mbtowc() simply returns 0. If s is not a null
     pointer, then, if s points to the null character, mbtowc() returns 0;
     if the next n or fewer bytes form a valid multibyte character,
     mbtowc() returns the number of bytes that comprise the converted mul-
     tibyte character; otherwise, s does not point to a valid multibyte
     character and mbtowc() returns -1.



Page 1                       Reliant UNIX 5.44                Printed 11/98

mbchar(3C)                                                       mbchar(3C)

     mblen() determines the number of bytes comprising the multibyte char-
     acter pointed to by s. This function is equivalent to the call:

          mbtowc((wchart *)0, s, n);

     wctomb() determines the number of bytes needed to represent the multi-
     byte 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. At most MBCURMAX characters are
     stored.

     If s is a null pointer, wctomb() simply returns 0. If s is not a null
     pointer, wctomb() returns -1 if the value of wchar does not correspond
     to a valid multibyte character; otherwise it returns the number of
     bytes that comprise the multibyte character corresponding to the value
     of wchar.

   Restartable multibyte/wide-character conversion functions

     These functions differ from the corresponding multibyte character
     functions of mblen(), mbtowc(), and wctomb() in that they have an
     extra parameter, ps, of type pointer to mbstatet that points to an
     object that can completely describe the current conversion state of
     the associated multibyte character sequence. If ps is a null pointer,
     each function uses its own internal mbstatet object instead, which is
     initialized at program startup to the initial conversion state. The
     implementation behaves as if no library function calls these functions
     with a null pointer for ps.

     The mbrlen() function is equivalent to the call:

          mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)

     where internal is the mbstatet object for the mbrlen() function.

     The mbrlen() function returns (sizet)-2, (sizet)-1, a value between
     zero and n, inclusive.

     If s is a null pointer, the mbrtowc() function is equivalent to the
     call:

          mbrtowc(NULL, "", l, ps)

     In this case, the values of the parameters pwc and n are ignored.

     If s is a null pointer, the wcrtomb() function is equivalent to the
     call:

          wcrtobm(buf, L'\0', ps)

     where buf is an internal buffer.



Page 2                       Reliant UNIX 5.44                Printed 11/98

mbchar(3C)                                                       mbchar(3C)

SEE ALSO
     chrtbl(1M), mbstring(3C), setlocale(3C), environ(5), stdlib(5),
     wchar(5).



















































Page 3                       Reliant UNIX 5.44                Printed 11/98