inwstr(3NCURSES)

💖 inwstr — get a wide-character string from a curses window ✨

okay bestie, so this is inwstr(3NCURSES) from the Library calls section, and it's literally the girlboss way to yoink a whole wide-character string out of a curses window. eight functions, one vibe. let's go 🫶

---

🌸 NAME 🌸

inwstr, winwstr, mvinwstr, mvwinwstr, innwstr, winnwstr, mvinnwstr, mvwinnwstr — get a wide-character string from a curses window 💅

---

✨ SYNOPSIS ✨

#include <curses.h>

int inwstr(wchar_t * wstr);
int winwstr(WINDOW * win, wchar_t * wstr);
int mvinwstr(int y, int x, wchar_t * wstr);
int mvwinwstr(WINDOW * win, int y, int x, wchar_t * wstr);

int innwstr(wchar_t * wstr, int n);
int winnwstr(WINDOW * win, wchar_t * wstr, int n);
int mvinnwstr(int y, int x, wchar_t * wstr, int n);
int mvwinnwstr(WINDOW * win, int y, int x, wchar_t * wstr, int n);

---

🦋 DESCRIPTION 🦋

so winwstr pulls a wide-character string out of a curses window win. it starts at the cursor, keeps going until the end of the line, and drops the whole thing into wstr. then it slaps a wide null character on the end to terminate it, and — listen — it omits any attributes and the color pair identifier that curses has attached to each character. we're just here for the letters, not the ~lewk~ 👑

winnwstr is the same energy, except it copies at most n wide characters out of win. and here's the fun part: a negative n means no limit, so winnwstr just does exactly what winwstr does. iconic behaviour honestly 💅

and if you want the full rundown on all the variants of these functions, that's ncurses(3NCURSES), bestie. it's giving reference material. 📚

---

🔥 RETURN VALUE 🔥

on a successful run, these functions return the count of wide characters copied from win to wstr — and no, that count does not include the wide null terminator, she's not invited to the party. or they return ERR if things go wrong 😭

innwstr, winnwstr, mvinnwstr, and mvwinnwstr return ERR if n is insufficiently large to store a complete wide character string. and remember, babes: a curses complex character can contain multiple wide characters, and some of those may be non-spacing. so like. plan accordingly. 🙈

in ncurses, these functions return ERR if:

• the curses screen has not been initialized 💀
• (for the functions that take a WINDOW pointer argument) win is a null pointer
• wstr is a null pointer

also, the functions prefixed with mv first perform cursor movement, and they fail if the position (y, x) is outside the window boundaries. stay in your lane, coordinate-wise 🎀

---

💜 NOTES 💜

all of these functions except winnwstr may be implemented as macros. surprise! 🎉

reading a line that overflows the array pointed to by wstr and its variants causes undefined results. no cap. instead, use the n-infixed functions with a positive n argument that's no larger than the size of the buffer backing wstr. protect yourself, bestie 🫶

---

🌈 EXTENSIONS 🌈

innwstr, winnwstr, mvinnwstr, and mvwinnwstr's acceptance of negative n values is an ncurses extension. not standard, just ncurses being extra ✨

---

⭐ PORTABILITY ⭐

if your application is out here using ncurses extensions, you should condition their use on the visibility of the NCURSES_VERSION preprocessor macro. gatekeeping your code from the compiler, as you should 💅

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. okay werk.

notwithstanding the foregoing (love that phrase, ate), X/Open Curses Issues 4 and 7 both state that innwstr, winnwstr, mvinnwstr, and mvwinnwstr "fail ... [i]f the array is not large enough to contain any complete characters". strictly interpreted, this means a caller of these functions cannot use their return values to detect truncation of a wide-character string copied from more than one character cell in win. 😬 ncurses, however, reports any truncation with ERR. ncurses said "not on my watch."

X/Open Curses specifies inwstr, winwstr, mvinwstr, and mvwinwstr as returning OK rather than a (wide) character count — which is lowkey wild, because that's unlike their non-wide counterparts instr, winstr, mvinstr, and mvwinstr. ncurses regards this inconsistency as an error in the standard. periodt. 💀

---

🎀 HISTORY 🎀

the System V Interface Definition, Version 4 (1995), specified winwstr and winnwstr (and the usual variants). these were later additions to SVr4.x — they did not appear in the first SVr4 (1989). the glow-up took a minute 💅

and get this: their synopses described each function as taking an argument of type pointer-to-char instead of pointer-to-wchar_t, despite describing them as "returning the string of wchar_t in str". presumably this was an error in the System V Interface Definition. girlie was typing too fast and never proofread. 😭

---

🍓 SEE ALSO 🍓

• instr(3NCURSES) — describes comparable functions of the ncurses library in its non-wide-character configuration. same vibe, smaller letters.
• ncurses(3NCURSES)
• in_wch(3NCURSES)
• in_wchstr(3NCURSES)

---

and that's the whole page, bestie — no skips, no summaries, every flag and caveat present and accounted for 👑

ncurses 6.6 — 2025-10-20 🌸 mwah, stay safe out there and don't overflow your buffers, ily 🫶💖✨