C in a Nutshell

Name

mbrlen

Synopsis

Determines the length of a multibyte character and saves the parse state

#include <stdlib.h>
size_tmbrlen( const char * restrict s, size_t maxsize,
               mbstate_t * restrict state );

The mbrlen() function, like mblen(), determines the length in bytes of a multibyte character referenced by its first argument. Its additional parameter, a pointer to an mbstate_t object, describes the parse state (also called the shift state) of a multibyte character sequence in the given encoding. mbrlen() updates this parse-state object after analyzing the multibyte character in the string, so that you can use it in a subsequent function call to interpret the next character correctly. (Hence the additional “r” in the function name, which stands for “restartable.”) If the final argument is a null pointer, mbrlen() uses an internal, static mbstate_t object.

The possible return values are as follows:

Positive values

The return value is the length of the multibyte character.

0

The first multibyte character in the string is a null character. In this case, mbrlen() sets the parse state object to the initial state.

-1

The first argument does not point to a valid multibyte character. The mbrlen() function sets the errno variable to EILSEQ and leaves the mbstate_t object in an undefined state.

-2

The first argument does not point to a valid multibyte character within the specified maximum number of bytes. The sequence may be the beginning of a valid but longer multibyte character.

The LC_TYPE category in ...