MULTIBYTE(3)

🌸 multibyte(3) — bestie edition 🌸

okay so bestie, welcome to the multibyte(3) page from the Library Functions Manual — this is the one that explains how the C library handles multibyte and wide character manipulation functions. it's giving "let me explain CJK encodings to you in the group chat" energy and honestly? we love her for it 💅

---

📚 LIBRARY

Standard C Library — link it with -lc. that's it, that's the whole vibe 🫶

---

✨ SYNOPSIS ✨

#include <limits.h>
#include <stdlib.h>
#include <wchar.h>

three headers, no cap. collect them all 💖

---

💖 DESCRIPTION 💖

okay so here's the situation. the basic elements of some written natural languages — think Chinese, for example — literally cannot be represented uniquely with single C chars. like, it's just not happening. so the C standard supports two different ways of dealing with extended natural language encodings:

1. wide characters — an internal representation where each basic element maps to a single object of type wchar_t
2. multibyte characters — used for input and output, where each basic element is coded as a sequence of C chars

and here's the tea: individual basic elements may map into one or more (up to MB_LEN_MAX) bytes in a multibyte character. so like, sometimes one glyph is one byte, sometimes it's several. it depends. main character energy honestly 🎀

The current locale (setlocale(3)) governs the interpretation of wide and multibyte characters. The locale category LC_CTYPE specifically controls this interpretation. The wchar_t type is wide enough to hold the largest value in the wide character representations for all locales. iconic of it ✨

Multibyte strings may contain ‘shift’ indicators to switch to and from particular modes within the given representation. If explicit bytes are used to signal shifting, these are not recognized as separate characters but are lumped with a neighboring character. There is always a distinguished ‘initial’ shift state. Some functions (e.g., mblen(3), mbtowc(3) and wctomb(3)) maintain static shift state internally, whereas others store it in an mbstate_t object passed by the caller.

⚠️ bestie listen. Shift states are undefined after a call to setlocale(3) with the LC_CTYPE or LC_ALL categories. like, undefined. do not come for me when it breaks. i warned you 😭

For convenience in processing, the wide character with value 0 (the null wide character) is recognized as the wide character string terminator, and the character with value 0 (the null byte) is recognized as the multibyte character string terminator. And null bytes are not permitted within multibyte characters — that's a hard no 🙈

---

🧚 the function lineup 🧚

The C library provides the following functions for dealing with multibyte characters — presenting the whole cast, no cuts:

• mblen(3) — get number of bytes in a character
• mbrlen(3) — get number of bytes in a character (restartable)
• mbrtowc(3) — convert a character to a wide-character code (restartable)
• mbsrtowcs(3) — convert a character string to a wide-character string (restartable)
• mbstowcs(3) — convert a character string to a wide-character string
• mbtowc(3) — convert a character to a wide-character code
• wcrtomb(3) — convert a wide-character code to a character (restartable)
• wcstombs(3) — convert a wide-character string to a character string
• wcsrtombs(3) — convert a wide-character string to a character string (restartable)
• wctomb(3) — convert a wide-character code to a character

notice how the restartable ones are all labeled? that's the mbstate_t girlies vs the static-state girlies. iykyk 💀

---

👀 SEE ALSO 👀

go read these next, bestie, in this exact order:

localedef(1), setlocale(3), stdio(3), big5(5), euc(5), gb18030(5), gb2312(5), gbk(5), mskanji(5), utf8(5)

that's the whole reading list. yes, all five of the encoding pages. slay 🦋

---

⭐ STANDARDS ⭐

These functions conform to ISO/IEC 9899:1999 (“ISO C99”). certified. periodt 💅

---

and that's the page!! Debian, September 9, 2019 — that's who shipped this and when, mwah, thanks Debian ily 🫶🎀✨