Skip to content

define_key(3x)

define_key - define a curses function key code

#include <curses.h>
int define_key(const char * definition, int key-code);

The define_key ncurses extension permits a curses application to bind a string definition to the function key key-code returned by wgetch(3X) (wide-character API users: wget_wch(3X)) when keypad(3X) is enabled in a window and a function key is pressed. ncurses interprets such a binding as it does those in the terminfo database entry for the terminal type.

If definition is already bound to another key code, define_key moves the binding to key-code.

A definition of NULL removes any existing binding from key-code. Similarly, a non-positive key-code removes an existing binding for definition, if any.

define_key returns ERR if

  • no screen has been initialized,

  • definition is NULL and key-code is nonpositive,

  • definition is NULL and no binding for key-code exists,

  • key-code is nonpositive and no binding for definition exists,

  • definition is an empty string,

  • definition is a prefix of a bound string, or a bound string is a prefix of definition, or

  • insufficient memory is available to bind definition to key-code.

Otherwise, define_key returns OK.

define_key is an ncurses extension.

Applications employing ncurses extensions should condition their use on the visibility of the NCURSES_VERSION preprocessor macro.

NetBSD curses since 2.0 (2004) supports define_key.

Thomas Dickey

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