- The getch, wgetch, mvgetch and mvwgetch, routines read a
- character from 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 af-
- ter one character (cbreak mode), or after the first new-
- line (nocbreak mode). In half-delay mode, the program
- waits until a character is typed or the specified timeout
- has been reached.
-
- If echo is enabled, and the window is not a pad, then the
- character will also be echoed into the designated window
- according to the following rules:
-
- o If the character is the current erase character, left
- arrow, or backspace, the cursor is moved one space to
- the left and that screen position is erased as if
- delch had been called.
-
- o If the character value is any other KEY_ define, the
- user is alerted with a beep call.
-
- o If the character is a carriage-return, and if nl is
- enabled, it is translated to a line-feed after echo-
- ing.
-
- o Otherwise the character is simply output to the
- screen.
-
- If the window is not a pad, and it has been moved or modi-
- fied 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 to-
- ken for that function key is returned instead of the raw
- characters:
-
- o The predefined function keys are listed in <curses.h>
- as macros with values outside the range of 8-bit char-
- acters. Their names begin with KEY_.
-
- o Other (user-defined) function keys which may be de-
- fined using define_key(3x) have no names, but also are
- expected to have values outside the range of 8-bit
- characters.
-
- Thus, a variable intended to hold the return value of a
- function key must be of short size or larger.
-
- When a character that could be the beginning of a function
- key is received (which, on modern terminals, means an es-
- cape character), 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 es-
- cape key and the escape is returned to the program.
-
- In ncurses, the timer normally expires after the value in
- ESCDELAY (see curs_variables(3x)). If notimeout is TRUE,
- the timer does not expire; it is an infinite (or very
- large) value. Because function keys usually begin with an
- escape character, the terminal may appear to hang in no-
- timeout mode after pressing the escape key until another
- key is pressed.
-
-
-
- The ungetch routine places ch back onto the input queue to
- be returned by the next call to wgetch. There is just one
- input queue for all windows.
-
-
-
- The following special keys are defined in <curses.h>.
-
- o Except for the special case KEY_RESIZE, it is neces-
- sary to enable keypad for getch to return these codes.
-
- o Not all of these are necessarily supported on any par-
- ticular terminal.
-
- o The naming convention may seem obscure, with some ap-
- parent misspellings (such as "RSUME" for "resume").
- The names correspond to the long terminfo capability
- names for the keys, and were defined long ago, in the
- 1980s.
-
- NameKeyname
- -------------------------------------------------
- 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)
- 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(inning) 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_MOUSE Mouse event read
- 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(erence) key
- KEY_REFRESH Refresh key
- KEY_REPLACE Replace key
- KEY_RESIZE Screen resized
- 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
-
- Keypad is arranged like this:
-
- +-----+------+-------+
- | A1 | up | A3 |
- +-----+------+-------+
- |left | B2 | right |
- +-----+------+-------+
- | C1 | down | C3 |
- +-----+------+-------+
- A few of these predefined values do not correspond to a
- real key:
-
- oKEY_RESIZE is returned when the SIGWINCH signal has
- been detected (see initscr(3x) and resizeterm(3x)).
- This code is returned whether or not keypad has been
- enabled.
-
- oKEY_MOUSE is returned for mouse-events (see
- curs_mouse(3x)). This code relies upon whether or not
- keypad(3x) has been enabled, because (e.g., with xterm
- mouse prototocol) ncurses must read escape sequences,
- just like a function key.
-
-
-
- The has_key routine takes a key-code value from the above
- list, and returns TRUE or FALSE according to whether the
- current terminal type recognizes a key with that value.
-
- The library also supports these extensions:
-
- define_key
- defines a key-code for a given string (see de-
- fine_key(3x)).
-
- key_defined
- checks if there is a key-code defined for a given
- string (see key_defined(3x)).
+
+ wgetch gathers a key stroke from the terminal keyboard associated with
+ a curses window win. ncurses(3x) describes the variants of this
+ function.
+
+ When input is pending, wgetch returns an integer identifying the key
+ stroke; for alphanumeric and punctuation keys, this value corresponds
+ to the character encoding used by the terminal. Use of the control key
+ as a modifier often results in a distinct code. The behavior of other
+ keys depends on whether win is in keypad mode; see subsection "Keypad
+ Mode" below.
+
+ If no input is pending, then if the no-delay flag is set in the window
+ (see nodelay(3x)), the function returns ERR; otherwise, curses waits
+ until the terminal has input. If cbreak(3x) has been called, this
+ happens after one character is read. If nocbreak(3x) has been called,
+ it occurs when the next newline is read. If halfdelay(3x) has been
+ called, curses waits until a character is typed or the specified delay
+ elapses.
+
+ If echo(3x) has been called, and the window is not a pad, curses writes
+ the returned character c to the window (at the cursor position) per the
+ following rules.
+
+ o If c matches the terminal's erase character, the cursor moves
+ leftward one position and the new position is erased as if
+ wmove(3x) and then wdelch(3x) were called. When the window's
+ keypad mode is enabled (see below), KEY_LEFT and KEY_BACKSPACE are
+ handled the same way.
+
+ ocurses writes any other c to the window, as with wechochar(3x).
+
+ o If the window has been moved or modified since the last call to
+ wrefresh(3x), curses calls wrefresh.
+
+ If c is a carriage return and nl(3x) has been called, wgetch returns
+ the character code for line feed instead.
+
+
+
+ To curses, key strokes not from the alphabetic section of the keyboard
+ (those corresponding to the ECMA-6 character set--see
+ ascii(7)--optionally modified by either the control or shift keys) are
+ treated as function keys. (In curses, the term "function key" includes
+ but is not limited to keycaps engraved with "F1", "PF1", and so on.)
+ If the window is in keypad mode, these produce a numeric code
+ corresponding to the KEY_ symbols listed in subsection "Predefined Key
+ Codes" below; otherwise, they transmit a sequence of codes typically
+ starting with the escape character, and which must be collected with
+ multiple wgetch calls.
+
+ o The curses.h header file declares many predefinedfunctionkeys
+ whose names begin with KEY_; these object-like macros have values
+ outside the range of eight-bit character codes.
+
+ o In ncurses, user-definedfunctionkeys are configured with
+ define_key(3x); they have no names, but are also expected to have
+ values outside the range of eight-bit codes.
+
+ A variable intended to hold a function key code must thus be of type
+ short or larger.
+
+ Most terminals one encounters follow the ECMA-48 standard insofar as
+ their function keys produce character sequences prefixed with the
+ escape character ESC. This fact implies that curses cannot know
+ whether the terminal has sent an ESC key stroke or the beginning of a
+ function key's character sequence without waiting to see if, and how
+ soon, further input arrives. When curses reads such an ambiguous
+ character, it sets a timer. If the remainder of the sequence does not
+ arrive within the designated time, wgetch returns the prefix character;
+ otherwise, it returns the function key code corresponding to the unique
+ sequence defined by the terminal. Consequently, a user of a curses
+ application may experience a delay after pressing ESC while curses
+ disambiguates the input; see section "EXTENSIONS" below. If the window
+ is in "no time-out" mode, the timer does not expire; it is an infinite
+ (or very large) value. See notimeout(3x). Because function key
+ sequences usually begin with an escape character, the terminal may
+ appear to hang in no time-out mode after the user has pressed ESC.
+ Generally, further typing "awakens" curses.
+
+
+
+ The header file curses.h defines the following function key codes.
+
+ o Except for the special case of KEY_RESIZE, a window's keypad mode
+ must be enabled for wgetch to read these codes from it.
+
+ o Not all of these are necessarily supported on any particular
+ terminal.
+
+ o The naming convention may seem obscure, with some apparent
+ misspellings (such as "RSUME" for "resume"); the names correspond
+ to the terminfo capability names for the keys, and were
+ standardized before the IBM PC/AT keyboard layout achieved a
+ dominant position in industry.
+
+ SymbolKeyname
+ -----------------------------------------------------------------
+ KEY_BREAK Break key
+ KEY_DOWN
+ KEY_UP Arrow keys
+ 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) Function key n where 0 <= n <= 63
+
+ KEY_DL Delete line
+ KEY_IL Insert line
+ KEY_DC Delete character
+ KEY_IC Insert character/Enter insert mode
+ KEY_EIC Exit insert character mode
+ KEY_CLEAR Clear screen
+ KEY_EOS Clear to end of screen
+ KEY_EOL Clear to end of line
+ KEY_SF Scroll one line forward
+ KEY_SR Scroll one line backward (reverse)
+ KEY_NPAGE Next page/Page up
+ KEY_PPAGE Previous page/Page down
+ KEY_STAB Set tab
+ KEY_CTAB Clear tab
+ KEY_CATAB Clear all tabs
+ KEY_ENTER Enter/Send
+ KEY_SRESET Soft (partial) reset
+ KEY_RESET (Hard) reset
+ KEY_PRINT Print/Copy
+ KEY_LL Home down/Bottom (lower left)
+ 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(inning) 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_MOUSE Mouse event occurred
+ 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(erence) key
+ KEY_REFRESH Refresh key
+ KEY_REPLACE Replace key
+ KEY_RESIZE Screen resized
+ KEY_RESTART Restart key
+ KEY_RESUME Resume key
+ KEY_SAVE Save key
+ KEY_SELECT Select key
+ KEY_SUSPEND Suspend key
+ KEY_UNDO Undo 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 character key
+ KEY_SDL Shifted delete line 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 insert key
+ KEY_SLEFT Shifted left arrow key
+ KEY_SMESSAGE Shifted message key
+ KEY_SMOVE Shifted move key
+ KEY_SNEXT Shifted next object key
+ KEY_SOPTIONS Shifted options key
+ KEY_SPREVIOUS Shifted previous object key
+ KEY_SPRINT Shifted print key
+ KEY_SREDO Shifted redo key
+ KEY_SREPLACE Shifted replace key
+ KEY_SRIGHT Shifted right arrow key
+ KEY_SRSUME Shifted resume key
+ KEY_SSAVE Shifted save key
+ KEY_SSUSPEND Shifted suspend key
+ KEY_SUNDO Shifted undo key
+
+ Many keyboards feature a nine-key directional pad.
+
+ +-----+------+-------+
+ | A1 | up | A3 |
+ +-----+------+-------+
+ |left | B2 | right |
+ +-----+------+-------+
+ | C1 | down | C3 |
+ +-----+------+-------+
+ Two of the symbols in the list above do not correspond to a physical
+ key.
+
+ owgetch returns KEY_RESIZE, even if the window's keypad mode is
+ disabled, when ncurses handles a SIGWINCH signal; see initscr(3x)
+ and resizeterm(3x).
+
+ owgetch returns KEY_MOUSE to indicate that a mouse event is pending
+ collection; see curs_mouse(3x). Receipt of this code requires a
+ window's keypad mode to be enabled, because to interpret mouse
+ input (as with with xterm(1)'s mouse prototocol), ncurses must read
+ an escape sequence, as with a function key.
+
+
+
+ In ncurses, has_key returns a Boolean value indicating whether the
+ terminal type recognizes its parameter as a key code value. See also
+ define_key(3x) and key_defined(3x).
- All routines return the integer ERR upon failure and an
- integer value other than ERR (OK in the case of ungetch)
- upon successful completion.
+ Except for has_key, these functions return OK on success and ERR on
+ failure.
+
+ Functions taking a WINDOW pointer argument fail if the pointer is NULL.
+
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (y, x) is outside the window boundaries.
+
+ wgetch also fails if
+
+ o its timeout expires without any data arriving, or
- ungetch
- returns ERR if there is no more room in the FIFO.
+ o execution was interrupted by a signal, in which case errno is set
+ to EINTR.
- wgetch
- returns ERR if the window pointer is null, or if
- its timeout expires without having any data, or if
- the execution was interrupted by a signal (errno
- will be set to EINTR).
+ ungetch fails if there is no more room in the input queue.
- Functions with a "mv" prefix first perform a cursor move-
- ment using wmove, and return an error if the position is
- outside the window, or if the window pointer is null.
+ has_key returns TRUE or FALSE.
- Use of the escape key by a programmer for a single charac-
- ter function is discouraged, as it will cause a delay of
- up to one second while the keypad code looks for a follow-
- ing function-key sequence.
-
- Some keys may be the same as commonly used control keys,
- e.g., KEY_ENTER versus control/M, KEY_BACKSPACE versus
- control/H. Some curses implementations may differ accord-
- ing to whether they treat these control keys specially
- (and ignore the terminfo), or use the terminfo defini-
- tions. Ncurses uses the terminfo definition. If it says
- that KEY_ENTER is control/M, getch will return KEY_ENTER
- when you press control/M.
-
- Generally, KEY_ENTER denotes the character(s) sent by the
- Enter key on the numeric keypad:
-
- o the terminal description lists the most useful keys,
-
- o the Enter key on the regular keyboard is already han-
- dled by the standard ASCII characters for carriage-re-
- turn and line-feed,
-
- o depending on whether nl or nonl was called, pressing
- "Enter" on the regular keyboard may return either a
- carriage-return or line-feed, and finally
-
- o "Enter or send" is the standard description for this
- key.
-
- 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 un-
- desirable results.
-
- Note that getch, mvgetch, and mvwgetch may be macros.
-
- Historically, the set of keypad macros was largely defined
- by the extremely function-key-rich keyboard of the AT&T
- 7300, aka 3B1, aka Safari 4. Modern personal computers
- usually have only a small subset of these. IBM PC-style
- consoles typically support little more than KEY_UP,
- KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END,
- KEY_NPAGE, KEY_PPAGE, and function keys 1 through 12. The
- Ins key is usually mapped to KEY_IC.
+ curses discourages assignment of the ESC key to a discrete function by
+ the programmer because the library requires a delay while it awaits the
+ potential remainder of a terminal escape sequence.
+
+ Some key strokes are indistinguishable from control characters; for
+ example, KEY_ENTER may be the same as ^M, and KEY_BACKSPACE may be the
+ same as ^H or ^?. Consult the terminal's terminfo entry to determine
+ whether this is the case; see infocmp(1). Some curses implementations,
+ including ncurses, honor the terminfo key definitions; others treat
+ such control characters specially.
+
+ curses distinguishes the Enter keys in the alphabetic and numeric
+ keypad sections of a keyboard because (most) terminals do. KEY_ENTER
+ refers to the key on the numeric keypad and, like other function keys,
+ and is reliably recognized only if the window's keypad mode is enabled.
+
+ o The terminfokey_enter (kent) capability describes the character
+ (sequence) sent by the Enter key of a terminal's numeric (or
+ similar) keypad.
+
+ o "Enter or send" is X/Open Curses's description of this key.
+
+ curses treats the Enter or Return key in the alphabetic section of the
+ keyboard differently.
+
+ o It usually produces a control code for carriage return (^M) or line
+ feed (^J).
+
+ o Depending on the terminal mode (raw, cbreak, or "cooked"), and
+ whether nl(3x) or nonl(3x) has been called, wgetch may return
+ either a carriage return or line feed upon an Enter or Return key
+ stroke.
+
+ Use of wgetch with echo(3x) and neither cbreak(3x) nor raw(3x) is not
+ well-defined.
+
+ Historically, the list of key code macros above was influenced by the
+ function-key-rich keyboard of the AT&T 7300 (also known variously as
+ the "3B1", "Safari 4", and "UNIX PC"), a 1985 machine. Today's
+ computer keyboards are based that of the IBM PC/AT and tend to have
+ fewer. A curses application can expect such a keyboard to transmit key
+ codes KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END,
+ KEY_PPAGE (Page Up), KEY_NPAGE (Page Down), KEY_IC (Insert), KEY_DC
+ (Delete), and KEY_F(n) for 1 <= n <= 12.
+
+ getch, mvgetch, and mvwgetch may be implemented as macros.
+
+
+
+ In ncurses, when a window's "no time-out" mode is not set, the ESCDELAY
+ variable configures the duration of the timer used to disambiguate a
+ function key character sequence from a series of key strokes beginning
+ with ESC typed by the user; see curs_variables(3x).
+
+ has_key was designed for ncurses(3x), and is not found in SVr4 curses,
+ 4.4BSD curses, or any other previous curses implementation.
- The *get* functions are described in the XSI Curses stan-
- dard, Issue 4. They read single-byte characters only.
- The standard specifies that they return ERR on failure,
- but specifies no error conditions.
-
- The echo behavior of these functions on input of KEY_ or
- backspace characters was not specified in the SVr4 docu-
- mentation. This description is adopted from the XSI Curs-
- es standard.
-
- The behavior of getch and friends in the presence of han-
- dled signals is unspecified in the SVr4 and XSI Curses
- documentation. Under historical curses implementations,
- it varied depending on whether the operating system's im-
- plementation of handled signal receipt interrupts a
- read(2) call in progress or not, and also (in some imple-
- mentations) depending on whether an input timeout or non-
- blocking mode has been set.
-
- KEY_MOUSE is mentioned in XSI Curses, along with a few re-
- lated terminfo capabilities, but no higher-level functions
- use the feature. The implementation in ncurses is an ex-
- tension.
-
- KEY_RESIZE is an extension first implemented for ncurses.
- NetBSD curses later added this extension.
-
- Programmers concerned about portability should be prepared
- for either of two cases: (a) signal receipt does not in-
- terrupt getch; (b) signal receipt interrupts getch and
- causes it to return ERR with errno set to EINTR.
-
- The has_key function is unique to ncurses. We recommend
- that any code using it be conditionalized on the NCURS-
- ES_VERSION feature macro.
+ Applications employing ncurses extensions should condition their use on
+ the visibility of the NCURSES_VERSION preprocessor macro.
+
+ X/Open Curses, Issue 4 describes getch, wgetch, mvgetch, mvwgetch, and
+ ungetch. It specifies no error conditions for them.
+
+ wgetch reads only single-byte characters.
+
+ The echo behavior of these functions on input of KEY_ or backspace
+ characters was not specified in the SVr4 documentation. This
+ description is adapted from X/Open Curses.
+
+ The behavior of wgetch in the presence of signal handlers is
+ unspecified in the SVr4 documentation and X/Open Curses. In historical
+ curses implementations, it varied depending on whether the operating
+ system's dispatch of a signal to a handler interrupting a read(2) call
+ in progress, and also (in some implementations) whether an input
+ timeout or non-blocking mode has been set. Programmers concerned about
+ portability should be prepared for either of two cases: (a) signal
+ receipt does not interrupt wgetch; or (b) signal receipt interrupts
+ wgetch and causes it to return ERR with errno set to EINTR.
+
+ KEY_MOUSE is mentioned in X/Open Curses, along with a few related term-
+ info capabilities, but no higher-level functions use the feature. The
+ implementation in ncurses is an extension.
+
+ KEY_RESIZE and has_key are extensions first implemented for ncurses.
+ By 2022, PDCurses and NetBSD curses had added them along with
+ KEY_MOUSE.