Unix/Linux Go Back    


NetBSD 6.1.5 - man page for mbrlen (netbsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <wchar.h>

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

DESCRIPTION
     The mbrlen() function usually determines the number of bytes in a multibyte 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 subsequent calls of this function to restart the conversion suspended.

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

     These 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 com-
		 plete character.  Thus, mbrlen() always returns (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 Standard C Library (libc, -lc) never changes 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 nul byte ('\0').

     positive	 The value returned is a number of bytes for the valid multibyte character
		 pointed to by s.  There are no cases that 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, this case
		 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 char-
		 acter.  In this case, mbrtowc() sets errno to indicate the error.

ERRORS
     mbrlen() may cause an error in the following case:

     [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, Amendment 1'').  The
     restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99'').

BSD					 February 3, 2002				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 10:51 PM.