wcsrtombs(3)

💖 wcsrtombs(3) 💖

okay bestie, welcome to the Library Functions Manual page for wcsrtombs(3). she's a libc girlie and she's here to turn your wide characters into multibyte ones. let's go 🫶

---

✨ NAME ✨

wcsrtombs — convert a wide-character string to a multibyte string

🎀 LIBRARY 🎀

Standard C library (libc, -lc)

🌸 SYNOPSIS 🌸

#include <wchar.h>

size_t wcsrtombs(size_t dsize;
                 char dest[restrict dsize],
                 const wchar_t **restrict src,
                 size_t dsize, mbstate_t *restrict ps);

🦋 DESCRIPTION 🦋

so here's the tea, bestie. if dest is not NULL, wcsrtombs() converts the wide-character string *src into a multibyte string, and it starts writing at dest. ✨

• at most dsize bytes get written to dest
• the shift state *ps gets updated
• the actual conversion is basically just calling wcrtomb(dest, *src, ps) over and over again — as long as that call succeeds — and then bumping dest forward by however many bytes got written, and bumping *src forward by one. periodt.

and the conversion can stop for three reasons:

• a wide character shows up that can NOT be represented as a multibyte sequence (per the current locale) 😭. in that case, *src is left pointing at the invalid wide character, (size_t) -1 gets returned, and errno gets set to EILSEQ.
• the size limit forces it to stop. in that case, *src is left pointing at the next wide character that still needs converting, and the number of bytes written to dest gets returned. no more, no less.
• the wide-character string got completely converted, including the terminating null wide character (L'\0') — which, side note, has the side effect of bringing *ps back to its initial state 🧚. in this case, *src gets set to NULL, and the number of bytes written to dest (not counting the terminating null byte '\0') is returned.

if dest is NULL, then dsize is ignored entirely, and the conversion proceeds just like above — EXCEPT the converted bytes never get written out to memory, and there's no size limit at all. lowkey freeing honestly.

in both of the above cases, if ps is NULL, a static anonymous state that only wcsrtombs() itself knows about gets used instead. iykyk.

⚠️ bestie, listen. the programmer has to make sure there's room for at least dsize bytes at dest. that's on you, not on her. 💅

👑 RETURN VALUE 👑

wcsrtombs() returns the number of bytes that make up the converted part of the multibyte sequence — not including the terminating null byte.

if a wide character showed up that couldn't be converted, (size_t) -1 is returned, and errno is set to EILSEQ. 💀

🔥 ATTRIBUTES 🔥

for an explanation of the terms used in this section, see attributes(7).

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

so yeah, thread safety is giving "it depends". 🌈

⭐ STANDARDS ⭐

C11, POSIX.1-2008. iconic behavior, no cap.

💜 HISTORY 💜

POSIX.1-2001, C99. she's been around, she's a legend.

🌈 NOTES 🌈

• the behavior of wcsrtombs() depends on the LC_CTYPE category of the current locale. so check your locale before you come for her. 🎀
• passing NULL as ps is not multithread safe. not me warning you twice, but like, i am warning you twice. 🙈

🌟 SEE ALSO 🌟

• iconv(3)
• mbsinit(3)
• wcrtomb(3)
• wcsnrtombs(3)
• wcstombs(3)

---

and that's the whole page, bestie 💖 this was Linux man-pages 6.20, dated 2026-02-08 — go forth and convert those wide characters responsibly, mwah 🫶✨