+<!--
+ * t
+ ****************************************************************************
+ * 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 *
+ * 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.87 2024/04/20 19:18:18 tom Exp @
+-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
+<HEAD>
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
+<TITLE>curs_getch 3x 2024-04-20 ncurses 6.4 Library calls</TITLE>
+<link rel="author" href="mailto:bug-ncurses@gnu.org">
+
+</HEAD>
<BODY>
+<H1 class="no-header">curs_getch 3x 2024-04-20 ncurses 6.4 Library calls</H1>
<PRE>
-<!-- Manpage converted by man2html 3.0.1 -->
-
-</PRE>
-<H2>NAME</H2><PRE>
- <B>getch</B>, <B>wgetch</B>, <B>mvgetch</B>, <B>mvwgetch</B>, <B>ungetch</B>, <B>has_key</B> - get
- (or push back) characters from <B>curses</B> terminal keyboard
-
+<STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
-</PRE>
-<H2>SYNOPSIS</H2><PRE>
- <B>#include</B> <B><curses.h></B>
-
- <B>int</B> <B>getch(void);</B>
- <B>int</B> <B>wgetch(WINDOW</B> <B>*win);</B>
- <B>int</B> <B>mvgetch(int</B> <B>y,</B> <B>int</B> <B>x);</B>
- <B>int</B> <B>mvwgetch(WINDOW</B> <B>*win,</B> <B>int</B> <B>y,</B> <B>int</B> <B>x);</B>
- <B>int</B> <B>ungetch(int</B> <B>ch);</B>
- <B>int</B> <B>has_key(int</B> <B>ch);</B>
-</PRE>
-<H2>DESCRIPTION</H2><PRE>
- The <B>getch</B>, <B>wgetch</B>, <B>mvgetch</B> and <B>mvwgetch</B>, routines read a
- character from the window. In no-delay mode, if no input
- is waiting, the value <B>ERR</B> is returned. In delay mode, the
- program waits until the system passes text through to the
- program. Depending on the setting of <B>cbreak</B>, this is
- after 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.
-
- Unless <B>noecho</B> has been set, then the character will also
- be echoed into the designated window according to the fol-
- lowing rules: If the character is the current erase char-
- acter, left arrow, or backspace, the cursor is moved one
- space to the left and that screen position is erased as if
- <B>delch</B> had been called. If the character value is any
- other <B>KEY_</B> define, the user is alerted with a <B>beep</B> call.
- 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 <B>wrefresh</B>, <B>wrefresh</B> will be
- called before another character is read.
-
- If <B>keypad</B> is <B>TRUE</B>, 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
- <B><curses.h></B> as macros with values outside the range of
- 8-bit characters whose names begin with <B>KEY_.</B> 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
- escape character), <B>curses</B> 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 <B>ungetch</B> routine places <I>ch</I> back onto the input queue to
- be returned by the next call to <B>wgetch</B>. Note that there
- is, in effect, just one input queue for all windows.
-
-
- <B>Function</B> <B>Keys</B>
- The following function keys, defined in <B><curses.h></B>, might
- be returned by <B>getch</B> if <B>keypad</B> has been enabled. Note
- that not all of these are necessarily supported on any
- particular terminal.
-
- <I>Name</I> <I>Key</I> <I>name</I>
-
- 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(<I>n</I>) For 0 <= <I>n</I> <= 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:
-
- +-----+------+-------+
- | <B>A1</B> | <B>up</B> | <B>A3</B> |
- +-----+------+-------+
- |<B>left</B> | <B>B2</B> | <B>right</B> |
- +-----+------+-------+
- | <B>C1</B> | <B>down</B> | <B>C3</B> |
- +-----+------+-------+
- The <B>has_key</B> routine takes a key value from the above list,
- and returns TRUE or FALSE according as the current termi-
- nal type recognizes a key with that value.
+</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
+ <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, <STRONG>ungetch</STRONG>, <STRONG>has_key</STRONG> - get (or push back)
+ characters from <EM>curses</EM> terminal keyboard
+
+
+</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
+ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
+ <STRONG>int</STRONG> <STRONG>getch(void);</STRONG>
+ <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG>
+ <STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
+ <STRONG>int</STRONG> <STRONG>mvwgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
-</PRE>
-<H2>RETURN VALUE</H2><PRE>
- All routines return the integer <B>ERR</B> upon failure and an
- integer value other than <B>ERR</B> (<B>OK</B> in the case of ungetch())
- upon successful completion.
+ <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <EM>c</EM><STRONG>);</STRONG>
+ <EM>/*</EM> <EM>extension</EM> <EM>*/</EM>
+ <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <EM>c</EM><STRONG>);</STRONG>
-</PRE>
-<H2>NOTES</H2><PRE>
- 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.
-
- When using <B>getch</B>, <B>wgetch</B>, <B>mvgetch</B>, or <B>mvwgetch</B>, nocbreak
- mode (<B>nocbreak</B>) and echo mode (<B>echo</B>) 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 <B>getch</B>, <B>mvgetch</B>, and <B>mvwgetch</B> 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 <B>KEY_UP</B>,
- <B>KEY_DOWN</B>, <B>KEY_LEFT</B>, <B>KEY_RIGHT</B>, <B>KEY_HOME</B>, <B>KEY_END</B>,
- <B>KEY_NPAGE</B>, <B>KEY_PPAGE</B>, and function keys 1 through 12. The
- Ins key is usually mapped to <B>KEY_IC</B>.
-
-
-</PRE>
-<H2>PORTABILITY</H2><PRE>
- 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 <B>ERR</B> on failure,
- but specifies no error conditions.
-
- The echo behavior of these functions on input of <B>KEY_</B> or
- backspace characters was not specified in the SVr4 docu-
- mentation. This description is adopted from the XSI
- Curses standard.
-
- The behavior of <B>getch</B> 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
- implementation of handled signal receipt interrupts a
- <B><A HREF="read.2.html">read(2)</A></B> call in progress or not, and also (in some imple-
- mentations) depending on whether an input timeout or non-
- blocking mode hsd been set.
-
- Programmers concerned about portability should be prepared
- for either of two cases: (a) signal receipt does not
- interrupt <B>getch</B>; (b) signal receipt interrupts <B>getch</B> and
- causes it to return ERR with <B>errno</B> set to <B>EINTR</B>. Under
- the <B>ncurses</B> implementation, handled signals never inter-
- rupt <B>getch</B>.
-
- The <B>has_key</B> function is unique to <B>ncurses</B>. We recommend
- that any code using it be conditionalized on the
- <B>NCURSES_VERSION</B> feature macro.
-
-
-</PRE>
-<H2>SEE ALSO</H2><PRE>
- <B><A HREF="ncurses.3x.html">curses(3x)</A></B>, <B><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></B>, <B><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></B>,
- <B><A HREF="curs_move.3x.html">curs_move(3x)</A></B>, <B><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></B>. <B><A HREF="resizeterm.3x.html">resizeterm(3x)</A></B>.
+</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+</PRE><H3><a name="h3-Reading-Characters">Reading Characters</a></H3><PRE>
+ <STRONG>wgetch</STRONG> gathers a key stroke from the terminal keyboard associated with
+ a <EM>curses</EM> window <EM>win</EM>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this
+ function.
+ When input is pending, <STRONG>wgetch</STRONG> 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 <EM>win</EM> 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 <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits
+ until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> has been called, this
+ happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called,
+ it occurs when the next newline is read. If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been
+ called, <EM>curses</EM> waits until a character is typed or the specified delay
+ elapses.
+
+ If <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> has been called, and the window is not a pad, <EM>curses</EM> writes
+ the returned character <EM>c</EM> to the window (at the cursor position) per the
+ following rules.
+
+ <STRONG>o</STRONG> If <EM>c</EM> matches the terminal's erase character, the cursor moves
+ leftward one position and the new position is erased as if
+ <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG> were called. When the window's
+ keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are
+ handled the same way.
+
+ <STRONG>o</STRONG> <EM>curses</EM> writes any other <EM>c</EM> to the window, as with <STRONG><A HREF="curs_addch.3x.html">wechochar(3x)</A></STRONG>.
+
+ <STRONG>o</STRONG> If the window has been moved or modified since the last call to
+ <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG>.
+
+ If <EM>c</EM> is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> returns
+ the character code for line feed instead.
+
+
+</PRE><H3><a name="h3-Keypad-Mode">Keypad Mode</a></H3><PRE>
+ To <EM>curses</EM>, key strokes not from the alphabetic section of the keyboard
+ (those corresponding to the ECMA-6 character set--see
+ <STRONG>ascii(7)</STRONG>--optionally modified by either the control or shift keys) are
+ treated as <EM>function</EM> keys. (In <EM>curses</EM>, 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 <STRONG>KEY_</STRONG> 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 <STRONG>wgetch</STRONG> calls.
+
+ <STRONG>o</STRONG> The <EM>curses.h</EM> header file declares many <EM>predefined</EM> <EM>function</EM> <EM>keys</EM>
+ whose names begin with <STRONG>KEY_</STRONG>; these object-like macros have values
+ outside the range of eight-bit character codes.
+
+ <STRONG>o</STRONG> In <EM>ncurses</EM>, <EM>user-defined</EM> <EM>function</EM> <EM>keys</EM> are configured with
+ <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>; 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
+ <EM>short</EM> 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 <EM>curses</EM> 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 <EM>curses</EM> reads such an ambiguous
+ character, it sets a timer. If the remainder of the sequence does not
+ arrive within the designated time, <STRONG>wgetch</STRONG> 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 <EM>curses</EM>
+ application may experience a delay after pressing ESC while <EM>curses</EM>
+ 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 <STRONG><A HREF="notimeout.3x.html">notimeout(3x)</A></STRONG>. 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" <EM>curses</EM>.
+
+
+</PRE><H3><a name="h3-Ungetting-Characters">Ungetting Characters</a></H3><PRE>
+ <STRONG>ungetch</STRONG> places <EM>c</EM> into the input queue to be returned by the next call
+ to <STRONG>wgetch</STRONG>. A single input queue serves all windows.
+
+
+</PRE><H3><a name="h3-Predefined-Key-Codes">Predefined Key Codes</a></H3><PRE>
+ The header file <EM>curses.h</EM> defines the following function key codes.
+
+ <STRONG>o</STRONG> Except for the special case of <STRONG>KEY_RESIZE</STRONG>, a window's keypad mode
+ must be enabled for <STRONG>wgetch</STRONG> to read these codes from it.
+
+ <STRONG>o</STRONG> Not all of these are necessarily supported on any particular
+ terminal.
+
+ <STRONG>o</STRONG> The naming convention may seem obscure, with some apparent
+ misspellings (such as "RSUME" for "resume"); the names correspond
+ to the <EM>terminfo</EM> capability names for the keys, and were
+ standardized before the IBM PC/AT keyboard layout achieved a
+ dominant position in industry.
+
+ <STRONG>Symbol</STRONG> <STRONG>Key</STRONG> <STRONG>name</STRONG>
+ -----------------------------------------------------------------
+ <STRONG>KEY_BREAK</STRONG> Break key
+ <STRONG>KEY_DOWN</STRONG>
+ <STRONG>KEY_UP</STRONG> Arrow keys
+ <STRONG>KEY_LEFT</STRONG>
+ <STRONG>KEY_RIGHT</STRONG>
+ <STRONG>KEY_HOME</STRONG> Home key (upward+left arrow)
+ <STRONG>KEY_BACKSPACE</STRONG> Backspace
+ <STRONG>KEY_F0</STRONG> Function keys; space for 64 keys is reserved
+ <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> Function key <EM>n</EM> where 0 <= <EM>n</EM> <= 63
+
+ <STRONG>KEY_DL</STRONG> Delete line
+ <STRONG>KEY_IL</STRONG> Insert line
+ <STRONG>KEY_DC</STRONG> Delete character
+ <STRONG>KEY_IC</STRONG> Insert character/Enter insert mode
+ <STRONG>KEY_EIC</STRONG> Exit insert character mode
+ <STRONG>KEY_CLEAR</STRONG> Clear screen
+ <STRONG>KEY_EOS</STRONG> Clear to end of screen
+ <STRONG>KEY_EOL</STRONG> Clear to end of line
+ <STRONG>KEY_SF</STRONG> Scroll one line forward
+ <STRONG>KEY_SR</STRONG> Scroll one line backward (reverse)
+ <STRONG>KEY_NPAGE</STRONG> Next page/Page up
+ <STRONG>KEY_PPAGE</STRONG> Previous page/Page down
+ <STRONG>KEY_STAB</STRONG> Set tab
+ <STRONG>KEY_CTAB</STRONG> Clear tab
+ <STRONG>KEY_CATAB</STRONG> Clear all tabs
+ <STRONG>KEY_ENTER</STRONG> Enter/Send
+ <STRONG>KEY_SRESET</STRONG> Soft (partial) reset
+ <STRONG>KEY_RESET</STRONG> (Hard) reset
+ <STRONG>KEY_PRINT</STRONG> Print/Copy
+ <STRONG>KEY_LL</STRONG> Home down/Bottom (lower left)
+ <STRONG>KEY_A1</STRONG> Upper left of keypad
+ <STRONG>KEY_A3</STRONG> Upper right of keypad
+ <STRONG>KEY_B2</STRONG> Center of keypad
+ <STRONG>KEY_C1</STRONG> Lower left of keypad
+ <STRONG>KEY_C3</STRONG> Lower right of keypad
+ <STRONG>KEY_BTAB</STRONG> Back tab key
+ <STRONG>KEY_BEG</STRONG> Beg(inning) key
+ <STRONG>KEY_CANCEL</STRONG> Cancel key
+ <STRONG>KEY_CLOSE</STRONG> Close key
+ <STRONG>KEY_COMMAND</STRONG> Cmd (command) key
+ <STRONG>KEY_COPY</STRONG> Copy key
+ <STRONG>KEY_CREATE</STRONG> Create key
+ <STRONG>KEY_END</STRONG> End key
+ <STRONG>KEY_EXIT</STRONG> Exit key
+ <STRONG>KEY_FIND</STRONG> Find key
+ <STRONG>KEY_HELP</STRONG> Help key
+ <STRONG>KEY_MARK</STRONG> Mark key
+ <STRONG>KEY_MESSAGE</STRONG> Message key
+ <STRONG>KEY_MOUSE</STRONG> Mouse event occurred
+ <STRONG>KEY_MOVE</STRONG> Move key
+ <STRONG>KEY_NEXT</STRONG> Next object key
+ <STRONG>KEY_OPEN</STRONG> Open key
+ <STRONG>KEY_OPTIONS</STRONG> Options key
+ <STRONG>KEY_PREVIOUS</STRONG> Previous object key
+ <STRONG>KEY_REDO</STRONG> Redo key
+ <STRONG>KEY_REFERENCE</STRONG> Ref(erence) key
+ <STRONG>KEY_REFRESH</STRONG> Refresh key
+ <STRONG>KEY_REPLACE</STRONG> Replace key
+ <STRONG>KEY_RESIZE</STRONG> Screen resized
+ <STRONG>KEY_RESTART</STRONG> Restart key
+ <STRONG>KEY_RESUME</STRONG> Resume key
+ <STRONG>KEY_SAVE</STRONG> Save key
+ <STRONG>KEY_SELECT</STRONG> Select key
+ <STRONG>KEY_SUSPEND</STRONG> Suspend key
+ <STRONG>KEY_UNDO</STRONG> Undo key
+ -----------------------------------------------------------------
+ <STRONG>KEY_SBEG</STRONG> Shifted beginning key
+ <STRONG>KEY_SCANCEL</STRONG> Shifted cancel key
+ <STRONG>KEY_SCOMMAND</STRONG> Shifted command key
+ <STRONG>KEY_SCOPY</STRONG> Shifted copy key
+ <STRONG>KEY_SCREATE</STRONG> Shifted create key
+ <STRONG>KEY_SDC</STRONG> Shifted delete character key
+ <STRONG>KEY_SDL</STRONG> Shifted delete line key
+ <STRONG>KEY_SEND</STRONG> Shifted end key
+ <STRONG>KEY_SEOL</STRONG> Shifted clear line key
+
+ <STRONG>KEY_SEXIT</STRONG> Shifted exit key
+ <STRONG>KEY_SFIND</STRONG> Shifted find key
+ <STRONG>KEY_SHELP</STRONG> Shifted help key
+ <STRONG>KEY_SHOME</STRONG> Shifted home key
+ <STRONG>KEY_SIC</STRONG> Shifted insert key
+ <STRONG>KEY_SLEFT</STRONG> Shifted left arrow key
+ <STRONG>KEY_SMESSAGE</STRONG> Shifted message key
+ <STRONG>KEY_SMOVE</STRONG> Shifted move key
+ <STRONG>KEY_SNEXT</STRONG> Shifted next object key
+ <STRONG>KEY_SOPTIONS</STRONG> Shifted options key
+ <STRONG>KEY_SPREVIOUS</STRONG> Shifted previous object key
+ <STRONG>KEY_SPRINT</STRONG> Shifted print key
+ <STRONG>KEY_SREDO</STRONG> Shifted redo key
+ <STRONG>KEY_SREPLACE</STRONG> Shifted replace key
+ <STRONG>KEY_SRIGHT</STRONG> Shifted right arrow key
+ <STRONG>KEY_SRSUME</STRONG> Shifted resume key
+ <STRONG>KEY_SSAVE</STRONG> Shifted save key
+ <STRONG>KEY_SSUSPEND</STRONG> Shifted suspend key
+ <STRONG>KEY_SUNDO</STRONG> 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 <EM>not</EM> correspond to a physical
+ key.
+
+ <STRONG>o</STRONG> <STRONG>wgetch</STRONG> returns <STRONG>KEY_RESIZE</STRONG>, even if the window's keypad mode is
+ disabled, when <EM>ncurses</EM> handles a <STRONG>SIGWINCH</STRONG> signal; see <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>
+ and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>.
+
+ <STRONG>o</STRONG> <STRONG>wgetch</STRONG> returns <STRONG>KEY_MOUSE</STRONG> to indicate that a mouse event is pending
+ collection; see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>. Receipt of this code requires a
+ window's keypad mode to be enabled, because to interpret mouse
+ input (as with with <STRONG>xterm(1)</STRONG>'s mouse prototocol), <EM>ncurses</EM> must read
+ an escape sequence, as with a function key.
+
+
+</PRE><H3><a name="h3-Testing-Key-Codes">Testing Key Codes</a></H3><PRE>
+ In <EM>ncurses</EM>, <STRONG>has_key</STRONG> returns a Boolean value indicating whether the
+ terminal type recognizes its parameter as a key code value. See also
+ <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> and <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>.
+
+
+</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
+ Except for <STRONG>has_key</STRONG>, these functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on
+ failure.
+
+ Functions taking a <EM>WINDOW</EM> pointer argument fail if the pointer is <STRONG>NULL</STRONG>.
+
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
+
+ <STRONG>wgetch</STRONG> also fails if
+
+ <STRONG>o</STRONG> its timeout expires without any data arriving, or
+
+ <STRONG>o</STRONG> execution was interrupted by a signal, in which case <STRONG>errno</STRONG> is set
+ to <STRONG>EINTR</STRONG>.
+
+ <STRONG>ungetch</STRONG> fails if there is no more room in the input queue.
+
+ <STRONG>has_key</STRONG> returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
+
+
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+ <EM>curses</EM> 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, <STRONG>KEY_ENTER</STRONG> may be the same as <STRONG>^M</STRONG>, and <STRONG>KEY_BACKSPACE</STRONG> may be the
+ same as <STRONG>^H</STRONG> or <STRONG>^?</STRONG>. Consult the terminal's <EM>terminfo</EM> entry to determine
+ whether this is the case; see <STRONG><A HREF="infocmp.1m.html">infocmp(1)</A></STRONG>. Some <EM>curses</EM> implementations,
+ including <EM>ncurses</EM>, honor the <EM>terminfo</EM> key definitions; others treat
+ such control characters specially.
+
+ <EM>curses</EM> distinguishes the Enter keys in the alphabetic and numeric
+ keypad sections of a keyboard because (most) terminals do. <STRONG>KEY_ENTER</STRONG>
+ 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.
+
+ <STRONG>o</STRONG> The <EM>terminfo</EM> <STRONG>key_enter</STRONG> (<STRONG>kent</STRONG>) capability describes the character
+ (sequence) sent by the Enter key of a terminal's numeric (or
+ similar) keypad.
+ <STRONG>o</STRONG> "Enter or send" is X/Open Curses's description of this key.
+ <EM>curses</EM> treats the Enter or Return key in the <EM>alphabetic</EM> section of the
+ keyboard differently.
+ <STRONG>o</STRONG> It usually produces a control code for carriage return (<STRONG>^M</STRONG>) or line
+ feed (<STRONG>^J</STRONG>).
+ <STRONG>o</STRONG> Depending on the terminal mode (raw, cbreak, or "cooked"), and
+ whether <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> or <STRONG><A HREF="curs_inopts.3x.html">nonl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> may return
+ either a carriage return or line feed upon an Enter or Return key
+ stroke.
+ Use of <STRONG>wgetch</STRONG> with <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> and neither <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> nor <STRONG><A HREF="curs_inopts.3x.html">raw(3x)</A></STRONG> 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 <EM>curses</EM> application can expect such a keyboard to transmit key
+ codes <STRONG>KEY_UP</STRONG>, <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>,
+ <STRONG>KEY_PPAGE</STRONG> (Page Up), <STRONG>KEY_NPAGE</STRONG> (Page Down), <STRONG>KEY_IC</STRONG> (Insert), <STRONG>KEY_DC</STRONG>
+ (Delete), and <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> for 1 <= <EM>n</EM> <= 12.
+ <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be implemented as macros.
+</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
+ In <EM>ncurses</EM>, when a window's "no time-out" mode is <EM>not</EM> set, the <STRONG>ESCDELAY</STRONG>
+ 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 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
+ <STRONG>has_key</STRONG> was designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and is not found in SVr4 <EM>curses</EM>,
+ 4.4BSD <EM>curses</EM>, or any other previous curses implementation.
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+ Applications employing <EM>ncurses</EM> extensions should condition their use on
+ the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
+ X/Open Curses, Issue 4 describes <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, and
+ <STRONG>ungetch</STRONG>. It specifies no error conditions for them.
+ <STRONG>wgetch</STRONG> reads only single-byte characters.
+ The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or backspace
+ characters was not specified in the SVr4 documentation. This
+ description is adapted from X/Open Curses.
+ The behavior of <STRONG>wgetch</STRONG> in the presence of signal handlers is
+ unspecified in the SVr4 documentation and X/Open Curses. In historical
+ <EM>curses</EM> implementations, it varied depending on whether the operating
+ system's dispatch of a signal to a handler interrupting a <STRONG>read(2)</STRONG> 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 <STRONG>wgetch</STRONG>; or (b) signal receipt interrupts
+ <STRONG>wgetch</STRONG> and causes it to return <STRONG>ERR</STRONG> with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>.
+ <STRONG>KEY_MOUSE</STRONG> is mentioned in X/Open Curses, along with a few related <EM>term-</EM>
+ <EM>info</EM> capabilities, but no higher-level functions use the feature. The
+ implementation in <EM>ncurses</EM> is an extension.
+ <STRONG>KEY_RESIZE</STRONG> and <STRONG>has_key</STRONG> are extensions first implemented for <EM>ncurses</EM>.
+ By 2022, <EM>PDCurses</EM> and NetBSD <EM>curses</EM> had added them along with
+ <STRONG>KEY_MOUSE</STRONG>.
+</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
+ <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
+ in its wide-character configuration (<EM>ncursesw</EM>).
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>,
+ <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
+ <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>, <STRONG>ascii(7)</STRONG>
+ ECMA-6 "7-bit coded Character Set" <https://ecma-international.org/
+ publications-and-standards/standards/ecma-6/>
+ ECMA-48 "Control Functions for Coded Character Sets" <https://
+ ecma-international.org/publications-and-standards/standards/ecma-48/>
+ncurses 6.4 2024-04-20 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
</PRE>
-<HR>
-<ADDRESS>
-Man(1) output converted with
-<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
-</ADDRESS>
+<div class="nav">
+<ul>
+<li><a href="#h2-NAME">NAME</a></li>
+<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
+<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
+<ul>
+<li><a href="#h3-Reading-Characters">Reading Characters</a></li>
+<li><a href="#h3-Keypad-Mode">Keypad Mode</a></li>
+<li><a href="#h3-Ungetting-Characters">Ungetting Characters</a></li>
+<li><a href="#h3-Predefined-Key-Codes">Predefined Key Codes</a></li>
+<li><a href="#h3-Testing-Key-Codes">Testing Key Codes</a></li>
+</ul>
+</li>
+<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
+<li><a href="#h2-NOTES">NOTES</a></li>
+<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
+<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
+</ul>
+</div>
</BODY>
</HTML>
projects / ncurses.git / blobdiff