1<!-- 2 * t 3 **************************************************************************** 4 * Copyright 2018-2023,2024 Thomas E. Dickey * 5 * Copyright 1998-2016,2017 Free Software Foundation, Inc. * 6 * * 7 * Permission is hereby granted, free of charge, to any person obtaining a * 8 * copy of this software and associated documentation files (the * 9 * "Software"), to deal in the Software without restriction, including * 10 * without limitation the rights to use, copy, modify, merge, publish, * 11 * distribute, distribute with modifications, sublicense, and/or sell * 12 * copies of the Software, and to permit persons to whom the Software is * 13 * furnished to do so, subject to the following conditions: * 14 * * 15 * The above copyright notice and this permission notice shall be included * 16 * in all copies or substantial portions of the Software. * 17 * * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * 19 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * 20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * 21 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * 22 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * 23 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * 24 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * 25 * * 26 * Except as contained in this notice, the name(s) of the above copyright * 27 * holders shall not be used in advertising or otherwise to promote the * 28 * sale, use or other dealings in this Software without prior written * 29 * authorization. * 30 **************************************************************************** 31 * @Id: curs_getch.3x,v 1.87 2024/04/20 19:18:18 tom Exp @ 32--> 33<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> 34<HTML> 35<HEAD> 36<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 37<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> 38<TITLE>curs_getch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> 39<link rel="author" href="mailto:bug-ncurses@gnu.org"> 40 41</HEAD> 42<BODY> 43<H1 class="no-header">curs_getch 3x 2024-04-20 ncurses 6.5 Library calls</H1> 44<PRE> 45<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> 46 47 48 49 50</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> 51 <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, <STRONG>ungetch</STRONG>, <STRONG>has_key</STRONG> - get (or push back) 52 characters from <EM>curses</EM> terminal keyboard 53 54 55</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> 56 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> 57 58 <STRONG>int</STRONG> <STRONG>getch(void);</STRONG> 59 <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> 60 <STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> 61 <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> 62 63 <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <EM>c</EM><STRONG>);</STRONG> 64 65 <EM>/*</EM> <EM>extension</EM> <EM>*/</EM> 66 <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <EM>c</EM><STRONG>);</STRONG> 67 68 69</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> 70 71</PRE><H3><a name="h3-Reading-Characters">Reading Characters</a></H3><PRE> 72 <STRONG>wgetch</STRONG> gathers a key stroke from the terminal keyboard associated with 73 a <EM>curses</EM> window <EM>win</EM>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this 74 function. 75 76 When input is pending, <STRONG>wgetch</STRONG> returns an integer identifying the key 77 stroke; for alphanumeric and punctuation keys, this value corresponds 78 to the character encoding used by the terminal. Use of the control key 79 as a modifier often results in a distinct code. The behavior of other 80 keys depends on whether <EM>win</EM> is in keypad mode; see subsection "Keypad 81 Mode" below. 82 83 If no input is pending, then if the no-delay flag is set in the window 84 (see <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits 85 until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> has been called, this 86 happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called, 87 it occurs when the next newline is read. If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been 88 called, <EM>curses</EM> waits until a character is typed or the specified delay 89 elapses. 90 91 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 92 the returned character <EM>c</EM> to the window (at the cursor position) per the 93 following rules. 94 95 <STRONG>o</STRONG> If <EM>c</EM> matches the terminal's erase character, the cursor moves 96 leftward one position and the new position is erased as if 97 <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 98 keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are 99 handled the same way. 100 101 <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>. 102 103 <STRONG>o</STRONG> If the window has been moved or modified since the last call to 104 <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG>. 105 106 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 107 the character code for line feed instead. 108 109 110</PRE><H3><a name="h3-Keypad-Mode">Keypad Mode</a></H3><PRE> 111 To <EM>curses</EM>, key strokes not from the alphabetic section of the keyboard 112 (those corresponding to the ECMA-6 character set--see 113 <STRONG>ascii(7)</STRONG>--optionally modified by either the control or shift keys) are 114 treated as <EM>function</EM> keys. (In <EM>curses</EM>, the term "function key" includes 115 but is not limited to keycaps engraved with "F1", "PF1", and so on.) 116 If the window is in keypad mode, these produce a numeric code 117 corresponding to the <STRONG>KEY_</STRONG> symbols listed in subsection "Predefined Key 118 Codes" below; otherwise, they transmit a sequence of codes typically 119 starting with the escape character, and which must be collected with 120 multiple <STRONG>wgetch</STRONG> calls. 121 122 <STRONG>o</STRONG> The <EM>curses.h</EM> header file declares many <EM>predefined</EM> <EM>function</EM> <EM>keys</EM> 123 whose names begin with <STRONG>KEY_</STRONG>; these object-like macros have values 124 outside the range of eight-bit character codes. 125 126 <STRONG>o</STRONG> In <EM>ncurses</EM>, <EM>user-defined</EM> <EM>function</EM> <EM>keys</EM> are configured with 127 <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>; they have no names, but are also expected to have 128 values outside the range of eight-bit codes. 129 130 A variable intended to hold a function key code must thus be of type 131 <EM>short</EM> or larger. 132 133 Most terminals one encounters follow the ECMA-48 standard insofar as 134 their function keys produce character sequences prefixed with the 135 escape character ESC. This fact implies that <EM>curses</EM> cannot know 136 whether the terminal has sent an ESC key stroke or the beginning of a 137 function key's character sequence without waiting to see if, and how 138 soon, further input arrives. When <EM>curses</EM> reads such an ambiguous 139 character, it sets a timer. If the remainder of the sequence does not 140 arrive within the designated time, <STRONG>wgetch</STRONG> returns the prefix character; 141 otherwise, it returns the function key code corresponding to the unique 142 sequence defined by the terminal. Consequently, a user of a <EM>curses</EM> 143 application may experience a delay after pressing ESC while <EM>curses</EM> 144 disambiguates the input; see section "EXTENSIONS" below. If the window 145 is in "no time-out" mode, the timer does not expire; it is an infinite 146 (or very large) value. See <STRONG><A HREF="notimeout.3x.html">notimeout(3x)</A></STRONG>. Because function key 147 sequences usually begin with an escape character, the terminal may 148 appear to hang in no time-out mode after the user has pressed ESC. 149 Generally, further typing "awakens" <EM>curses</EM>. 150 151 152</PRE><H3><a name="h3-Ungetting-Characters">Ungetting Characters</a></H3><PRE> 153 <STRONG>ungetch</STRONG> places <EM>c</EM> into the input queue to be returned by the next call 154 to <STRONG>wgetch</STRONG>. A single input queue serves all windows. 155 156 157</PRE><H3><a name="h3-Predefined-Key-Codes">Predefined Key Codes</a></H3><PRE> 158 The header file <EM>curses.h</EM> defines the following function key codes. 159 160 <STRONG>o</STRONG> Except for the special case of <STRONG>KEY_RESIZE</STRONG>, a window's keypad mode 161 must be enabled for <STRONG>wgetch</STRONG> to read these codes from it. 162 163 <STRONG>o</STRONG> Not all of these are necessarily supported on any particular 164 terminal. 165 166 <STRONG>o</STRONG> The naming convention may seem obscure, with some apparent 167 misspellings (such as "RSUME" for "resume"); the names correspond 168 to the <EM>terminfo</EM> capability names for the keys, and were 169 standardized before the IBM PC/AT keyboard layout achieved a 170 dominant position in industry. 171 172 <STRONG>Symbol</STRONG> <STRONG>Key</STRONG> <STRONG>name</STRONG> 173 ----------------------------------------------------------------- 174 <STRONG>KEY_BREAK</STRONG> Break key 175 <STRONG>KEY_DOWN</STRONG> 176 <STRONG>KEY_UP</STRONG> Arrow keys 177 <STRONG>KEY_LEFT</STRONG> 178 <STRONG>KEY_RIGHT</STRONG> 179 <STRONG>KEY_HOME</STRONG> Home key (upward+left arrow) 180 <STRONG>KEY_BACKSPACE</STRONG> Backspace 181 <STRONG>KEY_F0</STRONG> Function keys; space for 64 keys is reserved 182 <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> Function key <EM>n</EM> where 0 <= <EM>n</EM> <= 63 183 184 <STRONG>KEY_DL</STRONG> Delete line 185 <STRONG>KEY_IL</STRONG> Insert line 186 <STRONG>KEY_DC</STRONG> Delete character 187 <STRONG>KEY_IC</STRONG> Insert character/Enter insert mode 188 <STRONG>KEY_EIC</STRONG> Exit insert character mode 189 <STRONG>KEY_CLEAR</STRONG> Clear screen 190 <STRONG>KEY_EOS</STRONG> Clear to end of screen 191 <STRONG>KEY_EOL</STRONG> Clear to end of line 192 <STRONG>KEY_SF</STRONG> Scroll one line forward 193 <STRONG>KEY_SR</STRONG> Scroll one line backward (reverse) 194 <STRONG>KEY_NPAGE</STRONG> Next page/Page up 195 <STRONG>KEY_PPAGE</STRONG> Previous page/Page down 196 <STRONG>KEY_STAB</STRONG> Set tab 197 <STRONG>KEY_CTAB</STRONG> Clear tab 198 <STRONG>KEY_CATAB</STRONG> Clear all tabs 199 <STRONG>KEY_ENTER</STRONG> Enter/Send 200 <STRONG>KEY_SRESET</STRONG> Soft (partial) reset 201 <STRONG>KEY_RESET</STRONG> (Hard) reset 202 <STRONG>KEY_PRINT</STRONG> Print/Copy 203 <STRONG>KEY_LL</STRONG> Home down/Bottom (lower left) 204 <STRONG>KEY_A1</STRONG> Upper left of keypad 205 <STRONG>KEY_A3</STRONG> Upper right of keypad 206 <STRONG>KEY_B2</STRONG> Center of keypad 207 <STRONG>KEY_C1</STRONG> Lower left of keypad 208 <STRONG>KEY_C3</STRONG> Lower right of keypad 209 <STRONG>KEY_BTAB</STRONG> Back tab key 210 <STRONG>KEY_BEG</STRONG> Beg(inning) key 211 <STRONG>KEY_CANCEL</STRONG> Cancel key 212 <STRONG>KEY_CLOSE</STRONG> Close key 213 <STRONG>KEY_COMMAND</STRONG> Cmd (command) key 214 <STRONG>KEY_COPY</STRONG> Copy key 215 <STRONG>KEY_CREATE</STRONG> Create key 216 <STRONG>KEY_END</STRONG> End key 217 <STRONG>KEY_EXIT</STRONG> Exit key 218 <STRONG>KEY_FIND</STRONG> Find key 219 <STRONG>KEY_HELP</STRONG> Help key 220 <STRONG>KEY_MARK</STRONG> Mark key 221 <STRONG>KEY_MESSAGE</STRONG> Message key 222 <STRONG>KEY_MOUSE</STRONG> Mouse event occurred 223 <STRONG>KEY_MOVE</STRONG> Move key 224 <STRONG>KEY_NEXT</STRONG> Next object key 225 <STRONG>KEY_OPEN</STRONG> Open key 226 <STRONG>KEY_OPTIONS</STRONG> Options key 227 <STRONG>KEY_PREVIOUS</STRONG> Previous object key 228 <STRONG>KEY_REDO</STRONG> Redo key 229 <STRONG>KEY_REFERENCE</STRONG> Ref(erence) key 230 <STRONG>KEY_REFRESH</STRONG> Refresh key 231 <STRONG>KEY_REPLACE</STRONG> Replace key 232 <STRONG>KEY_RESIZE</STRONG> Screen resized 233 <STRONG>KEY_RESTART</STRONG> Restart key 234 <STRONG>KEY_RESUME</STRONG> Resume key 235 <STRONG>KEY_SAVE</STRONG> Save key 236 <STRONG>KEY_SELECT</STRONG> Select key 237 <STRONG>KEY_SUSPEND</STRONG> Suspend key 238 <STRONG>KEY_UNDO</STRONG> Undo key 239 ----------------------------------------------------------------- 240 <STRONG>KEY_SBEG</STRONG> Shifted beginning key 241 <STRONG>KEY_SCANCEL</STRONG> Shifted cancel key 242 <STRONG>KEY_SCOMMAND</STRONG> Shifted command key 243 <STRONG>KEY_SCOPY</STRONG> Shifted copy key 244 <STRONG>KEY_SCREATE</STRONG> Shifted create key 245 <STRONG>KEY_SDC</STRONG> Shifted delete character key 246 <STRONG>KEY_SDL</STRONG> Shifted delete line key 247 <STRONG>KEY_SEND</STRONG> Shifted end key 248 <STRONG>KEY_SEOL</STRONG> Shifted clear line key 249 250 <STRONG>KEY_SEXIT</STRONG> Shifted exit key 251 <STRONG>KEY_SFIND</STRONG> Shifted find key 252 <STRONG>KEY_SHELP</STRONG> Shifted help key 253 <STRONG>KEY_SHOME</STRONG> Shifted home key 254 <STRONG>KEY_SIC</STRONG> Shifted insert key 255 <STRONG>KEY_SLEFT</STRONG> Shifted left arrow key 256 <STRONG>KEY_SMESSAGE</STRONG> Shifted message key 257 <STRONG>KEY_SMOVE</STRONG> Shifted move key 258 <STRONG>KEY_SNEXT</STRONG> Shifted next object key 259 <STRONG>KEY_SOPTIONS</STRONG> Shifted options key 260 <STRONG>KEY_SPREVIOUS</STRONG> Shifted previous object key 261 <STRONG>KEY_SPRINT</STRONG> Shifted print key 262 <STRONG>KEY_SREDO</STRONG> Shifted redo key 263 <STRONG>KEY_SREPLACE</STRONG> Shifted replace key 264 <STRONG>KEY_SRIGHT</STRONG> Shifted right arrow key 265 <STRONG>KEY_SRSUME</STRONG> Shifted resume key 266 <STRONG>KEY_SSAVE</STRONG> Shifted save key 267 <STRONG>KEY_SSUSPEND</STRONG> Shifted suspend key 268 <STRONG>KEY_SUNDO</STRONG> Shifted undo key 269 270 Many keyboards feature a nine-key directional pad. 271 272 +-----+------+-------+ 273 | A1 | up | A3 | 274 +-----+------+-------+ 275 |left | B2 | right | 276 +-----+------+-------+ 277 | C1 | down | C3 | 278 +-----+------+-------+ 279 Two of the symbols in the list above do <EM>not</EM> correspond to a physical 280 key. 281 282 <STRONG>o</STRONG> <STRONG>wgetch</STRONG> returns <STRONG>KEY_RESIZE</STRONG>, even if the window's keypad mode is 283 disabled, when <EM>ncurses</EM> handles a <STRONG>SIGWINCH</STRONG> signal; see <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> 284 and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>. 285 286 <STRONG>o</STRONG> <STRONG>wgetch</STRONG> returns <STRONG>KEY_MOUSE</STRONG> to indicate that a mouse event is pending 287 collection; see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>. Receipt of this code requires a 288 window's keypad mode to be enabled, because to interpret mouse 289 input (as with with <STRONG>xterm(1)</STRONG>'s mouse prototocol), <EM>ncurses</EM> must read 290 an escape sequence, as with a function key. 291 292 293</PRE><H3><a name="h3-Testing-Key-Codes">Testing Key Codes</a></H3><PRE> 294 In <EM>ncurses</EM>, <STRONG>has_key</STRONG> returns a Boolean value indicating whether the 295 terminal type recognizes its parameter as a key code value. See also 296 <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>. 297 298 299</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> 300 Except for <STRONG>has_key</STRONG>, these functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on 301 failure. 302 303 Functions taking a <EM>WINDOW</EM> pointer argument fail if the pointer is <STRONG>NULL</STRONG>. 304 305 Functions prefixed with "mv" first perform cursor movement and fail if 306 the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. 307 308 <STRONG>wgetch</STRONG> also fails if 309 310 <STRONG>o</STRONG> its timeout expires without any data arriving, or 311 312 <STRONG>o</STRONG> execution was interrupted by a signal, in which case <STRONG>errno</STRONG> is set 313 to <STRONG>EINTR</STRONG>. 314 315 <STRONG>ungetch</STRONG> fails if there is no more room in the input queue. 316 317 <STRONG>has_key</STRONG> returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>. 318 319 320</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> 321 <EM>curses</EM> discourages assignment of the ESC key to a discrete function by 322 the programmer because the library requires a delay while it awaits the 323 potential remainder of a terminal escape sequence. 324 325 Some key strokes are indistinguishable from control characters; for 326 example, <STRONG>KEY_ENTER</STRONG> may be the same as <STRONG>^M</STRONG>, and <STRONG>KEY_BACKSPACE</STRONG> may be the 327 same as <STRONG>^H</STRONG> or <STRONG>^?</STRONG>. Consult the terminal's <EM>terminfo</EM> entry to determine 328 whether this is the case; see <STRONG><A HREF="infocmp.1m.html">infocmp(1)</A></STRONG>. Some <EM>curses</EM> implementations, 329 including <EM>ncurses</EM>, honor the <EM>terminfo</EM> key definitions; others treat 330 such control characters specially. 331 332 <EM>curses</EM> distinguishes the Enter keys in the alphabetic and numeric 333 keypad sections of a keyboard because (most) terminals do. <STRONG>KEY_ENTER</STRONG> 334 refers to the key on the numeric keypad and, like other function keys, 335 and is reliably recognized only if the window's keypad mode is enabled. 336 337 <STRONG>o</STRONG> The <EM>terminfo</EM> <STRONG>key_enter</STRONG> (<STRONG>kent</STRONG>) capability describes the character 338 (sequence) sent by the Enter key of a terminal's numeric (or 339 similar) keypad. 340 341 <STRONG>o</STRONG> "Enter or send" is X/Open Curses's description of this key. 342 343 <EM>curses</EM> treats the Enter or Return key in the <EM>alphabetic</EM> section of the 344 keyboard differently. 345 346 <STRONG>o</STRONG> It usually produces a control code for carriage return (<STRONG>^M</STRONG>) or line 347 feed (<STRONG>^J</STRONG>). 348 349 <STRONG>o</STRONG> Depending on the terminal mode (raw, cbreak, or "cooked"), and 350 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 351 either a carriage return or line feed upon an Enter or Return key 352 stroke. 353 354 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 355 well-defined. 356 357 Historically, the list of key code macros above was influenced by the 358 function-key-rich keyboard of the AT&T 7300 (also known variously as 359 the "3B1", "Safari 4", and "UNIX PC"), a 1985 machine. Today's 360 computer keyboards are based that of the IBM PC/AT and tend to have 361 fewer. A <EM>curses</EM> application can expect such a keyboard to transmit key 362 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>, 363 <STRONG>KEY_PPAGE</STRONG> (Page Up), <STRONG>KEY_NPAGE</STRONG> (Page Down), <STRONG>KEY_IC</STRONG> (Insert), <STRONG>KEY_DC</STRONG> 364 (Delete), and <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> for 1 <= <EM>n</EM> <= 12. 365 366 <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be implemented as macros. 367 368 369</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> 370 In <EM>ncurses</EM>, when a window's "no time-out" mode is <EM>not</EM> set, the <STRONG>ESCDELAY</STRONG> 371 variable configures the duration of the timer used to disambiguate a 372 function key character sequence from a series of key strokes beginning 373 with ESC typed by the user; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>. 374 375 <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>, 376 4.4BSD <EM>curses</EM>, or any other previous curses implementation. 377 378 379</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> 380 Applications employing <EM>ncurses</EM> extensions should condition their use on 381 the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. 382 383 X/Open Curses, Issue 4 describes <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, and 384 <STRONG>ungetch</STRONG>. It specifies no error conditions for them. 385 386 <STRONG>wgetch</STRONG> reads only single-byte characters. 387 388 The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or backspace 389 characters was not specified in the SVr4 documentation. This 390 description is adapted from X/Open Curses. 391 392 The behavior of <STRONG>wgetch</STRONG> in the presence of signal handlers is 393 unspecified in the SVr4 documentation and X/Open Curses. In historical 394 <EM>curses</EM> implementations, it varied depending on whether the operating 395 system's dispatch of a signal to a handler interrupting a <STRONG>read(2)</STRONG> call 396 in progress, and also (in some implementations) whether an input 397 timeout or non-blocking mode has been set. Programmers concerned about 398 portability should be prepared for either of two cases: (a) signal 399 receipt does not interrupt <STRONG>wgetch</STRONG>; or (b) signal receipt interrupts 400 <STRONG>wgetch</STRONG> and causes it to return <STRONG>ERR</STRONG> with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. 401 402 <STRONG>KEY_MOUSE</STRONG> is mentioned in X/Open Curses, along with a few related <EM>term-</EM> 403 <EM>info</EM> capabilities, but no higher-level functions use the feature. The 404 implementation in <EM>ncurses</EM> is an extension. 405 406 <STRONG>KEY_RESIZE</STRONG> and <STRONG>has_key</STRONG> are extensions first implemented for <EM>ncurses</EM>. 407 By 2022, <EM>PDCurses</EM> and NetBSD <EM>curses</EM> had added them along with 408 <STRONG>KEY_MOUSE</STRONG>. 409 410 411</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> 412 <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library 413 in its wide-character configuration (<EM>ncursesw</EM>). 414 415 <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>, 416 <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>, 417 <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>, <STRONG>ascii(7)</STRONG> 418 419 ECMA-6 "7-bit coded Character Set" <https://ecma-international.org/ 420 publications-and-standards/standards/ecma-6/> 421 422 ECMA-48 "Control Functions for Coded Character Sets" <https:// 423 ecma-international.org/publications-and-standards/standards/ecma-48/> 424 425 426 427ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> 428</PRE> 429<div class="nav"> 430<ul> 431<li><a href="#h2-NAME">NAME</a></li> 432<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> 433<li><a href="#h2-DESCRIPTION">DESCRIPTION</a> 434<ul> 435<li><a href="#h3-Reading-Characters">Reading Characters</a></li> 436<li><a href="#h3-Keypad-Mode">Keypad Mode</a></li> 437<li><a href="#h3-Ungetting-Characters">Ungetting Characters</a></li> 438<li><a href="#h3-Predefined-Key-Codes">Predefined Key Codes</a></li> 439<li><a href="#h3-Testing-Key-Codes">Testing Key Codes</a></li> 440</ul> 441</li> 442<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> 443<li><a href="#h2-NOTES">NOTES</a></li> 444<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> 445<li><a href="#h2-PORTABILITY">PORTABILITY</a></li> 446<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> 447</ul> 448</div> 449</BODY> 450</HTML> 451