wcrtomb(3)

💅 wcrtomb(3) — bestie edition

okay so this is a libc page from the Library Functions Manual, and it's all about wcrtomb — converting a wide character into a multibyte sequence ✨

---

🌸 NAME 🌸

wcrtomb — the girl who converts a wide character to a multibyte sequence 🦋

---

📚 LIBRARY 📚

Standard C library — link it with -lc 💖

---

✨ SYNOPSIS ✨

#include <wchar.h>

size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict ps);

---

🫶 DESCRIPTION 🫶

okay so there are like, three whole situations here and we're gonna go through them one by one, no skipping, that's the rule 💅

Case one, the main character case: s is not NULL and wc is not a null wide character (L'\0'). in this case, wcrtomb() takes the wide character wc, converts it to its multibyte representation, and stores it right at the beginning of the character array pointed to by s. it updates the shift state *ps, and returns the length of that multibyte representation — which is literally just the number of bytes written at s. slay. 🔥

Case two, the plot twist: s is not NULL, but wc is a null wide character (L'\0'). here, wcrtomb() stores at the character array pointed to by s the shift sequence needed to bring *ps back to the initial state, followed by a '\0' byte. it updates the shift state *ps (aka brings it into the initial state, we love a reset arc 🧚), and returns the length of the shift sequence plus one — that is, the number of bytes written at s.

Case three, the chaotic one: s is NULL. in this case wc is just... ignored 🙈, and the function effectively returns

wcrtomb(buf, L'\0', ps)

where buf is an internal anonymous buffer. it's giving mysterious, it's giving private, we don't get to see it. periodt. 💀

and in all of the above cases — every single one bestie — if ps is NULL, then a static anonymous state known only to the wcrtomb() function is used instead. iconic behaviour honestly 👑

⚠️ at most MB_CUR_MAX bytes will be written at s. so you, the programmer, must make sure there's enough room to store that multibyte sequence at s. no cap, do not skip this, she will not warn you twice. 😭

---

🌈 RETURN VALUE 🌈

wcrtomb() returns the number of bytes that have been — or would have been — written to the byte array at s. 🍓

but if wc cannot be represented as a multibyte sequence (as per the current locale), then (size_t) -1 gets returned, and errno is set to EILSEQ. rough, but that's the vibe check failing. 💀

---

👑 ATTRIBUTES 👑

for an explanation of the terms used in this section, go look at attributes(7) — she's the reference for all this, iykyk 📖

• Interface: wcrtomb()
• Attribute: Thread safety
• Value: MT-Unsafe race:wcrtomb/!ps

so basically: thread-safe? not entirely, bestie. the /!ps is doing a lot of heavy lifting there. 🙈

---

⭐ STANDARDS ⭐

C11, POSIX.1-2008. ✨ certified, standardised, official.

---

🎀 HISTORY 🎀

POSIX.1-2001, C99. she's been around a minute, and she ate. 💅

---

💜 NOTES 💜

• the behavior of wcrtomb() depends on the LC_CTYPE category of the current locale. so like... your locale is the moment, and the moment matters. 🌸
• passing NULL as ps is not multithread safe. big deal, say it louder for the people in the back. 📢

---

🦋 SEE ALSO 🦋

• mbsinit(3)
• wcsrtombs(3)

---

okay that's the whole page bestie, you're so welcome, go convert some wide characters responsibly 💖

this was Linux man-pages 6.20, dated 2026-02-08, and yes wcrtomb(3) said what she said. bye bestie, drink water, use MB_CUR_MAX, don't overflow your buffer 🫶✨🌈