MBRLEN(3) BSD Library Functions Manual MBRLEN(3)
NAME
mbrlen -- get number of bytes in a multibyte character (restartable)
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <wchar.h>
size_t
mbrlen(const char * restrict s, size_t n, mbstate_t * restrict ps);
DESCRIPTION
The 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:
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 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.
RETURN VALUES
The mbrlen() returns:
0 s points to a nul byte ('