mbrlen man page on Minix

Man page or keyword search:  
man Server   6208 pages
apropos Keyword Search (all sections)
Output format
Minix logo
[printable version]

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 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 sub‐
     sequent 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 complete character.  Thus, mbrlen() always
		 returns (size_t)-2.

     ps == NULL	 mbrlen() uses its own internal state object to keep the con‐
		 version 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 multi‐
		 byte 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 character.  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
[top]

List of man pages available for Minix

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net