size_t
mbrlen(
const char * restrict s
, size_t n
, mbstate_t * restrict ps
)
)
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:
)
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
bytes of the array pointed to by
s
never form a complete character.
Thus,
mbrlen(
)
always returns (size_t)-2.
)
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.
)
returns:
s
points to a nul byte
(`\0').
s
.
There are no cases that this value is greater than
n
or the value of the
MB_CUR_MAX
macro.
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.
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.
)
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.
)
function conforms to
ISO/IEC 9899/AMD1:1990 (``ISO C90'') .
The restrict qualifier is added at
ISO/IEC 9899:1999 (``ISO C99'') .