NAME    [Toc]    [Back]

     mbrlen -- get number of bytes in a character (restartable)

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <wchar.h>

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

DESCRIPTION    [Toc]    [Back]

     The mbrlen() function determines the number of bytes constituting the
     multibyte character sequence pointed to by s, examining at most n bytes.

     The mbstate_t argument, ps, is used to keep track of the shift state.  If
     it is NULL, mbrlen() uses an internal, static mbstate_t object.

     It is equivalent to:

	   mbrtowc(NULL, s, n, ps);

     Except that when ps is a NULL pointer, mbrlen() uses its own static,
     internal mbstate_t object to keep track of the shift state.

RETURN VALUES    [Toc]    [Back]

     The mbrlen() functions returns:

     0	     The first n or fewer bytes of s represent the null wide character
	     (L'\0').

     >0      The first n or fewer bytes of s represent a valid character,
	     mbrtowc() returns the length (in bytes) of the multibyte
	     sequence.

     (size_t)-2
	     The first n bytes of s are an incomplete multibyte sequence.

     (size_t)-1
	     The byte sequence pointed to by s is an invalid multibyte
	     sequence.

EXAMPLES    [Toc]    [Back]

     A function which calculates the number of characters in a multibyte character
 string:

	   size_t
	   nchars(const char *s)
	   {
		   size_t charlen, chars;
		   mbstate_t mbs;

		   chars = 0;
		   memset(&mbs, 0, sizeof(mbs));
		   while ((charlen = mbrlen(s, MB_CUR_MAX, &mbs)) != 0 &&
		       charlen != (size_t)-1 && charlen != (size_t)-2) {
			   s += charlen;
			   chars++;
		   }

		   return (chars);
	   }

ERRORS    [Toc]    [Back]

     The mbrlen() function will fail if:

     [EILSEQ]		An invalid multibyte sequence was detected.

SEE ALSO    [Toc]    [Back]

     mblen(3), mbrtowc(3)

STANDARDS    [Toc]    [Back]

     The mbrlen() function conforms to ISO/IEC 9899:1999 (``ISO C99'').

BUGS    [Toc]    [Back]

     The current implementation does not support shift states.


FreeBSD 5.2.1		       November 11, 2002		 FreeBSD 5.2.1