CURSES_INPUT(3)

CURSES_INPUT(3) | Library Functions Manual | CURSES_INPUT(3)

# NAME

`curses_input`, `getch`, `wgetch`, `mvgetch`, `mvwgetch`, `define_key`, `keyok`, `has_key`, `getnstr`, `wgetnstr`, `mvgetnstr`, `mvwgetnstr`, `getstr`, `wgetstr`, `mvgetstr`, `mvwgetstr`, `keypad`, `is_keypad`, `notimeout`, `timeout`, `wtimeout`, `nodelay`, `ungetch`, `set_escdelay` — curses input stream routines

# LIBRARY

Curses Library (libcurses, -lcurses)

# SYNOPSIS

`#include <curses.h>`

int
`getch`(void);

int
`wgetch`(WINDOW *win);

int
`mvgetch`(int y, int x);

int
`mvwgetch`(WINDOW *win, int y, int x);

int
`keyok`(int key_symbol, bool flag);

int
`has_key`(int key_symbol);

int
`define_key`(const char *sequence, int key_symbol);

int
`getnstr`(char *str, int limit);

int
`wgetnstr`(WINDOW *win, char *str, int limit);

int
`mvgetnstr`(int y, int x, char *str, int limit);

int
`mvwgetnstr`(WINDOW *win, int y, int x, char *str, int limit);

int
`getstr`(char *str);

int
`wgetstr`(WINDOW *win, char *str);

int
`mvgetstr`(int y, int x, char *str);

int
`mvwgetstr`(WINDOW *win, int y, int x, char *str);

int
`keypad`(WINDOW *win, bool flag);

bool
`is_keypad`(const WINDOW *win);

int
`notimeout`(WINDOW *win, bool flag);

void
`timeout`(int delay);

void
`wtimeout`(WINDOW *win, int delay);

int
`nodelay`(WINDOW *win, bool flag);

int
`ungetch`(int c);

int
`set_escdelay`(int escdelay);

extern int ESCDELAY;

# DESCRIPTION

These functions read characters and strings from the window input file descriptor.

The `getch`() function reads a character from the stdscr input file descriptor and returns it. If the `keypad`() flag has been set to `TRUE`, then `getch`() will assemble multi-character key sequences into key symbols, If the terminal is resized, `getch`() will return `KEY_RESIZE`, regardless of the setting of `keypad`(). Calling `getch`() will cause an implicit `refresh`() on stdscr.

The `wgetch`() function is the same as the `getch`() function, excepting that it reads from the input file descriptor associated with the window specified by win.

If the `keypad`() flag is `TRUE` then the assembly of specific key symbols can be disabled by using the `keyok`() function. If the flag is set to `FALSE` on a key symbol then `getch`() will behave as if the character sequence associated with that key symbol was not recognised and will return the component characters one at a time to the caller. The `is_keypad`() function returns `TRUE` if the keypad flag is set for the window specified by win.

The `has_key`() function takes a key value and returns `TRUE` if the current terminal recognises a key with that value, otherwise `FALSE`.

Custom associations between sequences of characters and a key symbol can be made by using the `define_key`() function. Normally, these associations are made by the information in the terminfo(5) database but the `define_key`() function gives the capability to remove or add more associations. If `define_key`() is passed a non-NULL string in sequence it will associate that sequence with the key symbol passed in key_symbol. The key symbol may be one of the ones listed below or a custom value that is application defined. It is valid to have multiple character sequences map to the same key symbol and there are no constraints on the length of the sequence allowed. The assembly of custom sequences follow the same rules for inter-character timing and so forth as the terminfo(5) derived ones. If `define_key`() is passed a NULL in sequence then all associations for the key symbol in key_symbol will be deleted, this includes any associations that were derived from terminfo(5).

The `mvgetch`() and `mvwgetch`() functions are the same as the `getch`() and `wgetch`() functions, respectively, excepting that `wmove`() is called to move the cursor to the position specified by y, x before the character is read.

