inch(3NCURSES)

inch(3NCURSES) 💖 the "wait what's in this cell bestie" function

okay so like. welcome to the inch(3NCURSES) manual page, a library call situation, and honestly? it's giving "I just want to know what character is sitting there." 🎀

---

✨ 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);

like. four little besties. all here to grab you a chtype. slay. 💅

---

✨ DESCRIPTION ✨

so winch returns the curses character — and when I say character I mean the whole package, bestie: its attributes and its color pair identifier — sitting at the cursor position in the window win. it's not just the letter, it's the letter and its whole vibe. 👑

and if you're like "okay but how do I actually pull those pieces out of a chtype?" — subsection "Video Attributes" of attron(3NCURSES) explains exactly how to extract these data from a chtype. go read it, it's right there. 📖

also ncurses(3NCURSES) describes the variants of this function, so if you're confused about which flavor you're looking at, that's your girl.

---

✨ RETURN VALUE ✨

these functions return OK on success and ERR on failure. simple as that, no cap. ✨

in ncurses specifically, they return ERR if win is NULL. so like. don't do that. 😭

and the ones prefixed with mv — that's mvinch and mvwinch — first perform cursor movement, and they fail if the position (y, x) is outside the window boundaries. so if you're trying to peek at a cell that doesn't exist, that's an ERR, bestie, the math is not mathing. 💀

---

✨ NOTES ✨

heads up: inch, mvinch, and mvwinch may be implemented as macros. yes, macros. we love a little preprocessor moment. 🙈

and here's the big one, so listen up: these functions do not fail if the window contains cells of curses complex characters — that is, if they contain 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 like. no error, no warning, just quietly handing you a truncated little guy. the rest of the bits? gone. not invited. 💀

---

✨ PORTABILITY ✨

X/Open Curses Issue 4 describes these functions. and it specifies no error conditions for them. so like, the spec said "vibes only, no errors defined." 🌈

---

✨ HISTORY ✨

okay this part is genuinely iconic, gather round 🫶

the original curses in 4BSD (1980) defined winch as a macro accessing the WINDOW structure member representing character cell data — and at that time that member was a char, containing only a 7-bit ASCII character code and a "standout" attribute bit, which was the only attribute bit the library supported. one (1) bit of attitude. 🎀

then SVr2 curses (1984) extended this approach, widening the character code to eight bits and permitting several attributes to be combined with it by storing them together in a chtype, an alias of unsigned short. glow-up. ✨

but because a macro was used, its value was not type-checked the way a function return value could have been. rip to type safety, you would've loved it here. 😭

Goodheart documented SVr3 (1987) winch as returning an int. then 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. history lesson AND a glow-up. 👑

and finally, SVr3.2 (1988) added a 6-bit color pair identifier alongside the attributes. color entered the chat and never left. 🌸

---

✨ SEE ALSO ✨

• in_wch(3NCURSES) — describes comparable functions of the ncurses library in its wide-character configuration (ncursesw). if you're on that wide-character grind, this is your bestie. 🦋
• ncurses(3NCURSES)
• instr(3NCURSES)

---

and that's the whole page, bestie!! this was ncurses 6.6, dated 2025-02-15, manual page inch(3NCURSES) — mwah, go read your cells, ily, bye 💖✨🎀