MBRLEN(3) | Library Functions Manual | MBRLEN(3)

# NAME

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

# SYNOPSIS

`#include <wchar.h>`

size_t
`mbrlen`(const char * restrict s, size_t n, mbstate_t * restrict ps);

# DESCRIPTION

The `mbrlen`() function returns the number of bytes in the first multibyte character of the multibyte string s. It examines at most the first n bytes of s.

`mbrlen`() is equivalent to the following call, except that ps is evaluated only once:

    mbrtowc(NULL, s, n, (ps != NULL) ? ps : &internal);

Here, internal is an internal state object automatically initialized to the initial conversion state at startup time of the program.

In state-dependent encodings, s may point to special sequence bytes changing the shift state. Although such sequence bytes correspond to no wide character, they affect the conversion state object pointed to by ps, and `mbrlen`() treats the special sequence bytes as if they were part of the subsequent multibyte character.

Unlike mblen(3), `mbrlen`() accepts the byte sequence if it is not a complete character but the initial part of some valid character. In this case, this function accepts all such bytes and saves 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.

There are the special cases:

s == NULL
  `mbrlen`() sets the conversion state object pointed to by ps to the initial conversion 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 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 the ps argument.

  Calling any other function in libc never changes the internal state of `mbrlen`(), except for calling setlocale(3) with an `LC_CTYPE` that differs from the current locale. Such setlocale(3) calls cause the internal state of this function to become indeterminate.

# RETURN VALUES

The `mbrlen`() function returns:

0
  s points to a NUL byte (‘\0’).
positive
  The value returned is the number of bytes in the valid multibyte character pointed to by s. There are no cases where this value is greater than n or the value of the `MB_CUR_MAX` macro.
(size_t)-2
  The first n bytes of s contain an incomplete multibyte character that can potentially be completed by reading more bytes. When n is at least `MB_CUR_MAX`, this can only occur if 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 cases:

[`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:1995 (“ISO C90, Amendment 1”). The restrict qualifier is added at ISO/IEC 9899/1999 (“ISO C99”).

March 29, 2022 | Debian