-.\" $Id: curs_getch.3x,v 1.10 1997/01/05 11:57:54 Jesse.Thilo Exp $
+'\" t
+.\"***************************************************************************
+.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
+.\" *
+.\" Permission is hereby granted, free of charge, to any person obtaining a *
+.\" copy of this software and associated documentation files (the *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" $Id: curs_getch.3x,v 1.61 2021/12/25 21:49:32 tom Exp $
.TH curs_getch 3X ""
+.na
+.hy 0
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
-\fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR,
-\fBmvwgetch\fR, \fBungetch\fR - get (or push back) characters from
-\fBcurses\fR terminal keyboard
+\fBgetch\fP,
+\fBwgetch\fP,
+\fBmvgetch\fP,
+\fBmvwgetch\fP,
+\fBungetch\fP,
+\fBhas_key\fP \- get (or push back) characters from \fBcurses\fP terminal keyboard
+.ad
+.hy
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-
-\fBint getch(void);\fR
+\fB#include <curses.h>\fP
+.PP
+\fBint getch(void);\fP
.br
-\fBint wgetch(WINDOW *win);\fR
-.br
-\fBint mvgetch(int y, int x);\fR
-.br
-\fBint mvwgetch(WINDOW *win, int y, int x);\fR
+\fBint wgetch(WINDOW *\fP\fIwin);\fP
+.sp
+\fBint mvgetch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fP
.br
-\fBint ungetch(int ch);\fR
+\fBint mvwgetch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fP
+.sp
+\fBint ungetch(int \fP\fIch\fP\fB);\fP
+.sp
+/* extension */
.br
-\fBint has_key(int ch);\fR
+\fBint has_key(int \fP\fIch\fP\fB);\fP
.br
.SH DESCRIPTION
-The \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR and \fBmvwgetch\fR, routines read
-a character from the window. In no-delay mode, if no input is waiting, the
-value \fBERR\fR is returned. In delay mode, the program waits until the system
-passes text through to the program. Depending on the setting of \fBcbreak\fR,
-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
+.SS Reading characters
+The \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP and \fBmvwgetch\fP, routines read
+a character from the window.
+In no-delay mode, if no input is waiting, the value \fBERR\fP is returned.
+In delay mode, the program waits until the system
+passes text through to the program.
+Depending on the setting of \fBcbreak\fP,
+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.
-
-If \fBnoecho\fR has been set, then the character will also be echoed into the
+.PP
+If \fBecho\fP 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:
+.bP
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 \fBdelch\fR had been called.
-If the character value is any other \fBKEY_\fR define, the user is alerted
-with a \fBbeep\fR call.
+as if \fBdelch\fP had been called.
+.bP
+If the character value is any other \fBKEY_\fP define, the user is alerted
+with a \fBbeep\fP call.
+.bP
+If the character is a carriage-return,
+and if \fBnl\fP is enabled,
+it is translated to a line-feed after echoing.
+.bP
Otherwise the character is simply output to the screen.
-
+.PP
If the window is not a pad, and it has been moved or modified since the last
-call to \fBwrefresh\fR, \fBwrefresh\fR will be called before another character
+call to \fBwrefresh\fP, \fBwrefresh\fP will be called before another character
is read.
-
-If \fBkeypad\fR is \fBTRUE\fR, 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 \fB<curses.h>\fR as macros with values outside the range
-of 8-bit characters whose names begin with \fBKEY_.\fR Thus, a variable
+.SS Keypad mode
+.PP
+If \fBkeypad\fP is \fBTRUE\fP, and a function key is pressed, the token for
+that function key is returned instead of the raw characters:
+.bP
+The predefined function
+keys are listed in \fB<curses.h>\fP as macros with values outside the range
+of 8-bit characters.
+Their names begin with \fBKEY_\fP.
+.bP
+Other (user-defined) function keys which may be defined
+using \fBdefine_key\fP(3X)
+have no names, but also are expected to have values outside the range of
+8-bit characters.
+.PP
+Thus, a variable
intended to hold the return value of a function key must be of short size or
larger.
-
+.PP
When a character that could be the beginning of a function key is received
-(which, on modern terminals, means an escape character), \fBcurses\fR 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
+(which, on modern terminals, means an escape character),
+\fBcurses\fP 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.
-
-The \fBungetch\fR routine places \fIch\fR back onto the input queue to be
-returned by the next call to \fBwgetch\fR. Note that there is, in effect,
-just one input queue for all windows.
-
-.SS Function Keys
-The following function keys, defined in \fB<curses.h>\fR, might be returned by
-\fBgetch\fR if \fBkeypad\fR has been enabled. Note that not all of these are
-necessarily supported on any particular terminal.
-.sp
+.PP
+In \fBncurses\fP, the timer normally expires after
+the value in \fBESCDELAY\fP (see \fBcurs_variables\fP(3X)).
+If \fBnotimeout\fP is \fBTRUE\fP, 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 notimeout mode after pressing the escape key
+until another key is pressed.
+.SS Ungetting characters
+.PP
+The \fBungetch\fP routine places \fIch\fP back onto the input queue to be
+returned by the next call to \fBwgetch\fP.
+There is just one input queue for all windows.
+.PP
+.SS Predefined key-codes
+The following special keys are defined in \fB<curses.h>\fP.
+.bP
+Except for the special case \fBKEY_RESIZE\fP,
+it is necessary to enable \fBkeypad\fP for \fBgetch\fP to return these codes.
+.bP
+Not all of these are necessarily supported on any particular terminal.
+.bP
+The naming convention may seem obscure, with some apparent
+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.
+.PP
.TS
center tab(/) ;
-l l
l l .
-\fIName\fR/\fIKey\fR \fIname\fR
-
+\fBName\fP/\fBKey\fP \fBname\fP
+_
KEY_BREAK/Break key
KEY_DOWN/The four arrow keys ...
KEY_UP
KEY_F0/T{
Function keys; space for 64 keys is reserved.
T}
-KEY_F(\fIn\fR)/T{
-For 0 \(<= \fIn\fR \(<= 63
+KEY_F(\fIn\fP)/T{
+For 0 \(<= \fIn\fP \(<= 63
T}
KEY_DL/Delete line
KEY_IL/Insert line
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_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_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_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_SUSPEND/Suspend key
KEY_UNDO/Undo key
.TE
-
+.PP
Keypad is arranged like this:
-.sp
+.br
.TS
center allbox tab(/) ;
c c c .
-\fBA1\fR/\fBup\fR/\fBA3\fR
-\fBleft\fR/\fBB2\fR/\fBright\fR
-\fBC1\fR/\fBdown\fR/\fBC3\fR
+\fBA1\fP/\fBup\fP/\fBA3\fP
+\fBleft\fP/\fBB2\fP/\fBright\fP
+\fBC1\fP/\fBdown\fP/\fBC3\fP
.TE
.sp
-The \fBhas_key\fR routine takes a key value from the above list, and
-returns TRUE or FALSE according as the current terminal type recognizes
-a key with that value.
-
+A few of these predefined values do \fInot\fP correspond to a real key:
+.bP
+.B KEY_RESIZE
+is returned when the \fBSIGWINCH\fP signal has been detected
+(see \fBinitscr\fP(3X) and \fBresizeterm\fP(3X)).
+This code is returned whether or not \fBkeypad\fP has been enabled.
+.bP
+.B KEY_MOUSE
+is returned for mouse-events (see \fBcurs_mouse\fP(3X)).
+This code relies upon whether or not \fBkeypad\fP(3X) has been enabled,
+because (e.g., with \fBxterm\fP(1) mouse prototocol) ncurses must
+read escape sequences,
+just like a function key.
+.SS Testing key-codes
+.PP
+The \fBhas_key\fP routine takes a key-code value from the above list, and
+returns \fBTRUE\fP or \fBFALSE\fP according to whether
+the current terminal type recognizes a key with that value.
+.PP
+The library also supports these extensions:
+.RS 3
+.TP 5
+.B define_key
+defines a key-code for a given string (see \fBdefine_key\fP(3X)).
+.TP 5
+.B key_defined
+checks if there is a key-code defined for a given
+string (see \fBkey_defined\fP(3X)).
+.RE
+.PP
.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure and an integer value
-other than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successful
+All routines return the integer \fBERR\fP upon failure and an integer value
+other than \fBERR\fP (\fBOK\fP in the case of \fBungetch\fP) upon successful
completion.
+.RS 3
+.TP 5
+\fBungetch\fP
+returns \fBERR\fP
+if there is no more room in the FIFO.
+.TP
+\fBwgetch\fP
+returns \fBERR\fP
+if the window pointer is null, or
+if its timeout expires without having any data, or
+if the execution was interrupted by a signal (\fBerrno\fP will be set to
+\fBEINTR\fP).
+.RE
+.PP
+Functions with a \*(``mv\*('' prefix first perform a cursor movement using
+\fBwmove\fP, and return an error if the position is outside the window,
+or if the window pointer is null.
.SH NOTES
Use of the escape key by a programmer for a single character function is
discouraged, as it will cause a delay of up to one second while the
keypad code looks for a following function-key sequence.
-
-When using \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, or
-\fBmvwgetch\fR, nocbreak mode (\fBnocbreak\fR) and echo mode
-(\fBecho\fR) should not be used at the same time. Depending on the
+.PP
+Some keys may be the same as commonly used control
+keys, e.g.,
+\fBKEY_ENTER\fP versus control/M,
+\fBKEY_BACKSPACE\fP versus control/H.
+Some curses implementations may differ according to whether they
+treat these control keys specially (and ignore the terminfo), or
+use the terminfo definitions.
+\fBNcurses\fP uses the terminfo definition.
+If it says that \fBKEY_ENTER\fP is control/M,
+\fBgetch\fP will return \fBKEY_ENTER\fP
+when you press control/M.
+.PP
+Generally, \fBKEY_ENTER\fP denotes the character(s) sent by the \fIEnter\fP
+key on the numeric keypad:
+.bP
+the terminal description lists the most useful keys,
+.bP
+the \fIEnter\fP key on the regular keyboard is already handled by
+the standard ASCII characters for carriage-return and line-feed,
+.bP
+depending on whether \fBnl\fP or \fBnonl\fP was called,
+pressing \*(``Enter\*('' on the regular keyboard
+may return either a carriage-return or line-feed, and finally
+.bP
+\*(``Enter or send\*('' is the standard description for this key.
+.PP
+When using \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP, or
+\fBmvwgetch\fP, nocbreak mode (\fBnocbreak\fP) and echo mode
+(\fBecho\fP) 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 \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR may be macros.
-
+.PP
+Note that \fBgetch\fP, \fBmvgetch\fP, and \fBmvwgetch\fP may be macros.
+.PP
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 \fBKEY_UP\fR, \fBKEY_DOWN\fR,
-\fBKEY_LEFT\fR, \fBKEY_RIGHT\fR, \fBKEY_HOME\fR, \fBKEY_END\fR,
-\fBKEY_NPAGE\fR, \fBKEY_PPAGE\fR, and function keys 1 through 12. The Ins key
-is usually mapped to \fBKEY_IC\fR.
+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 \fBKEY_UP\fP, \fBKEY_DOWN\fP,
+\fBKEY_LEFT\fP, \fBKEY_RIGHT\fP, \fBKEY_HOME\fP, \fBKEY_END\fP,
+\fBKEY_NPAGE\fP, \fBKEY_PPAGE\fP, and function keys 1 through 12.
+The Ins key
+is usually mapped to \fBKEY_IC\fP.
.SH PORTABILITY
-The *get* functions are described in the XSI Curses standard, Issue 4. They
-read single-byte characters only. The standard specifies that they return
-\fBERR\fR on failure, but specifies no error conditions.
-
-The echo behavior of these functions on input of \fBKEY_\fR or backspace
-characters was not specified in the SVr4 documentation. This description is
+The *get* functions are described in the XSI Curses standard, Issue 4.
+They
+read single-byte characters only.
+The standard specifies that they return
+\fBERR\fP on failure, but specifies no error conditions.
+.PP
+The echo behavior of these functions on input of \fBKEY_\fP or backspace
+characters was not specified in the SVr4 documentation.
+This description is
adopted from the XSI Curses standard.
-
-The behavior of \fBgetch\fR and friends in the presence of handled signals is
-unspecified in the SVr4 and XSI Curses documentation. Under historical curses
+.PP
+The behavior of \fBgetch\fP and friends in the presence of handled signals is
+unspecified in the SVr4 and XSI Curses documentation.
+Under historical curses
implementations, it varied depending on whether the operating system's
-implementation of handled signal receipt interrupts a \fBread\fR(2) call in
+implementation of handled signal receipt interrupts a \fBread\fP(2) call in
progress or not, and also (in some implementations) depending on whether an
-input timeout or non-blocking mode hsd been set.
-
+input timeout or non-blocking mode has been set.
+.PP
+\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related
+terminfo capabilities, but no higher-level functions use the feature.
+The implementation in ncurses is an extension.
+.PP
+\fBKEY_RESIZE\fP is an extension first implemented for ncurses.
+NetBSD curses later added this extension.
+.PP
Programmers concerned about portability should be prepared for either of two
-cases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receipt
-interrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to
-\fBEINTR\fR. Under the \fBncurses\fR implementation, handled signals never
-interrupt \fBgetch\fR.
-
-The \fBhas_key\fR function is unique to \fBncurses\fR. We recommend that
-any code using it be conditionalized on the NCURSES feature macro.
+cases: (a) signal receipt does not interrupt \fBgetch\fP; (b) signal receipt
+interrupts \fBgetch\fP and causes it to return \fBERR\fP with \fBerrno\fP set to
+\fBEINTR\fP.
+.PP
+The \fBhas_key\fP function is unique to \fBncurses\fP.
+We recommend that
+any code using it be conditionalized on the \fBNCURSES_VERSION\fP feature macro.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_inopts\fR(3X), \fBcurs_move\fR(3X),
-\fBcurs_refresh\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fBcurses\fP(3X),
+\fBcurs_inopts\fP(3X),
+\fBcurs_mouse\fP(3X),
+\fBcurs_move\fP(3X),
+\fBcurs_outopts\fP(3X),
+\fBcurs_refresh\fP(3X),
+\fBcurs_variables\fP(3X),
+\fBresizeterm\fP(3X).
+.PP
+Comparable functions in the wide-character (ncursesw) library are
+described in
+\fBcurs_get_wch\fP(3X).
projects / ncurses.git / blobdiff