MBLEN(3) BSD Library Functions Manual MBLEN(3)
mblen -- get number of bytes in a multibyte character
Standard C Library (libc, -lc)
mblen(const char *s, size_t n);
The mblen() 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
In state-dependent encodings, s may point the special sequence bytes to change the shift-
state. Although such sequence bytes corresponds to no individual wide-character code, the
mblen() changes the own state by them and treats them as if they are a part of the subse-
quent multibyte character.
Unlike mbrlen(3), the first n bytes pointed to by s need to form an entire multibyte charac-
ter. Otherwise, this function causes an error.
mblen() is equivalent to the following call, except the internal state of the mbtowc(3)
function is not affected:
mbtowc(NULL, s, n);
Calling any other functions in Standard C Library (libc, -lc) never changes the internal
state of mblen(), except for calling setlocale(3) with the LC_CTYPE category changed to that
of the current locale. Such setlocale(3) calls cause the internal state of this function to
The behaviour of mblen() is affected by the LC_CTYPE category of the current locale.
These are the special cases:
s == NULL mblen() initializes its own internal state to an initial state, and determines
whether the current encoding is state-dependent. This function returns 0 if the
encoding is state-independent, otherwise non-zero.
n == 0 In this case, the first n bytes of the array pointed to by s never form a com-
plete character. Thus, mblen() always fails.
Normally, mblen() returns:
0 s points to a nul byte ('\0').
positive The value returned is a number of bytes for the valid multibyte 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.
-1 s points to an invalid or incomplete multibyte character. The mblen() also sets
errno to indicate the error.
When s is equal to NULL, the mblen() returns:
0 The current encoding is state-independent.
non-zero The current encoding is state-dependent.
mblen() may cause an error in the following case:
[EILSEQ] s points to an invalid or incomplete multibyte character.
mbrlen(3), mbtowc(3), setlocale(3)
The mblen() function conforms to ANSI X3.159-1989 (``ANSI C89'').
BSD February 3, 2002 BSD