MBRLEN(3) | Library Functions Manual | MBRLEN(3) |
mbrlen
—
#include <wchar.h>
size_t
mbrlen
(const
char * restrict s, size_t
n, mbstate_t * restrict
ps);
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:
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.
mbrlen
() always returns (size_t)-2.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.
mbrlen
() returns:
MB_CUR_MAX
macro.MB_CUR_MAX
, this case can only occur if the array
pointed to by s contains a redundant shift
sequence.mbrtowc
() sets errno to
indicate the error.mbrlen
() may cause an error in the following case:
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”).
February 3, 2002 | NetBSD 9.2 |