define_key(3X)

📦
version 6.6_p20260516 · 6 versions
, in alpine 3.24, arch rolling, fedora 44

💖 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. 💅💖✨

📦 where this page comes from