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

#include <stdlib.h>
size_t mbrlen ( 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 the current locale settings determines which byte sequences are valid multibyte characters.

Example

See the example for mblen( ) in this chapter.

See Also

mblen( ), mbrtowc( )