Calling `getnstr`(), `wgetnstr`(), `mvgetnstr`() or `mvwgetnstr`() is effectively the same as calling `getch`() repeatedly until a newline is received or the character limit limit is reached. Once this happens the string is `NULL` terminated and returned in str. During input, the normal curses input key processing is performed and affects the input buffer. The `mvgetnstr`() function calls `wmove`() to move the cursor to the position given by y, x before getting the string, `wgetnstr`() reads the input from the designated window, `mvwgetnstr`() moves the cursor to the position given by y, x before getting the input from the designated window.

The functions `getstr`(), `wgetstr`(), `mvgetstr`(), and `mvwgetstr`() are similar to `getnstr`(), `wgetnstr`(), `mvgetnstr`(), and `mvwgetnstr`(), respectively, excepting that there is no limit on the number of characters that may be inserted into str. This may cause the buffer to be overflowed, so their use is not recommended.

The `keypad`() function is used to affect how `getch`() processes input characters. If flag is set to `TRUE`, then `getch`() will scan the input stream looking for multi-character key sequences that are emitted by some terminal function keys. If a recognised sequence of characters is found, then `getch`() will collapse that sequence into an integer key symbol, as shown below. The default setting for the flag is `FALSE`.

The `notimeout`() function controls whether or not `getch`() will wait indefinitely between characters in a multi-character key sequence or not. If flag is `TRUE`, then there is no timeout applied between characters comprising a multi-character key sequence. If flag is `FALSE`, then the component characters of a multi-character sequence must not have an inter-character gap of more than ESCDELAY. If this timing is exceeded, then the multi-character key assembly is deemed to have failed and the characters read thus far are returned one at a time when `getch`() is called. The default setting for the flag is `FALSE`. The default value of ESCDELAY is 300ms. If ESCDELAY is negative, no timeout is applied between characters comprising a multi-character key sequence.

The `timeout`() function affects the behaviour of `getch`() when reading a character from stdscr. If delay is negative, then `getch`() will block indefinitely on a read. If delay is 0, then `getch`() will return immediately with `ERR` if there are no characters immediately available. If delay is a positive number, then `getch`() will wait for that many milliseconds before returning and, if no character was available, then `ERR` will be returned. Note that for a positive number, the timeout is only accurate to the nearest tenth of a second. Also, the maximum value of delay is 25500 milliseconds. The `wtimeout`() function does the same as `timeout`() but applies to the specified window win.

The `nodelay`() function turns on and off blocking reads for `getch`(). If flag is `TRUE`, then `getch`() will not block on reads, if flag is `FALSE`, then reads will block. The default setting for the flag is `FALSE`. `nodelay`(win, TRUE) is equivalent to `wtimeout`(win, 0) and `nodelay`(win, FALSE) is equivalent to `wtimeout`(win, -1).

`ungetch`() will convert c into an unsigned char and push that character back onto the input stream. Only one character of push-back is guaranteed to work, more may be possible depending on system resources.

The `set_escdelay`() function sets the ESCDELAY value of the current screen to escdelay.

# RETURN VALUES

The functions `getch`(), `wgetch`(), `mvgetch`(), and `mvwgetch`() will return the value of the key pressed or `ERR` in the case of an error or a timeout. Additionally, if `keypad`(TRUE) has been called on a window, then it may return one of the following values:

