multibyte(3C)															     multibyte(3C)

NAME

       mblen(), mbtowc(), mbstowcs(), wctomb(), wcstombs() - multibyte characters and strings conversions

SYNOPSIS

DESCRIPTION

       A  multibyte character is composed of one or more bytes that represent a "whole" character in a character encoding.  A wide character (type
       of is composed of a fixed number of bytes whose code value can represent any character in a character encoding.

       Determine the number of bytes in the multibyte character pointed to by
		   s.  Equivalent to:

		   If s is a null pointer, mblen returns a nonzero or zero value, depending on whether the multibyte character encodings do or	do
		   not	have  state-dependent encodings, respectively.	Since no character encodings currently supported by HP-UX are state-depen-
		   dent, zero is always returned in this case.	However, for maximum portability to other systems, application programs should not
		   depend on this.

		   If  s  is  not a null pointer, mblen returns the number of bytes in the 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.  If s points to  the  null	character,
		   mblen returns 0.

       Determine the number of bytes in the multibyte character pointed to by
		   s,  determine  the  code  for  the  value  of type corresponding to that multibyte character, then store the code in the object
		   pointed to by pwc.  The value of the code corresponding to the null character is zero.  At  most  n	characters  are  examined,
		   starting at the character pointed to by s.

		   If  s  is a null pointer, returns a non-zero or zero value, depending on whether the multibyte character encodings do or do not
		   have state-dependent encodings, respectively.  Since no character encodings currently supported by HP-UX  are  state-dependent,
		   zero  is  always  returned  in  this  case.	However, for maximum portability to other systems, application programs should not
		   depend on this.

		   If s is not a null pointer, returns the number of bytes in the converted multibyte character if the next n or fewer bytes  form
		   a valid multibyte character, or -1 if they do not form a valid multibyte character.	If s points to the null character, returns
		   0.  The value returned is never greater than n or the value of the macro.

       Determine the number of bytes needed to represent
		   the multibyte character corresponding to the code whose value is wchar and store the multibyte character representation in  the
		   array object pointed to by s.  At most characters are stored.

		   If  s  is  a null pointer, returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not
		   have state-dependent encodings, respectively.  Since no character encodings currently supported by HP-UX  are  state-dependent,
		   zero  is  always  returned  in  this  case.	However, for maximum portability to other systems, application programs should not
		   depend on this.

		   If s is not a null pointer, returns the number of bytes in the multibyte character corresponding to the value of wchar,  or	-1
		   if  the  value of wchar does not correspond to a valid multibyte character.	The value returned is never greater than the value
		   of the macro.

       Convert a sequence of multibyte characters
		   from the array pointed to by s into a sequence of corresponding codes and store these codes into the array pointed to by  pwcs,
		   stopping  after  either  n codes or a code with value zero (a converted null character) is stored.  Each multibyte character is
		   converted as if by a call to No more than n elements are modified in the array pointed to by pwcs.

		   If an invalid multibyte character is encountered, returns (size_t)-1.  Otherwise, returns the number of  array  elements  modi-
		   fied, not including a terminating zero code, if any.  The array is not null- or zero-terminated if the value returned is n.	If
		   pwcs is a null pointer, returns the number of elements required for the wide-character-code array.

       Convert a sequence of codes corresponding to
		   multibyte characters from the array pointed to by pwcs into a sequence of multibyte characters and store them  into	the  array
		   pointed  to	by s, stopping if a multibyte character exceeds the limit of n total bytes or if a null character is stored.  Each
		   code is converted as if by a call to No more than n bytes are modified in the array pointed to by s.

		   If a code is encountered that does not correspond to a valid multibyte character, returns (size_t)-1.  Otherwise,  returns  the
		   number of bytes modified, not including a terminating null character, if any.  The array is not null- or zero-terminated if the
		   value returned is n.  If s is a null pointer, returns the number of bytes required for the character array.

EXTERNAL INFLUENCES

   Locale
       The category determines the behavior of the multibyte character and string functions.

ERRORS

       and may fail and is set if the following condition is encountered:

	      [EILSEQ]	     An invalid multibyte sequence or wide character code was found.

WARNINGS

       With the exception of ASCII characters, the code values of wide characters (type of are specific to the effective locale specified  by  the
       environment variable.  These values may not be compatible with values obtained by specifying other locales that are supported now, or which
       may be supported in the future.	It is recommended that wide character constants and wide string literals (see the not be  used,  and  that
       wide  character code values not be stored in files or devices because future standards may dictate changes in the code value assignments of
       the wide characters.  However, wide character constants and wide string literals corresponding to the characters of the ASCII code set  can
       be safely used since their values are guaranteed to be the same as their ASCII code set values.

AUTHOR

       The multibyte functions in this entry were developed by OSF and HP.

SEE ALSO

       setlocale(3C), wctype(3C), thread_safety(5), glossary(9).

STANDARDS CONFORMANCE

																     multibyte(3C)