MBRLEN(3)                BSD Library Functions Manual                MBRLEN(3)

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

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##include <>

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

     ##include <>

     sizet
     mbrlenl(const char * restrict s, sizet n, mbstatet * restrict ps,
         localet loc);

DESCRIPTION
     The mbrlen() function inspects at most n bytes pointed to by s to deter-
     mine the number of bytes needed to complete the next multibyte character.

     The mbstatet argument, ps, is used to keep track of the shift state.  If
     it is NUL, mbrlen() uses an internal, static mbstatet object, which is
     initialized to the initial conversion state at program startup.

     It is equivalent to:

           mbrtowc(NUL, s, n, ps);

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

     While the mbrlen() function uses the current locale, the mbrlenl() func-
     tion may be passed a locale directly. See xlocale(3) for more informa-
     tion.

RETURN VALUES
     The mbrlen() functions returns:

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

     >0      The next n or fewer bytes represent a valid character, mbrlen()
             returns the number of bytes used to complete the multibyte char-
             acter.

     (sizet)-2
             The next n contribute to, but do not complete, a valid multibyte
             character sequence, and all n bytes have been processed.

     (sizet)-1
             An encoding error has occurred.  The next n or fewer bytes do not
             contribute to a valid multibyte character.

EXAMPLES
     A function that calculates the number of characters in a multibyte char-
     acter string:

           sizet
           nchars(const char *s)
           {
                   sizet charlen, chars;
                   mbstatet mbs;

                   chars = 0;
                   memset(&mbs, 0, sizeof(mbs));
                   while ((charlen = mbrlen(s, MBCURMAX, &mbs)) != 0 &&
                       charlen != (sizet)-1 && charlen != (sizet)-2) {
                           s ]= charlen;
                           chars];
                   }

                   return (chars);
           }

ERORS
     The mbrlen() function will fail if:

     [EILSEQ]           An invalid multibyte sequence was detected.

     [EINVAL]           The conversion state is invalid.

SEE ALSO
     mblen(3), mbrtowc(3), multibyte(3), xlocale(3)

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

BSD                              April 7, 2004                             BSD