curs_instr(3X)

💖 curs_instr — Library calls 💖

okay bestie, we're diving into curs_instr(3X) from the ncurses fam, and honestly? it's giving "grab text off the screen" energy and i am obsessed. this whole page lives in the ncurses manual (yes, the library calls corner of it), and it's here to teach you how to yoink a string out of a curses window. no cap, it's useful. let's go 🦋

---

✨ NAME ✨

instr, winstr, mvinstr, mvwinstr, innstr, winnstr, mvinnstr, mvwinnstr — get a string from a curses window 🌸

---

✨ SYNOPSIS ✨

#include <curses.h>

int instr(char * str);
int winstr(WINDOW * win, char * str);
int mvinstr(int y, int x, char * str);
int mvwinstr(WINDOW * win, int y, int x, char * str);

int innstr(char * str, int n);
int winnstr(WINDOW * win, char * str, int n);
int mvinnstr(int y, int x, char * str, int n);
int mvwinnstr(WINDOW * win, int y, int x, char * str, int n);

---

✨ DESCRIPTION ✨

so winstr is the main character here 💅 it pulls a string out of a curses window called win, starting right at the cursor and going until it hits the end of the line. then it tucks that string into str, slaps a null character on the end to terminate it, and — super important — it leaves out any attributes and the color pair identifier that curses has attached to each character. clean string, no extra baggage, periodt.

winnstr does the exact same thing, except it copies at most n characters from win. and here's the cute part: a negative n means no limit at all, so winnstr just behaves like winstr. ✨

ncurses(3X) is where you go to read about the variants of these functions, iykyk.

---

✨ RETURN VALUE ✨

these functions hand you back the count of characters copied from win to str — and no, the null terminator does not count, she's not included in the tally 🎀 — or they return ERR if something went wrong. 😭

in ncurses, these functions fail when:

• the curses screen has not been initialized,
• (for the functions that take a WINDOW pointer argument) win is a null pointer, or
• str is a null pointer.

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

---

✨ NOTES ✨

• every single one of these functions except winnstr may be implemented as macros. so like, don't be weird about taking their address, bestie. 💀
• reading a line that overflows the array pointed to by str with and its variants causes undefined results. yes, undefined. the void. we don't go there. 🕳️

instead, use the n-infixed functions with a positive n argument that's no larger than the size of the buffer backing str. that's the move. 🫶

---

✨ EXTENSIONS ✨

innstr, winnstr, mvinnstr, and mvwinnstr's acceptance of negative n values is an ncurses extension. like, that's our thing, ncurses invented it. 🌈

---

✨ PORTABILITY ✨

if your app is out here using ncurses extensions, you should gate that usage on whether the NCURSES_VERSION preprocessor macro is visible. be polite, check first. 💜

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

X/Open Curses Issues 4 and 7 both state that instr, winstr, mvinstr, and mvwinstr return OK rather than a character count. this is likely an erratum. 🚨

• SVr3.1 and SVr4 implemented winstr as a wrapper around winnstr, returning the latter's return value. X/Open Curses's specification thus may have been an editorial solecism copied from System V's documentation (see below) by X/Open, rather than an intentional change. 💀
• ncurses retains compatibility with System V curses behavior. 🤝

SVr4 describes a successful return value only as “an integer value other than ERR”. so, vague. iconic of them.

SVr4 does not document whether n counts the null terminator that these functions write to str. the mystery continues. 🕵️‍♀️

---

✨ HISTORY ✨

SVr3.1 (1987) introduced these functions. a vintage moment. 🎀

---

✨ SEE ALSO ✨

curs_inwstr(3X) describes comparable functions of the ncurses library in its wide-character configuration (ncursesw). 🦋

curses(3X), curs_inch(3X), curs_inchstr(3X)

---

and that's the whole page, bestie!! 🫶 this was brought to you by ncurses 6.6, dated 2025-10-20 — so you know it's fresh, you know it's iconic, and you know your girl read every single line so you didn't have to. go get that string. 💅✨👑