BTOWC(3P)

💫 BTOWC(3P) — the POSIX Programmer's Manual glow-up 💫

okay bestie, so this is btowc, and it's literally living in the POSIX Programmer's Manual (3P, periodt). come sit with me, this one's a lil cutie 🎀

---

🌸 PROLOG 🌸

heads up before we even start, babes: this manual page is part of the POSIX Programmer's Manual. the Linux implementation of this interface may differ (so like, go check the corresponding Linux manual page if you wanna know how Linux actually does it 👀), or honestly the interface may not be implemented on Linux at all. no cap. so don't come for me if your box is built different 💀

---

✨ NAME ✨

btowc — single byte to wide character conversion 🦋

like. it takes a lil one-byte bb and turns it into a wide character. that's the whole vibe. that's the job.

---

🌈 SYNOPSIS 🌈

#include <stdio.h>
#include <wchar.h>

wint_t btowc(int c);

one function, one int, and it hands you back a wint_t. iconic honestly 👑

---

💖 DESCRIPTION 💖

okay so first things first, the functionality described on this reference page is aligned with the ISO C standard. if anything here conflicts with the requirements in the ISO C standard, that conflict is unintentional — no drama intended, fr fr. this volume of POSIX.1‐2017 defers to the ISO C standard. so like, ISO C is the main character here and we're just supporting cast 🫶

now the actual tea: the btowc() function shall determine whether c constitutes a valid (one-byte) character in the initial shift state. that's it. that's the check. is this byte a real one-byte character, or is it giving nothing? 💅

and the behavior of this function shall be affected by the LC_CTYPE category of the current locale. so your locale is lowkey in charge of whether things count as valid. keep that in mind bestie, it matters 😭

---

🎀 RETURN VALUE 🎀

here's the part you actually came for:

• btowc() shall return WEOF if c has the value EOF, or if (unsigned char) c does not constitute a valid (one-byte) character in the initial shift state 😔
• otherwise, it shall return the wide-character representation of that character ✨

and in the POSIX locale specifically? btowc() shall not return WEOF if c has a value in the range 0 to 255 inclusive. so like, every single byte in that range is a valid bb in the POSIX locale. slay 💚

---

💀 ERRORS 💀

No errors are defined.

literally none. not one. it's giving peaceful. 😌

the following sections are informative, bestie — so like, they're here for your reading pleasure, not for the rules 📖

---

🦋 EXAMPLES 🦋

None. 🙈

---

🌸 APPLICATION USAGE 🌸

None. 🎀

---

🧚 RATIONALE 🧚

None. 💜

---

⭐ FUTURE DIRECTIONS ⭐

None. 🌟

---

🔥 SEE ALSO 🔥

• wctob() — the reverse vibe, go check her out 👯

and also: the Base Definitions volume of POSIX.1‐2017, <stdio.h>, <wchar.h> 📚

---

👑 COPYRIGHT 👑

okay legal moment, stay with me, this matters:

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

IEEE/The Open Group dropped this in 2017, and that's the whole BTOWC(3P) moment bestie — go forth and convert those single bytes to wide characters, you absolute icon 💅✨🦋💖 no cap, ily, bye 🫶