Manual Pages for UNIX Operating System command usage for man mbrlen

Standard C Library Functions                           mbrlen(3C)



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

SYNOPSIS
     #include 

     size_t mbrlen(const char *restrict s, size_t n, mbstate_t *restrict 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  character; the value returned is the
                      number of bytes that complete  the  charac-
                      ter.


     (size_t)-2       If the next n bytes contribute to an incom-
                      plete 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



SunOS 5.11           Last change: 1 Nov 2003                    1






Standard C Library Functions                           mbrlen(3C)



                      implementations with state-dependent encod-
                      ings).


     (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       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | See NOTES below             |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


SEE ALSO
     mbrtowc(3C),  mbsinit(3C),   setlocale(3C),   attributes(5),
     environ(5), standards(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.






SunOS 5.11           Last change: 1 Nov 2003                    2