define_key(3X)

💖 define_key — the "make your own function key" era 💖

okay bestie, so we're in define_key(3X), part of the Library calls section of the ncurses manual, and this one is genuinely so fun. it's the little extension that lets you bind your own string to a function key code. like, you're the main character and you get to decide what that key means. periodt. 🎀

---

✨ NAME ✨

define_key — define a curses function key code

---

🦋 SYNOPSIS 🦋

#include <curses.h>

int define_key(const char * definition, int key-code);

---

💅 DESCRIPTION 💅

so define_key is an ncurses extension (iykyk, it's not in every curses out there) and what it does is it lets a curses application bind a string definition to the function key key-code. that key-code is the thing that wgetch(3X) hands back to you — and if you're one of the wide-character API girlies, that's wget_wch(3X) — but only when keypad(3X) is enabled in a window and a function key actually gets pressed. 🌸

and here's the cute part: ncurses treats that binding exactly the same way it treats the bindings in the terminfo database entry for the terminal type. no special-casing, no weird second-class treatment. it just slots right in. obsessed. 💖

now, the removal tricks, because yes, this function also un-binds things:

• if definition is NULL, it removes any existing binding from key-code. bye bye binding. 💀
• and similarly, if key-code is non-positive, it removes an existing binding for definition, if there even is one.

---

🔥 RETURN VALUE 🔥

define_key returns ERR when:

• definition is NULL and key-code is nonpositive, or
• there's not enough memory available to bind definition to key-code.

and otherwise? define_key returns OK. slay. ✨

---

🌈 EXTENSIONS 🌈

define_key is an ncurses extension. it's giving exclusive, bestie. 👑

---

🧚 PORTABILITY 🧚

if you're using ncurses extensions in your app, you should condition their use on the visibility of the NCURSES_VERSION preprocessor macro. like, don't just rawdog it and assume everyone has it, okay?

also, good news for the BSD girlies: NetBSD curses since 2.0 (2004) supports define_key. we love a crossover moment. 🫶

---

👑 AUTHORS 👑

Thomas Dickey

---

💜 SEE ALSO 💜

• curses(3X)
• keybound(3X)
• keyok(3X)
• key_defined(3X)
• terminfo(5)

---

and that's the whole vibe check, bestie. this page came from ncurses 6.6, dated 2024-12-28 — go forth and bind some keys, you absolute icon. 💅💖✨