February 3, 2002 MBLEN 3

### NAME

mblen - get number of bytes in a multibyte character

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```int` mblen(```const char *s``, size_t n`)

### DESCRIPTION

The mblen(``) 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`.

In state-dependent encodings, ```s` may point the special sequence bytes to change the shift-state. Although such sequence bytes corresponds to no individual wide-character code, the mblen(``) changes the own state by them and treats them as if they are a part of the subsequent multibyte character.

Unlike mbrlen(3), the first ```n` bytes pointed to by ```s` need to form an entire multibyte character. Otherwise, this function causes an error.

mblen(``) is equivalent to the following call, except the internal state of the mbtowc(3) function is not affected:

  `

      mbtowc(NULL, s, n);

  `

Calling any other functions in Standard C Library (libc, -lc) never changes the internal state of mblen(``), except for calling setlocale(3) with the ```LC_CTYPE` category changed to that of the current locale. Such setlocale(3) calls cause the internal state of this function to be indeterminate.

The behaviour of mblen(``) is affected by the ```LC_CTYPE` category of the current locale.

These are the special cases:

s == NULL
  mblen(``) initializes its own internal state to an initial state, and determines whether the current encoding is state-dependent. This function returns 0 if the encoding is state-independent, otherwise non-zero.

n == 0
  In this case, the first ```n` bytes of the array pointed to by ```s` never form a complete character. Thus, mblen(``) always fails.

### RETURN VALUES

Normally, mblen(``) 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.

-1
  ```s` points to an invalid or incomplete multibyte character. The mblen(``) also sets errno to indicate the error.

When ```s` is equal to ```NULL`, the mblen(``) returns:

0
  The current encoding is state-independent.

non-zero
  The current encoding is state-dependent.

### ERRORS

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

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

### SEE ALSO

mbrlen(3), mbtowc(3), setlocale(3)

### STANDARDS

The mblen(``) function conforms to ANSI X3.159-1989 (``ANSI C89'') .