curs_inwstr(3X)

💖 curs_inwstr — Library calls 💖

okay bestie, so this is the curs_inwstr(3X) page from the ncurses library, and it's literally all about getting a wide-character string out of a curses window. yes, we're pulling whole wide strings out of a window, cursor-first, no cap. let's get into it 🫶

---

✨ NAME ✨

inwstr, winwstr, mvinwstr, mvwinwstr, innwstr, winnwstr, mvinnwstr, mvwinnwstr — grab 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 is the main character here: it extracts a wide-character string from a curses window — that's win — and it starts right at the cursor and keeps going until it hits the end of the line. then it drops all that into wstr, and it terminates it with a wide null character. and here's the tea: it omits any attributes and color pair identifier that curses has associated with each character. so you get the text, not the whole glow-up. ✨

winnwstr does the exact same thing, but it copies at most n wide characters from win. and okay, a negative n implies no limit — so winnwstr just acts like winwstr at that point. iconic.

ncurses(3X) describes the variants of these functions, iykyk.

---

🔥 RETURN VALUE 🔥

when it works, these functions return the count of wide characters copied from win to wstr — and no, that count does not include the wide null terminator. if something goes wrong? you get ERR. periodt.

innwstr, winnwstr, mvinnwstr, and mvwinnwstr return ERR if n is insufficiently large to store a complete wide character string. (and like, remember — a curses complex character can hold multiple wide characters, and some of them may be non-spacing. so it's giving more than you think.)

in ncurses, these functions return ERR if:

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

and the functions prefixed with “mv”? they do the cursor movement first, and they fail if the position (y, x) is outside the window boundaries.

---

🎀 NOTES 🎀

all of these functions except winnwstr may be implemented as macros. so don't be out here doing macro shenanigans and acting surprised.

also, huge heads up bestie: reading a line that overflows the array pointed to by wstr and its variants causes undefined results. 💀 instead, use the n-infixed functions with a positive n that's no larger than the size of the buffer backing wstr. protect your buffer, protect your peace. 🫶

---

🌈 EXTENSIONS 🌈

innwstr, winnwstr, mvinnwstr, and mvwinnwstr accepting negative n values? yeah that's an ncurses extension. slay, but it's an extension.

---

👑 PORTABILITY 👑

if you're using ncurses extensions, you should condition your use on the visibility of the NCURSES_VERSION preprocessor macro. that's the vibe check you have to pass first.

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

notwithstanding the foregoing, 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”

and strictly interpreted? that 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 reports any truncation with ERR, for the record.

also X/Open Curses specifies inwstr, winwstr, mvinwstr, and mvwinwstr as returning OK rather than a (wide) character count — unlike their non-wide counterparts instr, winstr, mvinstr, and mvwinstr. ncurses regards this inconsistency as an error in the standard. not me agreeing, but like. yeah.

---

🧚 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). and get this: their synopses described each function as taking an argument of type pointer-to-char instead of pointer-to-wchar_t, even while describing them as “returning the string of wchar_t in str”. presumably that was an error in the System V Interface Definition. 🙈

---

⭐ SEE ALSO ⭐

• curs_instr(3X) — describes comparable functions of the ncurses library in its non-wide-character configuration.
• curses(3X)
• curs_in_wch(3X)
• curs_in_wchstr(3X)

---

okay that's the whole page bestie, you ate it 💅 this was ncurses 6.6, dated 2025-10-20, and the manual page is curs_inwstr(3X). go forth and read your wide strings responsibly 🍓💜