mblen(3)

💖 mblen — bestie's guide to counting bytes in your next multibyte character 💖

okay so real talk, this is mblen(3), and it lives in the Standard C library (that's libc, aka -lc, aka the thing you already linked). it's giving "tiny function, big feelings" because it counts how many bytes your next multibyte character is eating. 🦋

---

✨ SYNOPSIS ✨

#include <stdlib.h>

int mblen(size_t n;
          const char s[n], size_t n);

bestie. i need you to look at that signature. i'm not fixing it. that's literally what it says. 💅

---

🌸 DESCRIPTION 🌸

okay so here's the tea, and it depends on whether s is NULL or not, because it's giving two completely different main character eras. 👑

if s is NOT NULL:

• mblen() peeks at at most n bytes of the multibyte string that starts at s, and it pulls out the next complete multibyte character. no cap.
• it uses a static anonymous shift state that only mblen() itself knows about. it's lowkey mysterious like that. 🙈
• if that multibyte character is not the null wide character, it returns the number of bytes it consumed from s. slay.
• if that multibyte character is the null wide character, it returns 0.

if things go wrong:

• if the n bytes starting at s don't contain a complete multibyte character, mblen() returns -1. 😭 and listen — this can happen even if n is greater than or equal to MB_CUR_MAX, if the multibyte string contains redundant shift sequences. so don't come for it, it's not being dramatic for no reason.
• if the multibyte string starting at s contains an invalid multibyte sequence before the next complete character, mblen() also returns -1. 💀

if s IS NULL:

• mblen() resets that shift state (the one only this function knows about, yes, that one) back to the initial state.
• and then it returns nonzero if the encoding has nontrivial shift state, or zero if the encoding is stateless. it's a vibe check for your encoding, honestly. ✨

---

💅 RETURN VALUE 💅

• number of bytes parsed from the multibyte sequence starting at s, if a non-null wide character was recognized. go off. 🎀
• 0, if a null wide character was recognized.
• -1, if an invalid multibyte sequence was encountered, or if it couldn't parse a complete multibyte character.

fr fr, that -1 is doing a lot of emotional labor. it covers two whole different sad situations. 🫶

---

🔥 ATTRIBUTES 🔥

for the explanation of the terms used in this section, mosey on over to attributes(7). here's the chart, but make it cute:

• Interface: mblen()
  • Attribute: Thread safety
  • Value: MT-Unsafe race

not to be that girl but MT-Unsafe race?? yeah. be careful out here bestie. 🌈

---

🌟 VERSIONS 🌟

the function mbrlen(3) provides a better interface to the same functionality. so like, mbrlen(3) is the glow-up version. periodt. 💜

---

⭐ STANDARDS ⭐

C11, POSIX.1-2008. certified. iconic. no notes. 👑

---

🌸 HISTORY 🌸

POSIX.1-2001, C99. it's been around, it's seen things. 🧚

---

🦋 NOTES 🦋

the behavior of mblen() depends on the LC_CTYPE category of the current locale. so if it's acting weird, check your locale first, okay?? don't fight the function. 😭

---

🌈 SEE ALSO 🌈

• mbrlen(3) — go say hi to the better interface

---

and that's the whole page!! 💖 this absolutely gorgeous piece of documentation came from Linux man-pages 6.20, dated 2026-02-08, and yes she ate, she left no crumbs. 🎀✨💅