CURSES_INPUT(3) BSD Library Functions Manual CURSES_INPUT(3)NAME
curses_input, getch, wgetch, mvgetch, mvwgetch, define_key, keyok,
getnstr, wgetnstr, mvgetnstr, mvwgetnstr, getstr, wgetstr, mvgetstr,
mvwgetstr, keypad, notimeout, timeout, wtimeout, nodelay, ungetch —
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
define_key(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, boolf flag);
int
notimeout(WINDOW *win, boolf flag);
int
timeout(int delay);
int
wtimeout(WINDOW *win, int delay);
int
nodelay(WINDOW *win, boolf flag);
int
ungetch(int c);
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 sym‐
bols, If the terminal is resized, getch() will return KEY_RESIZE, regard‐
less 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 speci‐
fied 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.
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 termcap(5) database but the
define_key() function gives the capability to remove or add more associa‐
tions. 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 termcap(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 asso‐
ciations that were derived from termcap(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 simi‐
lar to getnstr(), wgetnstr(), mvgetnstr(), and mvwgetnstr(), respec‐
tively, 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 char‐
acters. If flag is set to TRUE, then getch() will scan the input stream
looking for multi-character key sequences that are emitted by some termi‐
nal 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 indef‐
initely between characters in a multi-character key sequence or not. If
flag is TRUE, then there is no timeout applied between characters com‐
prising a multi-character key sequence. If flag is FALSE, then the com‐
ponent 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 charac‐
ters 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 charac‐
ters 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 immedi‐
ately with ERR if there are no characters immediately available. If
delay is a positive number, then getch() will wait for that many mil‐
liseconds 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 guaran‐
teed to work, more may be possible depending on system resources.
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 termcap entries normally configured with all the
above capabilities defined.
Other functions that return an int will return one of the following val‐
ues:
OK The function completed successfully.
ERR An error occurred in the function.
Functions returning pointers will return NULL if an error is detected.
SEE ALSOcurses_cursor(3), curses_keyname(3), curses_refresh(3), curses_tty(3),
termcap(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 implementa‐
tions should avoid the use of these functions.
HISTORY
The Curses package appeared in 4.0BSD.
BSD July 25, 2006 BSD
