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

NAME
     mmbbrrlleenn, mmbbrrlleennll - get number of bytes in a character (restartable)

LLIIBBRRAARRYY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##iinncclluuddee <>

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

     ##iinncclluuddee <>

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

DESCRIPTION
     The mmbbrrlleenn() 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 NULL, mmbbrrlleenn() uses an internal, static mbstatet object, which is
     initialized to the initial conversion state at program startup.

     It is equivalent to:

           mbrtowc(NULL, s, n, ps);

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

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

RETURN VALUES
     The mmbbrrlleenn() 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, mmbbrrlleenn()
             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.

EEXXAAMMPPLLEESS
     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);
           }

EERRRROORRSS
     The mmbbrrlleenn() 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 mmbbrrlleenn() function conforms to ISO/IEC 9899:1999 (``ISO C99'').

BSD                              April 7, 2004                             BSD