CURSES_INPUT(3) 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, ungetchcurses 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 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.
 
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 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 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 associations 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 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.
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 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
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.