3 ****************************************************************************
4 * Copyright (c) 1998-2015,2016 Free Software Foundation, Inc. *
6 * Permission is hereby granted, free of charge, to any person obtaining a *
7 * copy of this software and associated documentation files (the *
8 * "Software"), to deal in the Software without restriction, including *
9 * without limitation the rights to use, copy, modify, merge, publish, *
10 * distribute, distribute with modifications, sublicense, and/or sell *
11 * copies of the Software, and to permit persons to whom the Software is *
12 * furnished to do so, subject to the following conditions: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 * Except as contained in this notice, the name(s) of the above copyright *
26 * holders shall not be used in advertising or otherwise to promote the *
27 * sale, use or other dealings in this Software without prior written *
29 ****************************************************************************
30 * @Id: curs_getch.3x,v 1.45 2016/05/15 01:05:18 tom Exp @
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
36 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
37 <TITLE>curs_getch 3x</TITLE>
38 <link rev=made href="mailto:bug-ncurses@gnu.org">
39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
42 <H1 class="no-header">curs_getch 3x</H1>
44 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
50 <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, <STRONG>ungetch</STRONG>, <STRONG>has_key</STRONG> - get
51 (or push back) characters from <STRONG>curses</STRONG> terminal keyboard
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
57 <STRONG>int</STRONG> <STRONG>getch(void);</STRONG>
58 <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win);</EM>
59 <STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
60 <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>
61 <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <EM>ch</EM><STRONG>);</STRONG>
62 <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <EM>ch</EM><STRONG>);</STRONG>
65 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
67 </PRE><H3><a name="h3-Reading-characters">Reading characters</a></H3><PRE>
68 The <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG> and <STRONG>mvwgetch</STRONG>, routines read a
69 character from the window. In no-delay mode, if no input
70 is waiting, the value <STRONG>ERR</STRONG> is returned. In delay mode, the
71 program waits until the system passes text through to the
72 program. Depending on the setting of <STRONG>cbreak</STRONG>, this is af-
73 ter one character (cbreak mode), or after the first new-
74 line (nocbreak mode). In half-delay mode, the program
75 waits until a character is typed or the specified timeout
78 If <STRONG>echo</STRONG> is enabled, and the window is not a pad, then the
79 character will also be echoed into the designated window
80 according to the following rules:
82 <STRONG>o</STRONG> If the character is the current erase character, left
83 arrow, or backspace, the cursor is moved one space to
84 the left and that screen position is erased as if
85 <STRONG>delch</STRONG> had been called.
87 <STRONG>o</STRONG> If the character value is any other <STRONG>KEY_</STRONG> define, the
88 user is alerted with a <STRONG>beep</STRONG> call.
90 <STRONG>o</STRONG> If the character is a carriage-return, and if <STRONG>nl</STRONG> is
91 enabled, it is translated to a line-feed after echo-
94 <STRONG>o</STRONG> Otherwise the character is simply output to the
97 If the window is not a pad, and it has been moved or modi-
98 fied since the last call to <STRONG>wrefresh</STRONG>, <STRONG>wrefresh</STRONG> will be
99 called before another character is read.
102 </PRE><H3><a name="h3-Keypad-mode">Keypad mode</a></H3><PRE>
103 If <STRONG>keypad</STRONG> is <STRONG>TRUE</STRONG>, and a function key is pressed, the to-
104 ken for that function key is returned instead of the raw
107 <STRONG>o</STRONG> The predefined function keys are listed in <STRONG><curses.h></STRONG>
108 as macros with values outside the range of 8-bit char-
109 acters. Their names begin with <STRONG>KEY_</STRONG>.
111 <STRONG>o</STRONG> Other (user-defined) function keys which may be de-
112 fined using <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> have no names, but also are
113 expected to have values outside the range of 8-bit
116 Thus, a variable intended to hold the return value of a
117 function key must be of short size or larger.
119 When a character that could be the beginning of a function
120 key is received (which, on modern terminals, means an es-
121 cape character), <STRONG>curses</STRONG> sets a timer. If the remainder of
122 the sequence does not come in within the designated time,
123 the character is passed through; otherwise, the function
124 key value is returned. For this reason, many terminals
125 experience a delay between the time a user presses the es-
126 cape key and the escape is returned to the program.
129 </PRE><H3><a name="h3-Ungetting-characters">Ungetting characters</a></H3><PRE>
130 The <STRONG>ungetch</STRONG> routine places <EM>ch</EM> back onto the input queue to
131 be returned by the next call to <STRONG>wgetch</STRONG>. There is just one
132 input queue for all windows.
135 </PRE><H3><a name="h3-Predefined-key-codes">Predefined key-codes</a></H3><PRE>
136 The following special keys are defined in <STRONG><curses.h></STRONG>.
138 <STRONG>o</STRONG> Except for the special case <STRONG>KEY_RESIZE</STRONG>, it is neces-
139 sary to enable <STRONG>keypad</STRONG> for <STRONG>getch</STRONG> to return these codes.
141 <STRONG>o</STRONG> Not all of these are necessarily supported on any par-
144 <STRONG>o</STRONG> The naming convention may seem obscure, with some ap-
145 parent misspellings (such as "RSUME" for "resume").
146 The names correspond to the long terminfo capability
147 names for the keys, and were defined long ago, in the
150 <EM>Name</EM> <EM>Key</EM> <EM>name</EM>
151 -------------------------------------------------
153 KEY_DOWN The four arrow keys ...
157 KEY_HOME Home key (upward+left arrow)
158 KEY_BACKSPACE Backspace
159 KEY_F0 Function keys; space for 64 keys
161 KEY_F(<EM>n</EM>) For 0 <= <EM>n</EM> <= 63
164 KEY_DC Delete character
165 KEY_IC Insert char or enter insert mode
166 KEY_EIC Exit insert char mode
167 KEY_CLEAR Clear screen
168 KEY_EOS Clear to end of screen
169 KEY_EOL Clear to end of line
170 KEY_SF Scroll 1 line forward
171 KEY_SR Scroll 1 line backward (reverse)
173 KEY_PPAGE Previous page
176 KEY_CATAB Clear all tabs
177 KEY_ENTER Enter or send
178 KEY_SRESET Soft (partial) reset
179 KEY_RESET Reset or hard reset
180 KEY_PRINT Print or copy
181 KEY_LL Home down or bottom (lower left)
183 KEY_A1 Upper left of keypad
184 KEY_A3 Upper right of keypad
185 KEY_B2 Center of keypad
186 KEY_C1 Lower left of keypad
187 KEY_C3 Lower right of keypad
188 KEY_BTAB Back tab key
189 KEY_BEG Beg(inning) key
190 KEY_CANCEL Cancel key
192 KEY_COMMAND Cmd (command) key
194 KEY_CREATE Create key
200 KEY_MESSAGE Message key
201 KEY_MOUSE Mouse event read
203 KEY_NEXT Next object key
205 KEY_OPTIONS Options key
206 KEY_PREVIOUS Previous object key
208 KEY_REFERENCE Ref(erence) key
209 KEY_REFRESH Refresh key
210 KEY_REPLACE Replace key
211 KEY_RESIZE Screen resized
212 KEY_RESTART Restart key
213 KEY_RESUME Resume key
215 KEY_SBEG Shifted beginning key
216 KEY_SCANCEL Shifted cancel key
217 KEY_SCOMMAND Shifted command key
218 KEY_SCOPY Shifted copy key
219 KEY_SCREATE Shifted create key
220 KEY_SDC Shifted delete char key
221 KEY_SDL Shifted delete line key
222 KEY_SELECT Select key
223 KEY_SEND Shifted end key
224 KEY_SEOL Shifted clear line key
225 KEY_SEXIT Shifted exit key
226 KEY_SFIND Shifted find key
227 KEY_SHELP Shifted help key
228 KEY_SHOME Shifted home key
229 KEY_SIC Shifted input key
230 KEY_SLEFT Shifted left arrow key
231 KEY_SMESSAGE Shifted message key
232 KEY_SMOVE Shifted move key
233 KEY_SNEXT Shifted next key
234 KEY_SOPTIONS Shifted options key
235 KEY_SPREVIOUS Shifted prev key
236 KEY_SPRINT Shifted print key
237 KEY_SREDO Shifted redo key
238 KEY_SREPLACE Shifted replace key
239 KEY_SRIGHT Shifted right arrow
240 KEY_SRSUME Shifted resume key
241 KEY_SSAVE Shifted save key
242 KEY_SSUSPEND Shifted suspend key
243 KEY_SUNDO Shifted undo key
244 KEY_SUSPEND Suspend key
247 Keypad is arranged like this:
249 +-----+------+-------+
250 | <STRONG>A1</STRONG> | <STRONG>up</STRONG> | <STRONG>A3</STRONG> |
251 +-----+------+-------+
252 |<STRONG>left</STRONG> | <STRONG>B2</STRONG> | <STRONG>right</STRONG> |
253 +-----+------+-------+
254 | <STRONG>C1</STRONG> | <STRONG>down</STRONG> | <STRONG>C3</STRONG> |
255 +-----+------+-------+
256 A few of these predefined values do <EM>not</EM> correspond to a
259 <STRONG>o</STRONG> <STRONG>KEY_RESIZE</STRONG> is returned when the <STRONG>SIGWINCH</STRONG> signal has
260 been detected (see <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>).
261 This code is returned whether or not <STRONG>keypad</STRONG> has been
264 <STRONG>o</STRONG> <STRONG>KEY_MOUSE</STRONG> is returned for mouse-events (see
265 <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>). This code relies upon whether or not
266 <STRONG><A HREF="keypad.3x.html">keypad(3x)</A></STRONG> has been enabled, because (e.g., with <EM>xterm</EM>
267 mouse prototocol) ncurses must read escape sequences,
268 just like a function key.
271 </PRE><H3><a name="h3-Testing-key-codes">Testing key-codes</a></H3><PRE>
272 The <STRONG>has_key</STRONG> routine takes a key-code value from the above
273 list, and returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG> according to whether the
274 current terminal type recognizes a key with that value.
276 The library also supports these extensions:
278 <STRONG>define_key</STRONG>
279 defines a key-code for a given string (see <STRONG>de-</STRONG>
280 <STRONG><A HREF="define_key.3x.html">fine_key(3x)</A></STRONG>).
282 <STRONG>key_defined</STRONG>
283 checks if there is a key-code defined for a given
284 string (see <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>).
287 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
288 All routines return the integer <STRONG>ERR</STRONG> upon failure and an
289 integer value other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of ungetch())
290 upon successful completion.
292 <STRONG>ungetch</STRONG>
293 returns ERR if there is no more room in the FIFO.
295 <STRONG>wgetch</STRONG>
296 returns ERR if the window pointer is null, or if
297 its timeout expires without having any data.
299 Functions with a "mv" prefix first perform a cursor move-
300 ment using <STRONG>wmove</STRONG>, and return an error if the position is
301 outside the window, or if the window pointer is null.
304 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
305 Use of the escape key by a programmer for a single charac-
306 ter function is discouraged, as it will cause a delay of
307 up to one second while the keypad code looks for a follow-
308 ing function-key sequence.
310 Some keys may be the same as commonly used control keys,
311 e.g., <STRONG>KEY_ENTER</STRONG> versus control/M, <STRONG>KEY_BACKSPACE</STRONG> versus
312 control/H. Some curses implementations may differ accord-
313 ing to whether they treat these control keys specially
314 (and ignore the terminfo), or use the terminfo defini-
315 tions. <STRONG>Ncurses</STRONG> uses the terminfo definition. If it says
316 that <STRONG>KEY_ENTER</STRONG> is control/M, <STRONG>getch</STRONG> will return <STRONG>KEY_ENTER</STRONG>
317 when you press control/M.
319 Generally, <STRONG>KEY_ENTER</STRONG> denotes the character(s) sent by the
320 <EM>Enter</EM> key on the numeric keypad:
322 <STRONG>o</STRONG> the terminal description lists the most useful keys,
324 <STRONG>o</STRONG> the <EM>Enter</EM> key on the regular keyboard is already han-
325 dled by the standard ASCII characters for carriage-re-
328 <STRONG>o</STRONG> depending on whether <STRONG>nl</STRONG> or <STRONG>nonl</STRONG> was called, pressing
329 "Enter" on the regular keyboard may return either a
330 carriage-return or line-feed, and finally
332 <STRONG>o</STRONG> "Enter or send" is the standard description for this
335 When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or <STRONG>mvwgetch</STRONG>, nocbreak
336 mode (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) should not be used at
337 the same time. Depending on the state of the tty driver
338 when each character is typed, the program may produce un-
341 Note that <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be macros.
343 Historically, the set of keypad macros was largely defined
344 by the extremely function-key-rich keyboard of the AT&T
345 7300, aka 3B1, aka Safari 4. Modern personal computers
346 usually have only a small subset of these. IBM PC-style
347 consoles typically support little more than <STRONG>KEY_UP</STRONG>,
348 <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>,
349 <STRONG>KEY_NPAGE</STRONG>, <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12. The
350 Ins key is usually mapped to <STRONG>KEY_IC</STRONG>.
353 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
354 The *get* functions are described in the XSI Curses stan-
355 dard, Issue 4. They read single-byte characters only.
356 The standard specifies that they return <STRONG>ERR</STRONG> on failure,
357 but specifies no error conditions.
359 The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or
360 backspace characters was not specified in the SVr4 docu-
361 mentation. This description is adopted from the XSI Curs-
364 The behavior of <STRONG>getch</STRONG> and friends in the presence of han-
365 dled signals is unspecified in the SVr4 and XSI Curses
366 documentation. Under historical curses implementations,
367 it varied depending on whether the operating system's im-
368 plementation of handled signal receipt interrupts a
369 <STRONG>read(2)</STRONG> call in progress or not, and also (in some imple-
370 mentations) depending on whether an input timeout or non-
371 blocking mode has been set.
373 <STRONG>KEY_MOUSE</STRONG> is mentioned in XSI Curses, along with a few re-
374 lated terminfo capabilities, but no higher-level functions
375 use the feature. The implementation in ncurses is an ex-
378 <STRONG>KEY_RESIZE</STRONG> is an extension first implemented for ncurses.
379 NetBSD curses later added this extension.
381 Programmers concerned about portability should be prepared
382 for either of two cases: (a) signal receipt does not in-
383 terrupt <STRONG>getch</STRONG>; (b) signal receipt interrupts <STRONG>getch</STRONG> and
384 causes it to return ERR with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. Under
385 the <STRONG>ncurses</STRONG> implementation, handled signals never inter-
386 rupt <STRONG>getch</STRONG>.
388 The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>. We recommend
389 that any code using it be conditionalized on the <STRONG>NCURS-</STRONG>
390 <STRONG>ES_VERSION</STRONG> feature macro.
393 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
394 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>,
395 <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_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG>re-</STRONG>
396 <STRONG><A HREF="resizeterm.3x.html">sizeterm(3x)</A></STRONG>.
398 Comparable functions in the wide-character (ncursesw) li-
399 brary are described in <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>.
403 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
407 <li><a href="#h2-NAME">NAME</a></li>
408 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
409 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
411 <li><a href="#h3-Reading-characters">Reading characters</a></li>
412 <li><a href="#h3-Keypad-mode">Keypad mode</a></li>
413 <li><a href="#h3-Ungetting-characters">Ungetting characters</a></li>
414 <li><a href="#h3-Predefined-key-codes">Predefined key-codes</a></li>
415 <li><a href="#h3-Testing-key-codes">Testing key-codes</a></li>
418 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
419 <li><a href="#h2-NOTES">NOTES</a></li>
420 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
421 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>