DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

curs_getch(S)


curs_getch: getch, wgetch, mvgetch, mvwgetch, ungetch -- get (or push back) characters from curses terminal keyboard

Syntax

cc ... -lcurses

#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

The routines getch(S), wgetch(S), mvgetch(S), and mvwgetch(S) read a character from the terminal associated with the window.

If no input is waiting, in no-delay mode, 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. The character is also echoed into the specified window unless noecho has been set.

If the window is not a pad, and it has been moved or modified since the last call to wrefresh(S), wrefresh( ) is called before another character is read. (See ``Warning'' section.)

If keypad is TRUE, and a function key is pressed, the routines return the token for that function key instead of the raw characters. Possible function keys are defined in curses.h with integers beginning with 0401, whose names begin with KEY_.

When curses(S) receives a character (such as Escape) that could be the beginning of a function key, it sets a timer. If the remainder of the sequence does not arrive within the specified time, the character is passed through; otherwise, the function key value is returned. For this reason, many terminals experience a delay between the time when a user presses <Escape> and when the Escape code is returned to the program. Since tokens returned by these routines are outside the ASCII range, they are not printable.

The ungetch(S) 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. Not all function keys may be supported on a particular terminal. A key is not supported if it does not send a unique code when pressed or if the key's definition is not in the terminfo database.

Name Key name
KEY_BREAK Break key
KEY_DOWN The four arrow keys ...
KEY_UP  
KEY_LEFT  
KEY_RIGHT  
KEY_HOME Home key (upward+left arrow)
KEY_BACKSPACE Backspace
KEY_F0 Function keys; space for 64 keys is reserved.
KEY_F(n) For 0 LESS THAN OR EQUAL TO n LESS THAN OR EQUAL TO 63
KEY_DL Delete line
KEY_IL Insert line
KEY_DC Delete character
KEY_IC Insert char or enter insert mode
KEY_EIC Exit insert char mode
KEY_CLEAR Clear screen
KEY_EOS Clear to end of screen
KEY_EOL Clear to end of line
KEY_SF Scroll 1 line forward
KEY_SR Scroll 1 line backward (reverse)
KEY_NPAGE Next page
KEY_PPAGE Previous page
KEY_STAB Set tab
KEY_CTAB Clear tab
KEY_CATAB Clear all tabs
KEY_ENTER Enter or send
KEY_SRESET Soft (partial) reset
KEY_RESET Reset or hard reset
KEY_PRINT Print or copy
KEY_LL Home down or bottom (lower left). Keypad is arranged like this:

A1 up A3
left B2 right
C1 down C3

