---
name: "mbrlen"
section: "3"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/mbrlen"
---

# mbrlen(3)

determine number of bytes in next multibyte character

## NAME

mbrlen - determine number of bytes in next multibyte character

## LIBRARY

Standard C library (*libc*, *-lc*)

## SYNOPSIS

```
#include <wchar.h>
```

**size\_t mbrlen(**size\_t n;               **const char** *s***\[restrict** *n***\], size\_t** *n***,**               **mbstate\_t \*restrict** *ps***);**

## DESCRIPTION

The **mbrlen**() function inspects at most *n* bytes of the multibyte string starting at *s* and extracts the next complete multibyte character. It updates the shift state *\*ps*. If the multibyte character is not the null wide character, it returns the number of bytes that were consumed from *s*. If the multibyte character is the null wide character, it resets the shift state *\*ps* to the initial state and returns 0.

If the *n* bytes starting at *s* do not contain a complete multibyte character, **mbrlen**() returns *(size\_t) -2*. This can happen even if *n* \>= *MB\_CUR\_MAX*, if the multibyte string contains redundant shift sequences.

If the multibyte string starting at *s* contains an invalid multibyte sequence before the next complete character, **mbrlen**() returns *(size\_t) -1* and sets *errno* to **EILSEQ**. In this case, the effects on *\*ps* are undefined.

If *ps* is NULL, a static anonymous state known only to the **mbrlen**() function is used instead.

## RETURN VALUE

The **mbrlen**() function returns the number of bytes parsed from the multibyte sequence starting at *s*, if a non-null wide character was recognized. It returns 0, if a null wide character was recognized. It returns *(size\_t) -1* and sets *errno* to **EILSEQ**, if an invalid multibyte sequence was encountered. It returns *(size\_t) -2* if it couldn't parse a complete multibyte character, meaning that *n* should be increased.

## ATTRIBUTES

For an explanation of the terms used in this section, see [**attributes**(7)](/attributes/7.md).

| | | |
| --- | --- | --- |
| **Interface** | **Attribute** | **Value** |
| **mbrlen**() | Thread safety | MT-Unsafe race:mbrlen/!ps |

## STANDARDS

C11, POSIX.1-2008.

## HISTORY

POSIX.1-2001, C99.

## NOTES

The behavior of **mbrlen**() depends on the **LC\_CTYPE** category of the current locale.

## SEE ALSO

[**mbrtowc**(3)](/mbrtowc/3.md)