MBTOWC(3POSIX)

💖 MBTOWC(3POSIX) 💖

okay bestie, welcome to the POSIX Programmer's Manual ✨ this is the mbtowc page and we're gonna get you fluent in it, no cap.

---

🌸 PROLOG 🌸

real talk first: this manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ — so if you're on Linux, go check the corresponding Linux manual page for the actual tea. Or, plot twist, the interface might not even be implemented on Linux at all. 💀

---

👑 NAME 👑

mbtowc — convert a character to a wide-character code

---

✨ SYNOPSIS ✨

#include <stdlib.h>

int mbtowc(wchar_t *restrict pwc, const char *restrict s, size_t n);

---

🦋 DESCRIPTION 🦋

so the functionality on this reference page is aligned with the ISO C standard. If anything here conflicts with the ISO C standard, that was not the vibe and it's unintentional — this volume of POSIX.1‐2017 defers to the ISO C standard. periodt.

If s is not a null pointer, mbtowc() shall figure out how many bytes make up the character that s points to. Then it shall determine the wide-character code for the value of type wchar_t that corresponds to that character. (fun fact: the wide-character code that corresponds to the null byte is 0.) If the character is valid and pwc is not a null pointer, mbtowc() shall store the wide-character code in the object that pwc points to. slay.

The behavior of this function is affected by the LC_CTYPE category of the current locale. For a state-dependent encoding, this function gets placed into its initial state by a call where its character pointer argument, s, is a null pointer. After that, calls with s as anything other than a null pointer shall cause the internal state of the function to be altered as necessary. A call with s as a null pointer shall make this function return a non-zero value if encodings have state dependency, and 0 otherwise. If the implementation uses special bytes to change the shift state, those bytes shall not produce separate wide-character codes — they get grouped with an adjacent character instead. Changing the LC_CTYPE category causes the shift state of this function to be unspecified. 👀 And at most n bytes of the array pointed to by s shall be examined.

The implementation shall behave as if no function defined in this volume of POSIX.1‐2017 calls mbtowc().

heads up bestie: the mbtowc() function need not be thread-safe. 💅

---

🔥 RETURN VALUE 🔥

If s is a null pointer, mbtowc() shall return a non-zero or 0 value — depending on whether character encodings do or do not have state-dependent encodings, respectively.

If s is not a null pointer, mbtowc() shall do one of these three:

1. return 0 — if s points to the null byte
2. return the number of bytes that constitute the converted character — if the next n or fewer bytes form a valid character
3. return -1 and set errno to indicate the error — if they do not form a valid character

And in no case shall the value returned be greater than n or the value of the {MB_CUR_MAX} macro. not even once. 🫶

---

💀 ERRORS 💀

The mbtowc() function shall fail if:

• EILSEQ — An invalid character sequence is detected. In the POSIX locale an [EILSEQ] error cannot occur since all byte values are valid characters. iconic honestly.

The following sections are informative.

---

🌈 EXAMPLES 🌈

None.

---

🎀 APPLICATION USAGE 🎀

None.

---

💜 RATIONALE 💜

None.

---

⭐ FUTURE DIRECTIONS ⭐

None.

---

🌸 SEE ALSO 🌸

• mblen()
• mbstowcs()
• wctomb()
• wcstombs()

Also, the Base Definitions volume of POSIX.1‐2017, <stdlib.h>.

---

🧚 COPYRIGHT 🧚

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 .

---

and that's the whole page bestie — brought to you by IEEE/The Open Group, 2017, aka the MBTOWC(3POSIX) footer babes. go forth and convert those characters 💖✨🎀