Termcap entry | getch Return Value | Key Function
!1 | KEY_SSAVE | Shift Save
!2 | KEY_SSUSPEND | Shift Suspend
!3 | KEY_SUNDO | Shift Undo
#1 | KEY_SHELP | Shift Help
#2 | KEY_SHOME | Shift Home
#3 | KEY_SIC | Shift Insert Character
#4 | KEY_SLEFT | Shift Left Arrow
%0 | KEY_REDO | Redo
%1 | KEY_HELP | Help
%2 | KEY_MARK | Mark
%3 | KEY_MESSAGE | Message
%4 | KEY_MOVE | Move
%5 | KEY_NEXT | Next Object
%6 | KEY_OPEN | Open
%7 | KEY_OPTIONS | Options
%8 | KEY_PREVIOUS | Previous Object
%9 | KEY_PRINT | Print
%a | KEY_SMESSAGE | Shift Message
%b | KEY_SMOVE | Shift Move
%c | KEY_SNEXT | Shift Next Object
%d | KEY_SOPTIONS | Shift Options
%e | KEY_SPREVIOUS | Shift Previous Object
%f | KEY_SPRINT | Shift Print
%g | KEY_SREDO | Shift Redo
%h | KEY_SREPLACE | Shift Replace
%i | KEY_SRIGHT | Shift Right Arrow
%j | KEY_SRSUME | Shift Resume
&0 | KEY_SCANCEL | Shift Cancel
&1 | KEY_REFERENCE | Reference
&2 | KEY_REFRESH | Refresh
&3 | KEY_REPLACE | Replace
&4 | KEY_RESTART | Restart
&5 | KEY_RESUME | Resume
&6 | KEY_SAVE | Save
&7 | KEY_SUSPEND | Suspend
&8 | KEY_UNDO | Undo
&9 | KEY_SBEG | Shift Begin
*0 | KEY_SFIND | Shift Find
*1 | KEY_SCOMMAND | Shift Command
*2 | KEY_SCOPY | Shift Copy
*3 | KEY_SCREATE | Shift Create
*4 | KEY_SDC | Shift Delete Character
*5 | KEY_SDL | Shift Delete Line
*6 | KEY_SELECT | Select
*7 | KEY_SEND | Shift End
*8 | KEY_SEOL | Shift Clear to EOL
*9 | KEY_SEXIT | Shift Exit
@0 | KEY_FIND | Find
@1 | KEY_BEG | Begin
@2 | KEY_CANCEL | Cancel
@3 | KEY_CLOSE | Close
@4 | KEY_COMMAND | Command
@5 | KEY_COPY | Copy
@6 | KEY_CREATE | Create
@7 | KEY_END | End
@8 | KEY_ENTER | Enter
@9 | KEY_EXIT | Exit
F1 | KEY_F(11) | Function Key 11
F2 | KEY_F(12) | Function Key 12
F3 | KEY_F(13) | Function Key 13
F4 | KEY_F(14) | Function Key 14
F5 | KEY_F(15) | Function Key 15
F6 | KEY_F(16) | Function Key 16
F7 | KEY_F(17) | Function Key 17
F8 | KEY_F(18) | Function Key 18
F9 | KEY_F(19) | Function Key 19
FA | KEY_F(20) | Function Key 20
FB | KEY_F(21) | Function Key 21
FC | KEY_F(22) | Function Key 22
FD | KEY_F(23) | Function Key 23
FE | KEY_F(24) | Function Key 24
FF | KEY_F(25) | Function Key 25
FG | KEY_F(26) | Function Key 26
FH | KEY_F(27) | Function Key 27
FI | KEY_F(28) | Function Key 28
FJ | KEY_F(29) | Function Key 29
FK | KEY_F(30) | Function Key 30
FL | KEY_F(31) | Function Key 31
FM | KEY_F(32) | Function Key 32
FN | KEY_F(33) | Function Key 33
FO | KEY_F(34) | Function Key 34
FP | KEY_F(35) | Function Key 35
FQ | KEY_F(36) | Function Key 36
FR | KEY_F(37) | Function Key 37
FS | KEY_F(38) | Function Key 38
FT | KEY_F(39) | Function Key 39
FU | KEY_F(40) | Function Key 40
FV | KEY_F(41) | Function Key 41
FW | KEY_F(42) | Function Key 42
FX | KEY_F(43) | Function Key 43
FY | KEY_F(44) | Function Key 44
FZ | KEY_F(45) | Function Key 45
Fa | KEY_F(46) | Function Key 46
Fb | KEY_F(47) | Function Key 47
Fc | KEY_F(48) | Function Key 48
Fd | KEY_F(49) | Function Key 49
Fe | KEY_F(50) | Function Key 50
Ff | KEY_F(51) | Function Key 51
Fg | KEY_F(52) | Function Key 52
Fh | KEY_F(53) | Function Key 53
Fi | KEY_F(54) | Function Key 54
Fj | KEY_F(55) | Function Key 55
Fk | KEY_F(56) | Function Key 56
Fl | KEY_F(57) | Function Key 57
Fm | KEY_F(58) | Function Key 58
Fn | KEY_F(59) | Function Key 59
Fo | KEY_F(60) | Function Key 60
Fp | KEY_F(61) | Function Key 61
Fq | KEY_F(62) | Function Key 62
Fr | KEY_F(63) | Function Key 63
K1 | KEY_A1 | Upper left key in keypad
K2 | KEY_B2 | Centre key in keypad
K3 | KEY_A3 | Upper right key in keypad
K4 | KEY_C1 | Lower left key in keypad
K5 | KEY_C3 | Lower right key in keypad
Km | KEY_MOUSE | Mouse Event
k0 | KEY_F0 | Function Key 0
k1 | KEY_F(1) | Function Key 1
k2 | KEY_F(2) | Function Key 2
k3 | KEY_F(3) | Function Key 3
k4 | KEY_F(4) | Function Key 4
k5 | KEY_F(5) | Function Key 5
k6 | KEY_F(6) | Function Key 6
k7 | KEY_F(7) | Function Key 7
k8 | KEY_F(8) | Function Key 8
k9 | KEY_F(9) | Function Key 9
k; | KEY_F(10) | Function Key 10
kA | KEY_IL | Insert Line
ka | KEY_CATAB | Clear All Tabs
kB | KEY_BTAB | Back Tab
kb | KEY_BACKSPACE | Backspace
kC | KEY_CLEAR | Clear
kD | KEY_DC | Delete Character
kd | KEY_DOWN | Down Arrow
kE | KEY_EOL | Clear to End Of Line
kF | KEY_SF | Scroll Forward one line
kH | KEY_LL | Home Down
kh | KEY_HOME | Home
kI | KEY_IC | Insert Character
kL | KEY_DL | Delete Line
kl | KEY_LEFT | Left Arrow
kM | KEY_EIC | Exit Insert Character Mode
kN | KEY_NPAGE | Next Page
kP | KEY_PPAGE | Previous Page
kR | KEY_SR | Scroll One Line Back
kr | KEY_RIGHT | Right Arrow
kS | KEY_EOS | Clear to End Of Screen
kT | KEY_STAB | Set Tab
kt | KEY_CTAB | Clear Tab
ku | KEY_UP | Up Arrow

Note that not all terminals are capable of generating all the keycodes listed above nor are terminfo entries normally configured with all the above capabilities defined.

Other functions that return an int will return one of the following values:

`OK`
  The function completed successfully.
`ERR`
  An error occurred in the function.

Functions returning pointers will return `NULL` if an error is detected.

# SEE ALSO

curses_cursor(3), curses_keyname(3), curses_refresh(3), curses_tty(3), terminfo(5)

# STANDARDS

The NetBSD Curses library complies with the X/Open Curses specification, part of the Single Unix Specification.

# NOTES

The `keyok`() and `define_key`() functions are implementations of extensions made by the NCurses library to the Curses standard. Portable implementations should avoid the use of these functions.

# HISTORY

The Curses package appeared in 4.0BSD. The `is_keypad`() and `set_tabsize`() functions are ncurses extension to the Curses library and was added in NetBSD 8.0.

May 14, 2024 | NetBSD 11.0