mbtowc(3)

💖 mbtowc(3) — bestie edition 💖

okay so we're doing mbtowc(3) today, from the Library Functions Manual, and honestly? she's a classic. a little old-school, a little haunted, but we love her. she takes a multibyte sequence and turns it into a wide character. no cap.

---

✨ NAME ✨

mbtowc — convert a multibyte sequence to a wide character 🦋

📚 LIBRARY 📚

Standard C library (libc, -lc). yes queen, it's already linked, you're fine.

🌸 SYNOPSIS 🌸

#include <stdlib.h>

int mbtowc(size_t size;
           wchar_t *restrict pwc, const char s[restrict size],
           size_t size);

(no i will not explain that signature. she is what she is. 💅)

👑 DESCRIPTION 👑

okay so there are three whole cases and you literally have to know all three, bestie, so let's go.

Case one: s is not NULL AND pwc is not NULL. This is the main character case, fr fr. mbtowc() peeks at at most size bytes of the multibyte string starting at s, pulls out the next complete multibyte character, converts it to a wide character, and stores it at *pwc. she also updates an internal shift state that only mbtowc() knows about (iykyk). And here's the return rule: if s does not point to a null byte ('\0'), you get back the number of bytes consumed from s — but if it does point to a null byte, you get 0.

Case two: s is not NULL but pwc is NULL. she behaves exactly like above, except she does not actually store the converted wide character in memory. she just... does the vibe check and moves on. 🙈

Case three: s is NULL. now pwc and size get completely ignored. mbtowc() resets the shift state (the one only she knows about) back to the initial state, and returns nonzero if the encoding has nontrivial shift state, or zero if the encoding is stateless.

🚨 and now the part that ruins your day: if the size bytes starting at s don't contain a complete multibyte character, or if they contain an invalid multibyte sequence, mbtowc() returns -1. and get this — this can happen even if size >= MB_CUR_MAX, if the multibyte string contains redundant shift sequences. yes, even when the math says you're fine. 😭

🌈 RETURN VALUE 🌈

• If s is not NULL: you get the number of consumed bytes starting at s, or 0 if s points to a null byte, or -1 upon failure.
• If s is NULL: you get nonzero if the encoding has nontrivial shift state, or zero if the encoding is stateless.

that's it. that's the whole chart. 📊

🎀 ATTRIBUTES 🎀

for an explanation of the terms used in this section, go see attributes(7). (their words not mine, but valid.)

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

she races. she is not the friend you text in a multithreaded emergency. 💀

💜 VERSIONS 💜

this function is not multithread safe. periodt. and if that's a problem for you, mbrtowc(3) provides a better interface to the same functionality — so like, go there, she's evolved.

⭐ STANDARDS ⭐

C11, POSIX.1-2008. certified. 📜

🦋 HISTORY 🦋

POSIX.1-2001, C99. she's been here a minute.

💅 NOTES 💅

the behavior of mbtowc() depends on the LC_CTYPE category of the current locale. change the locale, change the girl. 🌍

🔥 SEE ALSO 🔥

• MB_CUR_MAX(3)
• mblen(3)
• mbrtowc(3)
• mbstowcs(3)
• wcstombs(3)
• wctomb(3)

---

okay that's the whole page, bestie, you ate it, you understood it, iconic behavior. this was Linux man-pages 6.20, dated 2026-02-08, and it's page mbtowc(3). love u, go read the mbrtowc(3) one too, she's the upgrade. 🫶💖✨