+ <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>
+
+ <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <EM>ch</EM><STRONG>);</STRONG>
+
+ <EM>/*</EM> <EM>extension</EM> <EM>*/</EM>
+ <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <EM>ch</EM><STRONG>);</STRONG>
+
+
+</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>ch</EM> to the window (at the cursor position) per
+ the following rules.
+
+ <STRONG>o</STRONG> If <EM>ch</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>ch</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>ch</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 newline (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>ch</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
+
+ The keypad is arranged as follows.
+
+ +-----+------+-------+
+ | A1 | up | A3 |
+ +-----+------+-------+
+ |left | B2 | right |
+ +-----+------+-------+
+ | C1 | down | C3 |
+ +-----+------+-------+
+ Two of these symbols do <EM>not</EM> correspond to a real 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> detects the <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> takes a key code value from the above list, and
+ returns a Boolean value indicating the terminal's recognition of it.
+ 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>
+ <STRONG>wgetch</STRONG> returns <STRONG>ERR</STRONG> if
+
+ <STRONG>o</STRONG> the <EM>WINDOW</EM> pointer is <STRONG>NULL</STRONG>, or
+
+ <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>.
+
+ Functions with a "mv" prefix first perform cursor movement using
+ <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and fail if the position is outside the window, or (for "mvw"
+ functions) if the <EM>win</EM> parameter is a null pointer.
+
+ <STRONG>ungetch</STRONG> returns <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> 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, 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 terminal's keypad Enter key.
+
+ <STRONG>o</STRONG> "Enter or send" is X/Open Curses's description of this key.