MBLEN(3)

MBLEN(3) | Library Functions Manual | MBLEN(3)

# NAME

`mblen` —
get number of bytes in a multibyte character

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <stdlib.h>`

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”).

February 3, 2002 | NetBSD 9.0