February 3, 2002 MBRLEN 3

### NAME

mbrlen - get number of bytes in a multibyte character (restartable)

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```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 (`\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.

(size_t)-2
  ```s` points to the byte sequence which possibly contains part of a valid multibyte character, but which is incomplete. When ```n` is at least ```MB_CUR_MAX`, this case can only occur if the array pointed to by ```s` contains a redundant shift sequence.

(size_t)-1
  ```s` points to an illegal byte sequence which does not form a valid multibyte character. In this case, mbrtowc(``) sets errno to indicate the error.

### ERRORS

mbrlen(``) may cause an error in the following case:

[```EILSEQ`]
  ```s` points to an invalid multibyte character.

[```EINVAL`]
  ```ps` points to an invalid or uninitialized mbstate_t object.

### SEE ALSO

mblen(3), mbrtowc(3), setlocale(3)

### STANDARDS

The mbrlen(``) function conforms to ISO/IEC 9899/AMD1:1990 (``ISO C90'') . The restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99'') .