curs_getch(3X) curs_getch(3X)
NAME
cursgetch: getch, wgetch, mvgetch, mvwgetch, ungetch - get (or push
back) characters from curses terminal keyboard
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 ungetch(int ch);
DESCRIPTION
With the getch, wgetch, mvgetch and mvwgetch, routines a character is
read from the terminal associated with the window. In no-delay mode,
if no input is waiting, the value ERR is returned. In delay mode,
the program waits until the system passes text through to the
program. Depending on the setting of cbreak, this is after one
character (cbreak mode), or after the first newline (nocbreak mode).
In half-delay mode, the program waits until a character is typed or
the specified timeout has been reached. Unless noecho has been set,
the character will also be echoed into the designated window.
If the window is not a pad, and it has been moved or modified since
the last call to wrefresh, wrefresh will be called before another
character is read.
If keypad is TRUE, and a function key is pressed, the token for that
function key is returned instead of the raw characters. Possible
function keys are defined in <curses.h> with integers beginning with
0401, whose names begin with KEY. If a character that could be the
beginning of a function key (such as escape) is received, curses sets
a timer. If the remainder of the sequence does not come in within
the designated time, the character is passed through; otherwise, the
function key value is returned. For this reason, many terminals
experience a delay between the time a user presses the escape key and
the escape is returned to the program. Since tokens returned by
these routines are outside the ASCII range, they are not printable.
The ungetch routine places ch back onto the input queue to be
returned by the next call to wgetch.
Function Keys
The following function keys, defined in <curses.h>, might be returned
by getch if keypad has been enabled. Note that not all of these may
be supported on a particular terminal if the terminal does not
transmit a unique code when the key is pressed or if the definition
for the key is not present in the terminfo database.
8/91 Page 1
curs_getch(3X) curs_getch(3X)
__________________________________________________________________
Name Key name
__________________________________________________________________
KEYBREAK Break key
KEYDOWN The four arrow keys ...
KEYUP
KEYLEFT
KEYRIGHT
KEYHOME Home key (upward+left arrow)
KEYBACKSPACE Backspace
KEYF0 Function keys; space for 64 keys is reserved.
KEYF(n) For 0 < n < 63
KEYDL Delete line
KEYIL Insert line
KEYDC Delete character
KEYIC Insert char or enter insert mode
KEYEIC Exit insert char mode
KEYCLEAR Clear screen
KEYEOS Clear to end of screen
KEYEOL Clear to end of line
KEYSF Scroll 1 line forward
KEYSR Scroll 1 line backward (reverse)
KEYNPAGE Next page
KEYPPAGE Previous page
KEYSTAB Set tab
KEYCTAB Clear tab
KEYCATAB Clear all tabs
KEYENTER Enter or send
KEYSRESET Soft (partial) reset
KEYRESET Reset or hard reset
KEYPRINT Print or copy
KEYLL Home down or bottom (lower left). Keypad is
arranged like this:
A1 up A3
left B2 right
C1 down C3
KEYA1 Upper left of keypad
KEYA3 Upper right of keypad
KEYB2 Center of keypad
KEYC1 Lower left of keypad
KEYC3 Lower right of keypad
KEYBTAB Back tab key
KEYBEG Beg(inning) key
KEYCANCEL Cancel key
KEYCLOSE Close key
KEYCOMMAND Cmd (command) key
KEYCOPY Copy key
KEYCREATE Create key
KEYEND End key
KEYEXIT Exit key
KEYFIND Find key
Page 2 8/91
curs_getch(3X) curs_getch(3X)
__________________________________________________________________
Name Key name
__________________________________________________________________
KEYHELP Help key
KEYMARK Mark key
KEYMESSAGE Message key
KEYMOVE Move key
KEYNEXT Next object key
KEYOPEN Open key
KEYOPTIONS Options key
KEYPREVIOUS Previous object key
KEYREDO Redo key
KEYREFERENCE Ref(erence) key
KEYREFRESH Refresh key
KEYREPLACE Replace key
KEYRESTART Restart key
KEYRESUME Resume key
KEYSAVE Save key
KEYSBEG Shifted beginning key
KEYSCANCEL Shifted cancel key
KEYSCOMMAND Shifted command key
KEYSCOPY Shifted copy key
KEYSCREATE Shifted create key
KEYSDC Shifted delete char key
KEYSDL Shifted delete line key
KEYSELECT Select key
KEYSEND Shifted end key
KEYSEOL Shifted clear line key
KEYSEXIT Shifted exit key
KEYSFIND Shifted find key
KEYSHELP Shifted help key
KEYSHOME Shifted home key
KEYSIC Shifted input key
KEYSLEFT Shifted left arrow key
KEYSMESSAGE Shifted message key
KEYSMOVE Shifted move key
KEYSNEXT Shifted next key
KEYSOPTIONS Shifted options key
KEYSPREVIOUS Shifted prev key
KEYSPRINT Shifted print key
KEYSREDO Shifted redo key
KEYSREPLACE Shifted replace key
KEYSRIGHT Shifted right arrow
KEYSRSUME Shifted resume key
KEYSSAVE Shifted save key
KEYSSUSPEND Shifted suspend key
KEYSUNDO Shifted undo key
KEYSUSPEND Suspend key
KEYUNDO Undo key
8/91 Page 3
curs_getch(3X) curs_getch(3X)
RETURN VALUE
All routines return the integer ERR upon failure and an integer value
other than ERR upon successful completion.
NOTES
The header file <curses.h> automatically includes the header files
<stdio.h> and <unctrl.h>.
Use of the escape key by a programmer for a single character function
is discouraged.
When using getch, wgetch, mvgetch, or mvwgetch, nocbreak mode
(nocbreak) and echo mode (echo) should not be used at the same time.
Depending on the state of the tty driver when each character is
typed, the program may produce undesirable results.
Note that getch, mvgetch, and mvwgetch may be macros.
SEE ALSO
curses(3X), cursinopts(3X), cursmove(3X), cursrefresh(3X).
Page 4 8/91