btowc(3)

💖 btowc — bestie's guide to turning ONE lil byte into a wide character 💖

okay so first things first, this page is btowc(3) — it lives in the Library Functions Manual section, section 3, we love her 💅

✨ NAME ✨

btowc — convert single byte to wide character 🦋 (yes literally just one byte, she's not greedy)

📚 LIBRARY 📚

Standard C library (libc, -lc) — so like, it's already there for you, just link -lc, periodt ✨

🌸 SYNOPSIS 🌸

#include <wchar.h>

wint_t btowc(int c);

👑 DESCRIPTION 👑

so the btowc() function takes c, reads it as a multibyte sequence of length 1, starting out in the initial shift state, converts it to a wide character, and hands it right back to you 🫶 adorable, right?

but bestie, listen — if c is EOF, or if it's not a valid multibyte sequence of length 1, btowc() hits you with WEOF. that's the sad path 😭 no wide char for you.

🔥 RETURN VALUE 🔥

• you get the wide character that got converted from the single byte c 🎀
• if c is EOF or not a valid multibyte sequence of length 1 → you get WEOF 💀

⭐ ATTRIBUTES ⭐

for the whole explanation of what these terms even mean, go peek at attributes(7) 👀

• Interface: btowc()
• Attribute: Thread safety
• Value: MT-Safe ✅

so yes she's MT-Safe, the girlies can call her from multiple threads, no drama 💅

🌈 STANDARDS 🌈

C11, POSIX.1-2008 — certified iconic, no cap.

🎀 HISTORY 🎀

C99, POSIX.1-2001 — she's been around, an OG fr fr.

💜 NOTES 💜

• the behavior of btowc() depends on the LC_CTYPE category of the current locale 🌍 so like, what it does literally changes based on your locale, iykyk.
• This function should never be used. 😭 not me being dramatic — that's the actual docs. She does NOT work for encodings which have state, and she unnecessarily treats single bytes differently from multibyte sequences. it's giving chaotic.
• use either mbtowc(3) or the thread-safe mbrtowc(3) instead 🙈 please, for me, do that.

lowkey a warning: skip btowc(), go straight to mbtowc(3) or mbrtowc(3). this is not a drill 🔥

🦋 SEE ALSO 🦋

• mbrtowc(3)
• mbtowc(3)
• wctob(3)

---

and that's the whole vibe check bestie 💖 this page came from Linux man-pages 6.20, dated 2026-02-08, and honestly? slay. go forth and use mbrtowc(3) instead, ok love u, bye 👑🌸✨