'\" t
.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getch.3x,v 1.72 2023/09/16 23:34:43 tom Exp $
-.TH curs_getch 3X 2023-09-16 "ncurses 6.4" "Library calls"
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_getch.3x,v 1.87 2024/04/20 19:18:18 tom Exp $
+.TH curs_getch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds ^ \(ha
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.ds ^ ^
+.\}
+.
+.ie \n(.g .ds : \:
+.el .ds : \" empty
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
\fB\%has_key\fP \-
get (or push back) characters from \fIcurses\fR terminal keyboard
.SH SYNOPSIS
+.nf
.B #include <curses.h>
.PP
.B int getch(void);
-.br
-.B int wgetch(WINDOW *\fIwin\fB);
-.sp
-.B int mvgetch(int \fIy\fB, int \fIx\fB);
-.br
-.B int mvwgetch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);
-.sp
-.B int ungetch(int \fIch\fB);
-.sp
-/* extension */
-.br
-.B int has_key(int \fIch\fB);
-.br
+.B int wgetch(WINDOW *\fIwin\fP);
+.B int mvgetch(int \fIy\fP, int \fIx\fP);
+.B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.PP
+.B int ungetch(int \fIc\fP);
+.PP
+.\" XXX: Move has_key into its own page like define_key and key_defined?
+\fI/* extension */\fP
+.B int has_key(int \fIc\fP);
+.fi
.SH DESCRIPTION
-.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.
-.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\fP had been called.
+.SS "Reading Characters"
+.B \%wgetch
+gathers a key stroke from the terminal keyboard associated with a
+.I curses
+window
+.IR win .
+\fB\%ncurses\fP(3X) describes the variants of this function.
+.PP
+When input is pending,
+.B \%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
+.I win
+is in keypad mode;
+see subsection \*(``Keypad Mode\*('' below.
+.PP
+If no input is pending,
+then if the no-delay flag is set in the window
+(see \fB\%nodelay\fP(3X)),
+the function returns
+.BR ERR ;
+otherwise,
+.I curses
+waits until the terminal has input.
+If \fB\%cbreak\fP(3X)
+has been called,
+this happens after one character is read.
+If \fB\%nocbreak\fP(3X)
+has been called,
+it occurs when the next newline is read.
+If \fB\%halfdelay\fP(3X)
+has been called,
+.I curses
+waits until a character is typed or the specified delay elapses.
+.PP
+If \fB\%echo\fP(3X) has been called,
+and the window is not a pad,
+.I curses
+writes the returned character
+.I c
+to the window
+(at the cursor position)
+per the following rules.
.bP
-If the character value is any other \fBKEY_\fP define, the user is alerted
-with a \fBbeep\fP call.
+If
+.I c
+matches the terminal's erase character,
+the cursor moves leftward one position
+and the new position is erased
+as if \fB\%wmove\fP(3X) and then \fB\%wdelch\fP(3X) were called.
+When the window's keypad mode is enabled
+(see below),
+.B \%KEY_LEFT
+and
+.B \%KEY_BACKSPACE
+are handled the same way.
.bP
-If the character is a carriage-return,
-and if \fBnl\fP is enabled,
-it is translated to a line-feed after echoing.
+.I curses
+writes any other
+.I c
+to the window,
+as with \fB\%wechochar\fP(3X).
.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\fP, \fBwrefresh\fP will be called before another character
-is read.
-.SS Keypad mode
-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:
+If the window has been moved or modified since the last call to
+\fB\%wrefresh\fP(3X),
+.I curses
+calls
+.BR \%wrefresh .
+.PP
+If
+.I c
+is a carriage return and \fBnl\fP(3X) has been called,
+.B \%wgetch
+returns the character code for line feed instead.
+.SS "Keypad Mode"
+To
+.IR curses ,
+key strokes not from the alphabetic section of the keyboard
+(those corresponding to the ECMA-6 character set\(emsee
+\fIascii\fP(7)\(emoptionally modified by either the control or shift
+keys)
+are treated as
+.I function
+keys.
+(In
+.IR 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
+.B 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
+.B \%wgetch
+calls.
.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.
+The
+.I \%curses.h
+header file declares many
+.I "predefined function keys"
+whose names begin with
+.BR KEY_ ;
+these object-like macros have values outside the range of eight-bit
+character codes.
.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\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.
-.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
-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.
-.SS Predefined key-codes
-The following special keys are defined in \fB<curses.h>\fP.
+In
+.IR \%ncurses ,
+.I "user-defined function keys"
+are configured with \fB\%define_key\fP(3X);
+they have no names,
+but are also expected to have values outside the range of eight-bit
+codes.
+.PP
+A variable intended to hold a function key code must thus be of type
+.I short
+or larger.
+.PP
+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
+.I 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
+.I curses
+reads such an ambiguous character,
+it sets a timer.
+If the remainder of the sequence does not arrive within the designated
+time,
+.B \%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
+.I curses
+application may experience a delay after pressing ESC while
+.I 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 \fB\%notimeout\fP(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\*(''
+.IR curses .
+.SS "Ungetting Characters"
+.B \%ungetch
+places
+.I c
+into the input queue to be returned by the next call to
+.BR \%wgetch .
+A single input queue serves all windows.
+.SS "Predefined Key Codes"
+The header file
+.I \%curses.h
+defines the following function key codes.
.bP
-Except for the special case \fBKEY_RESIZE\fP,
-it is necessary to enable \fBkeypad\fP for \fBgetch\fP to return these codes.
+Except for the special case of
+.BR \%KEY_RESIZE ,
+a window's keypad mode must be enabled for
+.B \%wgetch
+to read these codes from it.
.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.
+The naming convention may seem obscure,
+with some apparent misspellings
+(such as \*(``RSUME\*('' for \*(``resume\*('');
+the names correspond to the
+.I \%term\%info
+capability names for the keys,
+and were standardized before the IBM PC/AT keyboard layout achieved a
+dominant position in industry.
.PP
.RS
+.\" XXX: Move this list into ncurses(3X), rather than duplicating it in
+.\" get_wch(3X) or having that page cross reference this one?
.TS
-tab(/) ;
-l l .
-\fBName\fP/\fBKey\fP \fBname\fP
-_
-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/T{
-Function keys; space for 64 keys is reserved.
+Lb Lb
+Lb Lx.
+Symbol Key name
+=
+KEY_BREAK Break key
+KEY_DOWN Arrow keys
+KEY_UP \^
+KEY_LEFT \^
+KEY_RIGHT \^
+KEY_HOME Home key (upward+left arrow)
+KEY_BACKSPACE Backspace
+KEY_F0 T{
+Function keys; space for 64 keys is reserved
T}
-KEY_F(\fIn\fP)/T{
-For 0 \(<= \fIn\fP \(<= 63
+KEY_F(\fIn\fP) T{
+Function key \fIn\fP where 0 \(<= \fIn\fP \(<= 63
T}
-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 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_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 insert 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
-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
+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
.TE
.RE
.PP
-Keypad is arranged like this:
+Many keyboards feature a nine-key directional pad.
.PP
.RS
.TS
-allbox tab(/) ;
-c c c .
-\fBA1\fP/\fBup\fP/\fBA3\fP
-\fBleft\fP/\fBB2\fP/\fBright\fP
-\fBC1\fP/\fBdown\fP/\fBC3\fP
+allbox center;
+C C C.
+A1 up A3
+left B2 right
+C1 down C3
.TE
.RE
.sp
-A few of these predefined values do \fInot\fP correspond to a real key:
+Two of the symbols in the list above do
+.I not
+correspond to a physical 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.
+.B \%wgetch
+returns
+.BR \%KEY_RESIZE ,
+even if the window's keypad mode is disabled,
+when
+.I \%ncurses
+handles a
+.B \%SIGWINCH
+signal;
+see \fB\%initscr\fP(3X) and \fB\%resizeterm\fP(3X).
.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
-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
+.B \%wgetch
+returns
+.B \%KEY_MOUSE
+to indicate that a mouse event is pending collection;
+see \fB\%curs_mouse\fP(3X).
+Receipt of this code requires a window's keypad mode to be enabled,
+because to interpret mouse input
+(as with with \fI\%xterm\fP(1)'s mouse prototocol),
+.I \%ncurses
+must read an escape sequence,
+as with a function key.
+.SS "Testing Key Codes"
+In
+.IR \%ncurses ,
+.B \%has_key
+returns a Boolean value indicating whether the terminal type recognizes
+its parameter as a key code value.
+See also
+\fB\%define_key\fP(3X) and \fB\%key_defined\fP(3X).
.SH RETURN VALUE
-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
+Except for
+.BR \%has_key ,
+these functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+Functions taking a
+.I \%WINDOW
+pointer argument fail if the pointer is
+.BR NULL .
+.PP
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
+.PP
+.B \%wgetch
+also fails if
+.bP
+its timeout expires without any data arriving,
+or
+.bP
+execution was interrupted by a signal,
+in which case
+.B \%errno
+is set to
+.BR \%EINTR .
.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.
+.B \%ungetch
+fails if there is no more room in the input queue.
+.PP
+.B \%has_key
+returns
+.B TRUE
+or
+.BR FALSE .
.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.
-.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:
+.I 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.
+.PP
+Some key strokes are indistinguishable from control characters;
+for example,
+.B \%KEY_ENTER
+may be the same as
+.BR \*^M ,
+.\" as with att630 or pccon+keys
+and
+.B \%KEY_BACKSPACE
+may be the same as
+.B \*^H
+.\" as with att505 or vt52-basic
+or
+.BR \*^? .
+.\" as with pccon+keys or vt320
+Consult the terminal's
+.I \%term\%info
+entry to determine whether this is the case;
+see \fB\%infocmp\fP(1).
+Some
+.I curses
+implementations,
+including
+.IR \%ncurses ,
+honor the
+.I \%term\%info
+key definitions;
+others treat such control characters specially.
+.PP
+.I curses
+distinguishes the Enter keys in the alphabetic and numeric keypad
+sections of a keyboard because (most) terminals do.
+.B \%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.
.bP
-the terminal description lists the most useful keys,
+The
+.I \%term\%info
+.B \%key_enter
+.RB ( kent )
+capability describes the character (sequence) sent by the Enter key of
+a terminal's numeric
+(or similar)
+keypad.
.bP
-the \fIEnter\fP key on the regular keyboard is already handled by
-the standard ASCII characters for carriage-return and line-feed,
+\*(``Enter or send\*('' is X/Open Curses's description of this key.
+.PP
+.I curses
+treats the Enter or Return key in the
+.I alphabetic
+section of the keyboard differently.
.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
+It usually produces a control code for carriage return
+.RB ( \*^M )
+or line feed
+.RB ( \*^J ).
.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.
-.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\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.
+Depending on the terminal mode
+(raw,
+cbreak,
+or
+\*(``cooked\*(''),
+and whether \fB\%nl\fP(3X) or \fB\%nonl\fP(3X) has been called,
+.B \%wgetch
+may return either a carriage return or line feed upon an Enter or Return
+key stroke.
+.PP
+Use of
+.B \%wgetch
+with \fB\%echo\fP(3X) and neither \fB\%cbreak\fP(3X) nor \fB\%raw\fP(3X)
+is not well-defined.
+.PP
+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
+.I curses
+application can expect such a keyboard to transmit key codes
+.BR \%KEY_UP ,
+.BR \%KEY_DOWN ,
+.BR \%KEY_LEFT ,
+.BR \%KEY_RIGHT ,
+.BR \%KEY_HOME ,
+.BR \%KEY_END ,
+.B \%KEY_PPAGE
+(Page Up),
+.B \%KEY_NPAGE
+(Page Down),
+.B \%KEY_IC
+(Insert),
+.B \%KEY_DC
+(Delete),
+and
+.BI \%KEY_F( n )
+for 1 \(<=
+.I n
+\(<= 12.
+.PP
+.BR \%getch ,
+.BR \%mvgetch ,
+and
+.B \%mvwgetch
+may be implemented as macros.
+.SH EXTENSIONS
+In
+.IR \%ncurses ,
+when a window's \*(``no time-out\*('' mode is
+.I not
+set,
+the
+.B \%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
+\fB\%curs_variables\fP(3X).
+.PP
+\fB\%has_key\fP was designed for \fB\%ncurses\fP(3X),
+and is not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous curses implementation.
.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\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.
-.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\fP(2) call in
-progress or not, and also (in some implementations) depending on whether an
-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\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.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
+.PP
+X/Open Curses,
+Issue 4 describes
+\fB\%getch\fP,
+\fB\%wgetch\fP,
+\fB\%mvgetch\fP,
+\fB\%mvwgetch\fP,
+and
+\fB\%ungetch\fP.
+It specifies no error conditions for them.
+.PP
+.B \%wgetch
+reads only single-byte characters.
+.PP
+The echo behavior of these functions on input of
+.B KEY_
+or backspace characters was not specified in the SVr4 documentation.
+This description is adapted from X/Open Curses.
+.PP
+The behavior of
+.B \%wgetch
+in the presence of signal handlers is unspecified in the SVr4
+documentation and X/Open Curses.
+In historical
+.I curses
+implementations,
+it varied depending on whether the operating system's dispatch of a
+signal to a handler interrupting a \fIread\fP(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
+.BR \%wgetch ;
+or
+(b) signal receipt interrupts
+.B \%wgetch
+and causes it to return
+.B ERR
+with
+.B \%errno
+set to
+.BR \%EINTR .
+.PP
+.B \%KEY_MOUSE
+is mentioned in X/Open Curses,
+along with a few related
+.I \%term\%info
+capabilities,
+but no higher-level functions use the feature.
+The implementation in
+.I \%ncurses
+is an extension.
+.PP
+.B \%KEY_RESIZE
+and
+.B \%has_key
+are extensions first implemented for
+.IR \%ncurses .
+By 2022,
+.I \%PDCurses
+.\" https://web.archive.org/web/20220117232009/https://pdcurses.org/docs/MANUAL.html
+and
+NetBSD
+.I curses
+.\" https://web.archive.org/web/20200923185647/https://man.netbsd.org/curses_input.3
+had added them along with
+.BR \%KEY_MOUSE .
.SH SEE ALSO
-\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).
+\fB\%curs_get_wch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its wide-character configuration
+.RI ( \%ncursesw ).
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_inopts\fP(3X),
+\fB\%curs_mouse\fP(3X),
+\fB\%curs_move\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%resizeterm\fP(3X),
+\fB\%ascii\fP(7)
+.PP
+ECMA-6 \*(``7-bit coded Character Set\*(''
+\%<https://\*:ecma\-international\*:.org/\
+\*:publications\-and\-standards/\*:standards/\*:ecma\-6/>
+.PP
+ECMA-48 \*(``Control Functions for Coded Character Sets\*(''
+\%<https://\*:ecma\-international\*:.org/\
+\*:publications\-and\-standards/\*:standards/\*:ecma\-48/>
projects / ncurses.git / blobdiff