get number of bytes in a multibyte
char * restrict s, size_t
n, mbstate_t * restrict
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
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
treats the special sequence bytes as if these are a part of the subsequent
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 the
is affected by
LC_CTYPE category of the current
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 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 conversion state, instead of ps mentioned in this manual page.
Calling any other functions in libc never change the internal state of
mbrlen(), except for calling setlocale(3) with a changing
LC_CTYPEcategory 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 (‘\0’).
- 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 of the
- 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_MAXcan 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.
mbrlen() may cause an error in the
- s points to an invalid multibyte character.
- ps points to an invalid or uninitialized mbstate_t object.
mblen(3), mbrtowc(3), setlocale(3)
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”).