mbrlen(3C)




NAME

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


SYNOPSIS

     #include <wchar.h>

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


DESCRIPTION

     If s is not a null pointer,  mbrlen() determines the  number
     of  bytes constituting the character pointed to by  s. It is
     equivalent to:

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

     If ps is a null pointer, the mbrlen() function uses its  own
     internal  mbstate_t  object, which is initialized at program
     startup to the initial conversion  state.    Otherwise,  the
     mbstate_t  object  pointed  to  by  ps is used to completely
     describe the current  conversion  state  of  the  associated
     character  sequence.   Solaris will behave as if no function
     defined in the Solaris Reference Manual calls mbrlen().

     The behavior of this function is affected  by  the  LC_CTYPE
     category of the current locale.  See environ(5).


RETURN VALUES

     The mbrlen() function returns the  first  of  the  following
     that applies:

     0     If the next n or fewer bytes  complete  the  character
           that corresponds to the null wide-character.

     positive
           If the next n or fewer bytes complete a valid  charac-
           ter;  the  value  returned is the number of bytes that
           complete the character.

     (size_t)-2
           If the next n bytes contribute to  an  incomplete  but
           potentially  valid   character,  and  all n bytes have
           been processed. When n has at least the value  of  the
           MB_CUR_MAX  macro,  this  case  can  only  occur if  s
           points at a sequence of redundant shift sequences (for
           implementations with state-dependent encodings).

     (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  character.  In this case, EILSEQ is  stored  in
           errno and the conversion state is undefined.


ERRORS

     The mbrlen() function may fail if:

     EINVAL
           The ps argument points to an object that  contains  an
           invalid conversion state.

     EILSEQ
           Invalid character sequence is detected.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | See NOTES below             |
    |_____________________________|_____________________________|


SEE ALSO

     mbrtowc(3C),  mbsinit(3C),   setlocale(3C),   attributes(5),
     environ(5)


NOTES

     If ps is not a null pointer,  mbrlen()  uses  the  mbstate_t
     object  pointed to by ps and the function can be used safely
     in multithreaded applications, as long as  setlocale(3C)  is
     not  being  called  to  change  the  locale. If ps is a null
     pointer, mbrlen() uses its internal mbstate_t object and the
     function is Unsafe in multithreaded applications.


Man(1) output converted with man2html