get number of bytes in a multibyte character
char * restrict s
mbstate_t * restrict
() function usually determines the
number of bytes in a multibyte character pointed to by
and returns it. This function shall only
examine max n bytes of the array beginning from
() is equivalent to the following call
is evaluated only once):
mbrtowc(NULL, s, n, (ps != NULL) ? ps : &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
() treats the special sequence
bytes as if these are a part of the subsequent multibyte character.
() 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
. They will be used on subsequent calls of
this function to restart the conversion suspended.
The behaviour of the
() is affected by
category of the current locale.
There 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
In this case,
- n == 0
- In this case, the first n bytes of the
array pointed to by s never form a
complete character. Thus,
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 libc never
change the internal state of
except for calling
setlocale(3) with a
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.
- s points to a null byte
- The value returned is a number of bytes for the valid multibyte character
pointed to by s. There are no cases where
this value is greater than n or the value
- 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 can only occur if the array
pointed to by s contains a redundant
- s points to an illegal byte sequence
which does not form a valid multibyte character. In this case,
errno to indicate the error.
() may cause an error in the following
- s points to an invalid multibyte
- ps points to an invalid or uninitialized
() function conforms to ISO/IEC
9899/AMD1:1995 (“ISO C90, Amendment 1”). The restrict qualifier
is added at ISO/IEC 9899/1999 (“ISO C99”).