define_key(3NCURSES)

💖 define_key — bestie edition 💖

okay so this is from the ncurses library calls manual, and honestly? she's a little icon. let's get into it 🫶

---

✨ NAME ✨

define_key — define a curses function key code 🌸

---

🎀 SYNOPSIS 🎀

#include <curses.h>

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

like. look at her. so simple. so powerful. 💅

---

🦋 DESCRIPTION 🦋

okay so first things first: define_key is an ncurses extension, not like a standard-library-core thing, so keep that in mind bestie. ✨

What she does is let a curses app bind a string definition to a function key — specifically to the key-code that comes back from wgetch(3NCURSES). and if you're on the wide-character API? that's wget_wch(3NCURSES) for you, mwah. 💜

BUT. and this is the important part, no cap — this only kicks in when keypad(3NCURSES) is enabled in a window and somebody actually presses a function key. both. not one or the other. both. 😌

and here's the cute part: ncurses treats your binding exactly the way it treats the bindings in the terminfo database entry for the terminal type. like, same energy. same treatment. iconic behaviour fr fr. 👑

---

💀 the removal lore (do not skip this)

• if definition is NULL, that removes any existing binding from key-code. gone. deleted. not me doing cleanup 💅
• similarly, a non-positive key-code removes an existing binding for definition, if there is one. bye bestie 🫶

---

⭐ RETURN VALUE ⭐

define_key returns ERR if:

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

Otherwise? define_key returns OK. slay. ✨

---

🌈 EXTENSIONS 🌈

define_key is an ncurses extension. that's the whole section. periodt. 💅

---

🌸 PORTABILITY 🌸

okay so if your app is out here using ncurses extensions, the move is to condition their use on the visibility of the NCURSES_VERSION preprocessor macro. like, check before you commit. vibe check your preprocessor. 😌

also, for the record: NetBSD curses since 2.0 (2004) supports define_key. so she's not only an ncurses girlie. we love range. 👑

---

🧚 AUTHORS 🧚

Thomas Dickey 💖

---

🔥 SEE ALSO 🔥

• ncurses(3NCURSES)
• keybound(3NCURSES)
• keyok(3NCURSES)
• key_defined(3NCURSES)
• terminfo(5)

go read them. iykyk. 🦋

---

and that's the whole page bestie!! this was ncurses 6.6, dated 2024-12-28, and it's the define_key(3NCURSES) manual page. mwah. go bind some keys. 💅✨🎀