instr(3NCURSES)

💖 instr — the manual page, but make it cute 💖

okay bestie, so this is a page from the ncurses manual (that's the Library calls section, iykyk) and it's literally all about grabbing a string out of a curses window. very demure, very mindful, very "get the text out of the box". 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 ✨

okay so winstr snatches a string out of a curses window called win. it starts right at the cursor 👀 and keeps going until the end of the line, then it stashes the whole thing in str. and bestie, it terminates it with a null character — yes we love a clean ending — and it omits any attributes and the color pair identifier that curses associates with each character. so it's just the raw text, no glow-up attached 💖

winnstr does the exact same thing, but it copies at most n characters from win. and here's the tea: a negative n implies no limit — winnstr just chills and works like winstr in that case 🦋

and ncurses(3NCURSES) describes the variants of these functions, if you want the full lore ✨

---

✨ RETURN VALUE ✨

these functions hand you back the count of characters copied from win to str (and no, that count does not include the null terminator, she's not invited) — or ERR upon failure 😭

in ncurses, these functions fail if:

• 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 functions prefixed with mv first perform cursor movement, and they fail if the position (y, x) is outside the window boundaries. so like, know your bounds bestie 🫶

---

✨ NOTES ✨

all of these functions except winnstr may be implemented as macros. sneaky little things 💀

⚠️ reading a line that overflows the array pointed to by str with instr and its variants causes undefined results. this is not the vibe. instead, use the n-infixed functions with a positive n argument no larger than the size of the buffer backing str. protect your buffers, protect your peace 🧚

---

✨ EXTENSIONS ✨

innstr, winnstr, mvinnstr, and mvwinnstr's acceptance of negative n values is an ncurses extension 👑 (not standard, just iconic)

---

✨ PORTABILITY ✨

if your app is using ncurses extensions, bestie, you should condition their use on the visibility of the NCURSES_VERSION preprocessor macro. fr fr 🌈

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

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. 😭 the drama of it all
• ncurses retains compatibility with System V curses behavior. loyal to a fault 💜

SVr4 describes a successful return value only as "an integer value other than ERR". vague. mysterious. lowkey unhelpful ✨

and SVr4 does not document whether n counts the null terminator that these functions write to str. we simply do not know. the mystery remains 💀

---

✨ HISTORY ✨

SVr3.1 (1987) introduced these functions. an oldie but a goodie 🎀

---

✨ SEE ALSO ✨

inwstr(3NCURSES) describes comparable functions of the ncurses library in its wide-character configuration (ncursesw). ✨

ncurses(3NCURSES), inch(3NCURSES), inchstr(3NCURSES) 💖

---

and that's the whole page bestie!! this lil' cutie came from ncurses 6.6, dated 2025-10-20, and the manual page itself goes by instr(3NCURSES) 🦋 go forth and read your windows, but mind your buffer sizes okay?? mwah 💅👑🌸