curs_inch(3X)

💖 curs_inch — get a curses character from a window 💖

okay bestie, welcome to the curs_inch(3X) page, which lives in the Library calls section of the manual and is literally all about pulling one single character (plus its whole little vibe bundle of attributes) out of a window. no cap, it's a tiny family of four functions and they're all iconic. let's go 🫶

---

✨ NAME ✨

inch, winch, mvinch, mvwinch — get a curses character from a window 👑

---

🌸 SYNOPSIS 🌸

#include <curses.h>

chtype inch(void);
chtype winch(WINDOW * win);
chtype mvinch(int y, int x);
chtype mvwinch(WINDOW * win, int y, int x);

---

💅 DESCRIPTION 💅

so winch returns the curses character — and when I say character I mean the whole package: its attributes and its color pair identifier too — sitting at the cursor position in the window win. it's giving "full character reveal". ✨

need to know how to actually dig those data out of a chtype? the subsection "Video Attributes" of attron(3X) has you covered, fr fr. and if you wanna know about all the variants of this function, ncurses(3X) is the one to read. 📖

---

🔥 RETURN VALUE 🔥

• OK when it slays (success) ✅
• ERR when it does not (failure) 💀

in ncurses, they return ERR if win is NULL. like, no window, no character, sorry babe. 😭

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

---

📝 NOTES 📝

• inch, mvinch, and mvwinch may be implemented as macros. sneaky but valid. 🙈
• these functions do not fail if the window contains cells of curses complex characters — meaning characters with codes wider than eight bits (or greater than 255 as an unsigned decimal integer). instead they just extract only the low-order eight bits of the character code from the cell. so yeah, the extra bits are just… not invited to the party. 💀

---

🌈 PORTABILITY 🌈

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. that's it, that's the whole section. short and mysterious, main character energy. 👑

---

🦋 HISTORY 🦋

okay storytime, this one's a journey:

• the original curses in 4BSD (1980) defined winch as a macro accessing the WINDOW structure member representing character cell data. at that time it was a char, holding only a 7-bit ASCII character code plus a "standout" attribute bit — the only one the library supported. humble beginnings bestie. 🎀
• SVr2 curses (1984) extended this approach: character code got widened to eight bits, and several attributes could now be combined with it by storing them all together in a chtype, which was an alias of unsigned short. because a macro was used, its value was not type-checked the way a function return value could have been. no vibe check on the type. 😭
• Goodheart documented SVr3 (1987) winch as returning an int.
• SVr3.1's (1987) chtype became an alias of unsigned long, using 16 bits for the character code and widening the type in practical terms to 32 bits — because 64-bit Unix systems were not yet in wide use, and fixed-width integral types would not be standard until ISO C99.
• SVr3.2 (1988) added a 6-bit color pair identifier alongside the attributes. and that's how we got the full glow-up. ✨

---

👀 SEE ALSO 👀

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

---

ncurses 6.6 🌸 2025-02-15

and that's the whole page babes, mwah 💋 this was ncurses 6.6 from 2025-02-15, stay hydrated, read your man pages, and go get that character out of your window 🫶✨💖