MirOS Manual: mbrlen(3)

MBRLEN(3)                  BSD Programmer's Manual                   MBRLEN(3)

NAME

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

SYNOPSIS

     #include <wchar.h>

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

DESCRIPTION

     The mbrlen() function usually determines the number of bytes in a multi-
     byte character pointed to by s and returns it. This function shall only
     examine max n bytes of the array beginning from s.

     mbrlen() is equivalent to the following call (except ps is evaluated only
     once):

           mbrtowc(NULL, s, n, (ps != NULL) ? ps : &internal);

     Here, internal is an internal state object.

     In state-dependent encodings, s may point to the special sequence bytes
     to change the shift-state. Although such sequence bytes corresponds to no
     individual wide-character code, these affect the conversion state object
     pointed to by ps, and the mbrlen() treats the special sequence bytes as
     if these are a part of the subsequent multibyte character.

     Unlike mblen(3), mbrlen() may accept the byte sequence when it is not a
     complete character but possibly contains part of a valid character. In
     this case, this function will accept all such bytes and save them into
     the conversion state object pointed to by ps. They will be used on subse-
     quent calls of this function to restart the conversion suspended.

     The behaviour of the mbrlen() is affected by LC_CTYPE category of the
     current locale.

     There are the special cases:

     s == NULL   mbrlen() sets the conversion state object pointed to by ps to
                 an initial state and always returns 0. Unlike mblen(3), the
                 value returned does not indicate whether the current encoding
                 of the locale is state-dependent.

                 In this case, mbrlen() ignores n.

     n == 0      In this case, the first n bytes of the array pointed to by s
                 never form a complete character. Thus, mbrlen() always re-
                 turns (size_t)-2.

     ps == NULL  mbrlen() uses its own internal state object to keep the
                 conversion state, instead of ps mentioned in this manual
                 page.

                 Calling any other functions in libc never change the internal
                 state of mbrlen(), except for calling setlocale(3) with a
                 changing LC_CTYPE category of the current locale. Such
                 setlocale(3) calls cause the internal state of this function
                 to be indeterminate. This internal state is initialized at
                 startup time of the program.

RETURN VALUES

     The mbrlen() returns:

     0           s points to a null byte ('\0').
     positive    The value returned is a number of bytes for the valid multi-
                 byte character pointed to by s. There are no cases where this
                 value is greater than n or the value of the MB_CUR_MAX macro.

     (size_t)-2  s points to the byte sequence which possibly contains part of
                 a valid multibyte character, but which is incomplete. When n
                 is at least MB_CUR_MAX can only occur if the array pointed to
                 by s contains a redundant shift sequence.

     (size_t)-1  s points to an illegal byte sequence which does not form a
                 valid multibyte character. In this case, mbrtowc() sets errno
                 to indicate the error.

ERRORS

     mbrlen() may cause an error in the following cases:

     [EILSEQ]      s points to an invalid multibyte character.

     [EINVAL]      ps points to an invalid or uninitialized mbstate_t object.

SEE ALSO

     mblen(3), mbrtowc(3), setlocale(3)

STANDARDS

     The mbrlen() function conforms to ISO/IEC 9899/AMD1:1995 ("ISO C90").

MirOS BSD #10-current          February 3, 2002                              1

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.