# mbrlen

> C++ Atlas: `cppatlas.com/w/c/string/multibyte/mbrlen` | Source: https://en.cppreference.com/w/c/string/multibyte/mbrlen | Domain: Strings | Standards: C95, C99

Determines the size, in bytes, of the representation of a multibyte character.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <wchar.h>
size_t mbrlen( const char* s, size_t n, mbstate_t* ps ); // (since C95) (until C99)
size_t mbrlen( const char* restrict s, size_t n, mbstate_t* restrict ps ); // (since C99)
```

Determines the size, in bytes, of the representation of a multibyte character.

This function is equivalent to the call `mbrtowc(NULL, s, n, ps ? ps: &internal)` for some hidden object `internal` of type `mbstate_t`, except that the expression `ps` is evaluated only once.

### Parameters

- `s` - pointer to an element of a multibyte character string
- `n` - limit on the number of bytes in s that can be examined
- `ps` - pointer to the variable holding the conversion state

### Return value

The first of the following that applies:

- `​0​` if the next `n` or fewer bytes complete the null character or if `s` is a null pointer. Both cases reset the conversion state.
- the number of bytes `[1...n]` that complete a valid multibyte character
- `(size_t)-2` if the next `n` bytes are part of a possibly valid multibyte character, which is still incomplete after examining all `n` bytes
- `(size_t)-1` if encoding error occurs. The value of `errno` is `EILSEQ`; the conversion state is unspecified.

### Example

```c
#include <locale.h>
#include <stdio.h>
#include <string.h>
#include <wchar.h>

int main(void)
{
    // allow mbrlen() to work with UTF-8 multibyte encoding
    setlocale(LC_ALL, "en_US.utf8");

    // UTF-8 narrow multibyte encoding
    const char* str = "水";
    size_t sz = strlen(str);

    mbstate_t mb;
    memset(&mb, 0, sizeof mb);
    int len1 = mbrlen(str, 1, &mb);
    if (len1 == -2)
        printf("The first 1 byte of %s is an incomplete multibyte char"
               " (mbrlen returns -2)\n", str);

    int len2 = mbrlen(str + 1, sz - 1, &mb);
    printf("The remaining %zu  bytes of %s hold %d bytes of the multibyte"
           " character\n", sz - 1, str, len2);

    printf("Attempting to call mbrlen() in the middle of %s while in initial"
           " shift state returns %zd\n", str, mbrlen(str + 1, sz - 1, &mb));
}
```

Output:

```text
The first 1 byte of 水 is an incomplete multibyte char (mbrlen returns -2)
The remaining 2  bytes of 水 hold 2 bytes of the multibyte character
Attempting to call mbrlen() in the middle of 水 while in initial shift state returns -1
```

### References

- C23 standard (ISO/IEC 9899:2024):

  - 7.29.6.3.1 The mbrlen function (p: TBD)

- C17 standard (ISO/IEC 9899:2018):

  - 7.29.6.3.1 The mbrlen function (p: TBD)

- C11 standard (ISO/IEC 9899:2011):

  - 7.29.6.3.1 The mbrlen function (p: 442)

- C99 standard (ISO/IEC 9899:1999):

  - 7.24.6.3.1 The mbrlen function (p: 388)

### See also

- [`mbrtowc`](https://en.cppreference.com/w/c/string/multibyte/mbrtowc) (C95): converts the next multibyte character to wide character, given state (function)
- [`mblen`](https://en.cppreference.com/w/c/string/multibyte/mblen): returns the number of bytes in the next multibyte character (function)
- [C++ documentation for `mbrlen`](https://en.cppreference.com/w/cpp/string/multibyte/mbrlen)

---
Attribution: content from https://en.cppreference.com/w/c/string/multibyte/mbrlen (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.