mblen(3)						     Library Functions Manual							  mblen(3)

NAME

       mblen, mbrlen - Determines the length in bytes of a multibyte character

LIBRARY

       Standard C Library (libc.so, libc.a)

SYNOPSIS

       #include <stdlib.h>

       int mblen(
	       const char *mbs,
	       size_t n);

       #include <wchar.h>

       size_t mbrlen(
	       const char *mbs,
	       size_t n,
	       mbstate_t *ps );

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       mblen():  ISO C, XPG4

       mbrlen():  ISO C

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Points to a multibyte-character string.	Specifies the maximum number of bytes to consider.  Points to an mbstate_t structure that contains
       the current conversion state of the multibyte-character string.

DESCRIPTION

       The mblen() function determines the number of bytes in a multibyte character. The behavior of the  mblen()  function  is  affected  by  the
       LC_CTYPE category of the current locale.

       In locales with shift-state character encoding, a call to mblen() with a null pointer as the mbs parameter, places the function in the ini-
       tial shift state. A call to mblen() with an mbs parameter that is not a null pointer may change the shift state	for  subsequent  calls	to
       mblen(),  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 mblen() function.

       In the case of nonrestartable functions, such as mblen(), conversion to shift-state encoding must first be enabled by calling the  function
       with a null pointer parameter and then calling the function again with the wide-character value to be converted.  The status of the conver-
       sion operation after the call is not available to subsequent calls.

       The mbrlen() function is a restartable version of mblen(), which means that, for locales that define state-dependent  encoding,	the  shift
       state  for  the	character  in  mbs is maintained in the mbstate_t structure and is therefore available to subsequent calls by mbrlen() and
       other restartable conversion functions.

RESTRICTIONS

       The mbrlen() and other restartable versions of conversion routines are functional only when used  with  locales	that  support  shift-state
       encoding.   Currently,  the  Tru64  UNIX  product  does	not provide any locales that use shift-state encoding.	Therefore, the mblen() and
       mbrlen() functions have the same run-time behavior and always return values for the nonshift-state case.

RETURN VALUES

       If the mbs parameter is not a null pointer, the mblen() function returns a value determined as follows: The number of bytes in the  charac-
       ter,  if  the number of bytes is n or fewer and if mbs points to a valid multibyte character other than the null character Zero (0), if mbs
       points to the null character -1, if mbs does not point to a valid multibyte character or if the length of the character in  bytes  is  more
       than the value of the n parameter or the MB_CUR_MAX variable

	      In this case, mblen() also sets errno to indicate the error.

       If  mbs	is  not  a  null pointer, the mbrlen() function returns the first value that applies in the following list: Zero, if the next n or
       fewer bytes constitute a null wide character 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 (size_t)-2, if the next n bytes contribute to an incomplete (but potentially
       valid) multibyte character (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, the mbrlen() function sets errno to indicate the error and the conversion state is undefined.

       If  the	mbs  parameter is a null pointer, the mblen() and mbrlen() functions both return one of the following values, depending on whether
       the current locale supports shift-state character encoding: A nonzero value, if the character encoding is shift-state dependent	Zero  (0),
       if the character encoding is not shift-state dependent

ERRORS

       If  the following condition occurs, the mblen() and mbrlen() functions set errno to the corresponding value: The mbs parameter points to an
       invalid multibyte character.

RELATED INFORMATION

       Functions: btowc(3), mbsinit(3), mbtowc(3), wctomb(3), mbstowcs(3), wcslen(3), wcstombs(3), wctob(3) delim off

																	  mblen(3)