mbsrtowcs(3)

💖 mbsrtowcs — bestie edition 💖

okay so this is mbsrtowcs(3), a lil member of the Library Functions Manual family, and it's here to convert a multibyte string into a wide-character string — but make it restartable. yes queen. we love a comeback story. ✨

🌈 LIBRARY

Standard C library, aka libc, link it with -lc. she's built in, no extra shopping required 🛍️

🎀 SYNOPSIS

#include <wchar.h>

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

✨ DESCRIPTION

so here's the tea ☕ — if dest is not NULL, we convert the multibyte string *src into a wide-character string, and it starts landing at dest. at most dsize wide characters get written to dest, no more, that's the cap bestie. and the shift state *ps gets updated along the way.

the conversion is basically done by calling mbrtowc(dest, *src, n, ps) over and over, where n is some positive number, for as long as that call succeeds — then you bump dest up by one and bump *src up by however many bytes got eaten. 🍽️

the conversion can stop for three reasons, and you need to know all three, this is not a drill:

• an invalid multibyte sequence showed up. in that case *src is left pointing right at the invalid sequence, (size_t) -1 is returned, and errno is set to EILSEQ. 💀 not the vibe.
• dsize non-L'\0' wide characters have been stored at dest. in this case *src is left pointing at the next multibyte sequence to be converted, and the number of wide characters written to dest gets returned.
• the multibyte string has been completely converted, including the terminating null wide character ('\0') — which has the side effect of bringing *ps back to the initial state 🧚 (she's healed). in this case *src is set to NULL, and the number of wide characters written to dest gets returned, not counting the terminating null wide character.

if dest is NULL, then dsize is ignored entirely (yes, ignored, she said what she said), and the conversion proceeds just like above — except the converted wide characters don't get written out to memory at all, and there's no length limit. free spirit behavior honestly. 🦋

in both of the cases above, if ps is NULL, then a static anonymous state that only mbsrtowcs() knows about is used instead. secret state. mysterious. iconique. 💅

now listen, to dodge that case 2 situation, the programmer should make sure dsize is greater than or equal to mbsrtowcs(NULL,src,0,ps)+1. simple math bestie, do it.

⚠️ also the programmer must make sure there's room for at least dsize wide characters at dest. no cap. if you don't, that's on you.

and for the lore: this function is a restartable version of mbstowcs(3). glow up achieved. 👑

🔥 RETURN VALUE

it returns the number of wide characters that make up the converted part of the wide-character string — not including the terminating null wide character. and if an invalid multibyte sequence got encountered? (size_t) -1 comes back and errno is set to EILSEQ. periodt.

👑 ATTRIBUTES

for an explanation of the terms used in this section, go see attributes(7). here's the rundown:

• mbsrtowcs() — Thread safety — MT-Unsafe race:mbsrtowcs/!ps

🌸 STANDARDS

C11, POSIX.1-2008.

💜 HISTORY

POSIX.1-2001, C99.

🍓 NOTES

the behavior of mbsrtowcs() depends on the LC_CTYPE category of the current locale. locale girlies know.

💀 passing NULL as ps is not multithread safe. so like… don't. unless you're chill with chaos.

🌈 SEE ALSO

iconv(3), mbrtowc(3), mbsinit(3), mbsnrtowcs(3), mbstowcs(3)

---

okay that's the whole page bestie, you're officially fluent 🫶 this was Linux man-pages 6.20, dated 2026-02-08 — mwah, kiss the manual, go convert some strings responsibly. 💖✨🎀