KEY_A1 Upper left of keypad
KEY_A3 Upper right of keypad
KEY_B2 Center of keypad
KEY_C1 Lower left of keypad
KEY_C3 Lower right of keypad
KEY_BTAB Back tab key
KEY_BEG Beg (Beginning) key
KEY_CANCEL Cancel key
KEY_CLOSE Close key
KEY_COMMAND Cmd (Command) key
KEY_COPY Copy key
KEY_CREATE Create key
KEY_END End key
KEY_EXIT Exit key
KEY_FIND Find key
KEY_HELP Help key
KEY_MARK Mark key
KEY_MESSAGE Message key
KEY_MOVE Move key
KEY_NEXT Next object key
KEY_OPEN Open key
KEY_OPTIONS Options key
KEY_PREVIOUS Previous object key
KEY_REDO Redo key
KEY_REFERENCE Ref (Reference) key
KEY_REFRESH Refresh key
KEY_REPLACE Replace key
KEY_RESTART Restart key
KEY_RESUME Resume key
KEY_SAVE Save key
KEY_SBEG Shifted beginning key
KEY_SCANCEL Shifted cancel key
KEY_SCOMMAND Shifted command key
KEY_SCOPY Shifted copy key
KEY_SCREATE Shifted create key
KEY_SDC Shifted delete char key
KEY_SDL Shifted delete line key
KEY_SELECT Select key
KEY_SEND Shifted end key
KEY_SEOL Shifted clear line key
KEY_SEXIT Shifted exit key
KEY_SFIND Shifted find key
KEY_SHELP Shifted help key
KEY_SHOME Shifted home key
KEY_SIC Shifted input key
KEY_SLEFT Shifted left arrow key
KEY_SMESSAGE Shifted message key
KEY_SMOVE Shifted move key
KEY_SNEXT Shifted next key
KEY_SOPTIONS Shifted options key
KEY_SPREVIOUS Shifted prev key
KEY_SPRINT Shifted print key
KEY_SREDO Shifted redo key
KEY_SREPLACE Shifted replace key
KEY_SRIGHT Shifted right arrow
KEY_SRSUME Shifted resume key
KEY_SSAVE Shifted save key
KEY_SSUSPEND Shifted suspend key
KEY_SUNDO Shifted undo key
KEY_SUSPEND Suspend key
KEY_UNDO Undo key

 Name                  Key name
 KEY_BREAK             Break key
 KEY_DOWN              The four arrow keys ...
 KEY_UP
 KEY_LEFT
 KEY_RIGHT
 KEY_HOME              Home key (upward+left arrow)
 KEY_BACKSPACE         Backspace
 KEY_F0                Function keys; space for 64 keys is reserved.
 KEY_F(n)              For 0  n  63
 KEY_DL                Delete line
 KEY_IL                Insert line
 KEY_DC                Delete character
 KEY_IC                Insert char or enter insert mode
 KEY_EIC               Exit insert char mode
 KEY_CLEAR             Clear screen
 KEY_EOS               Clear to end of screen
 KEY_EOL               Clear to end of line
 KEY_SF                Scroll 1 line forward
 KEY_SR                Scroll 1 line backward (reverse)
 KEY_NPAGE             Next page
 KEY_PPAGE             Previous page
 KEY_STAB              Set tab
 KEY_CTAB              Clear tab
 KEY_CATAB             Clear all tabs
 KEY_ENTER             Enter or send
 KEY_SRESET            Soft (partial) reset
 KEY_RESET             Reset or hard reset
 KEY_PRINT             Print or copy
 KEY_LL                Home down or bottom (lower left).  Keypad is
                       arranged like this:
                          A1   up   A3
                          left B2   right
                          C1   down C3
 KEY_A1                Upper left of keypad
 KEY_A3                Upper right of keypad
 KEY_B2                Center of keypad
 KEY_C1                Lower left of keypad
 KEY_C3                Lower right of keypad
 KEY_BTAB              Back tab key
 KEY_BEG               Beg (Beginning) key
 KEY_CANCEL            Cancel key
 KEY_CLOSE             Close key
 KEY_COMMAND           Cmd (Command) key
 KEY_COPY              Copy key
 KEY_CREATE            Create key
 KEY_END               End key
 KEY_EXIT              Exit key
 KEY_FIND              Find key
 KEY_HELP              Help key
 KEY_MARK              Mark key
 KEY_MESSAGE           Message key
 KEY_MOVE              Move key
 KEY_NEXT              Next object key
 KEY_OPEN              Open key
 KEY_OPTIONS           Options key
 KEY_PREVIOUS          Previous object key
 KEY_REDO              Redo key
 KEY_REFERENCE         Ref (Reference) key
 KEY_REFRESH           Refresh key
 KEY_REPLACE           Replace key
 KEY_RESTART           Restart key
 KEY_RESUME            Resume key
 KEY_SAVE              Save key
 KEY_SBEG              Shifted beginning key
 KEY_SCANCEL           Shifted cancel key
 KEY_SCOMMAND          Shifted command key
 KEY_SCOPY             Shifted copy key
 KEY_SCREATE           Shifted create key
 KEY_SDC               Shifted delete char key
 KEY_SDL               Shifted delete line key
 KEY_SELECT            Select key
 KEY_SEND              Shifted end key
 KEY_SEOL              Shifted clear line key
 KEY_SEXIT             Shifted exit key
 KEY_SFIND             Shifted find key
 KEY_SHELP             Shifted help key
 KEY_SHOME             Shifted home key
 KEY_SIC               Shifted input key
 KEY_SLEFT             Shifted left arrow key
 KEY_SMESSAGE          Shifted message key
 KEY_SMOVE             Shifted move key
 KEY_SNEXT             Shifted next key
 KEY_SOPTIONS          Shifted options key
 KEY_SPREVIOUS         Shifted prev key
 KEY_SPRINT            Shifted print key
 KEY_SREDO             Shifted redo key
 KEY_SREPLACE          Shifted replace key
 KEY_SRIGHT            Shifted right arrow
 KEY_SRSUME            Shifted resume key
 KEY_SSAVE             Shifted save key
 KEY_SSUSPEND          Shifted suspend key
 KEY_SUNDO             Shifted undo key
 KEY_SUSPEND           Suspend key
 KEY_UNDO              Undo key

Return values

All routines return the integer ERR on failure and an integer value other than ERR on successful completion.

Warning

The header file curses.h automatically includes the header files stdio.h and unctrl.h.

Programmers are discouraged from using Escape for a single-character function.

When using getch( ), wgetch( ), mvgetch( ), or mvwgetch( ), do not use nocbreak mode and echo mode at the same time. Depending on the state of the tty driver when each character is typed, the program might produce undesirable results. If wgetch( ) encounters a ^D, it returns it (unlike stdio routines, which returns a null string and has a return code of -1).

The following can be macros: getch( ), mvgetch( ), and mvwgetch( ).

Files


/usr/lib/libcurses.a
the library

See also

curses(S), curs_inopts(S), curs_move(S), curs_refresh(S)

Standards conformance

getch(S), wgetch(S), mvgetch(S), mvwgetch(S), and ungetch(S) are not part of any currently supported standard; they were developed by UNIX System Laboratories, Inc. and are maintained by The SCO Group.
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003