mbrlen() -- determine length of multibyte character using conversion states

SYNOPSIS

#include <wchar.h>

size_t mbrlen(const char *s, size_t n, mbstate_t *ps);

DESCRIPTION

If s is not null, the mbrlen() function determines the number of bytes constituting the character pointed to. It is equivalent to:

mbstate_t internal;
mbrtowc(NULL, s, n, ps != NULL ? ps : &internal);

If the specified state pointer is null, the mbrlen() function uses its own internal mbstate_t object, which is initialized at program startup to the initial conversion state. Otherwise, the specified mbstate_t object is used to completely describe the current conversion state of the associated character sequence.

The behavior of this function is affected by the LC_CTYPE category of the current locale.

PARAMETERS

s: Points to the string whose bytes are to be counted.
n: Specifies the maximum number of bytes to examine.
ps: Is the conversion state. If this is null, an internal mbstate_t object is used.

RETURN VALUES

The mbrlen() function returns the first of the following that applies:

0: If the next n or fewer bytes complete the character that corresponds to the null wide character.
positive number: If the next n or fewer bytes complete a valid character; the value returned is the number of bytes that complete the character.
-2: If the next n bytes contribute to an incomplete by potentially valid character, and all n bytes have been processed. When n has at least the value of MB_CUR_MAX, this case can only occur if s points at a sequence of redundant shift sequences (for locales with state-dependent encodings).
-1: If an encoding error occurs, in which case the next n or fewer bytes do not contribute to a complete and valid character. In this case, errno is set to EILSEQ, and the conversion state is undefined.