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.47 2016/06/11 22:56:33 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.
128 In <STRONG>ncurses</STRONG>, the timer normally expires after the value in
129 <STRONG>ESCDELAY</STRONG> (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>). If <STRONG>notimeout</STRONG> is <STRONG>TRUE</STRONG>,
130 the timer does not expire; it is an infinite (or very
131 large) value. Because function keys usually begin with an
132 escape character, the terminal may appear to hang in no-
133 timeout mode after pressing the escape key until another
137 </PRE><H3><a name="h3-Ungetting-characters">Ungetting characters</a></H3><PRE>
138 The <STRONG>ungetch</STRONG> routine places <EM>ch</EM> back onto the input queue to
139 be returned by the next call to <STRONG>wgetch</STRONG>. There is just one
140 input queue for all windows.
143 </PRE><H3><a name="h3-Predefined-key-codes">Predefined key-codes</a></H3><PRE>
144 The following special keys are defined in <STRONG><curses.h></STRONG>.
146 <STRONG>o</STRONG> Except for the special case <STRONG>KEY_RESIZE</STRONG>, it is neces-
147 sary to enable <STRONG>keypad</STRONG> for <STRONG>getch</STRONG> to return these codes.
149 <STRONG>o</STRONG> Not all of these are necessarily supported on any par-
152 <STRONG>o</STRONG> The naming convention may seem obscure, with some ap-
153 parent misspellings (such as "RSUME" for "resume").
154 The names correspond to the long terminfo capability
155 names for the keys, and were defined long ago, in the
158 <EM>Name</EM> <EM>Key</EM> <EM>name</EM>
159 -------------------------------------------------
161 KEY_DOWN The four arrow keys ...
165 KEY_HOME Home key (upward+left arrow)
166 KEY_BACKSPACE Backspace
167 KEY_F0 Function keys; space for 64 keys
169 KEY_F(<EM>n</EM>) For 0 <= <EM>n</EM> <= 63
172 KEY_DC Delete character
173 KEY_IC Insert char or enter insert mode
174 KEY_EIC Exit insert char mode
175 KEY_CLEAR Clear screen
176 KEY_EOS Clear to end of screen
177 KEY_EOL Clear to end of line
178 KEY_SF Scroll 1 line forward
179 KEY_SR Scroll 1 line backward (reverse)
181 KEY_PPAGE Previous page
185 KEY_CATAB Clear all tabs
186 KEY_ENTER Enter or send
187 KEY_SRESET Soft (partial) reset
188 KEY_RESET Reset or hard reset
189 KEY_PRINT Print or copy
190 KEY_LL Home down or bottom (lower left)
191 KEY_A1 Upper left of keypad
192 KEY_A3 Upper right of keypad
193 KEY_B2 Center of keypad
194 KEY_C1 Lower left of keypad
195 KEY_C3 Lower right of keypad
196 KEY_BTAB Back tab key
197 KEY_BEG Beg(inning) key
198 KEY_CANCEL Cancel key
200 KEY_COMMAND Cmd (command) key
202 KEY_CREATE Create key
208 KEY_MESSAGE Message key
209 KEY_MOUSE Mouse event read
211 KEY_NEXT Next object key
213 KEY_OPTIONS Options key
214 KEY_PREVIOUS Previous object key
216 KEY_REFERENCE Ref(erence) key
217 KEY_REFRESH Refresh key
218 KEY_REPLACE Replace key
219 KEY_RESIZE Screen resized
220 KEY_RESTART Restart key
221 KEY_RESUME Resume key
223 KEY_SBEG Shifted beginning key
224 KEY_SCANCEL Shifted cancel key
225 KEY_SCOMMAND Shifted command key
226 KEY_SCOPY Shifted copy key
227 KEY_SCREATE Shifted create key
228 KEY_SDC Shifted delete char key
229 KEY_SDL Shifted delete line key
230 KEY_SELECT Select key
231 KEY_SEND Shifted end key
232 KEY_SEOL Shifted clear line key
233 KEY_SEXIT Shifted exit key
234 KEY_SFIND Shifted find key
235 KEY_SHELP Shifted help key
236 KEY_SHOME Shifted home key
237 KEY_SIC Shifted input key
238 KEY_SLEFT Shifted left arrow key
239 KEY_SMESSAGE Shifted message key
240 KEY_SMOVE Shifted move key
241 KEY_SNEXT Shifted next key
242 KEY_SOPTIONS Shifted options key
243 KEY_SPREVIOUS Shifted prev key
244 KEY_SPRINT Shifted print key
245 KEY_SREDO Shifted redo key
246 KEY_SREPLACE Shifted replace key
247 KEY_SRIGHT Shifted right arrow
249 KEY_SRSUME Shifted resume key
250 KEY_SSAVE Shifted save key
251 KEY_SSUSPEND Shifted suspend key
252 KEY_SUNDO Shifted undo key
253 KEY_SUSPEND Suspend key
256 Keypad is arranged like this:
258 +-----+------+-------+
259 | <STRONG>A1</STRONG> | <STRONG>up</STRONG> | <STRONG>A3</STRONG> |
260 +-----+------+-------+
261 |<STRONG>left</STRONG> | <STRONG>B2</STRONG> | <STRONG>right</STRONG> |
262 +-----+------+-------+
263 | <STRONG>C1</STRONG> | <STRONG>down</STRONG> | <STRONG>C3</STRONG> |
264 +-----+------+-------+
265 A few of these predefined values do <EM>not</EM> correspond to a
268 <STRONG>o</STRONG> <STRONG>KEY_RESIZE</STRONG> is returned when the <STRONG>SIGWINCH</STRONG> signal has
269 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>).
270 This code is returned whether or not <STRONG>keypad</STRONG> has been
273 <STRONG>o</STRONG> <STRONG>KEY_MOUSE</STRONG> is returned for mouse-events (see
274 <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>). This code relies upon whether or not
275 <STRONG><A HREF="keypad.3x.html">keypad(3x)</A></STRONG> has been enabled, because (e.g., with <EM>xterm</EM>
276 mouse prototocol) ncurses must read escape sequences,
277 just like a function key.
280 </PRE><H3><a name="h3-Testing-key-codes">Testing key-codes</a></H3><PRE>
281 The <STRONG>has_key</STRONG> routine takes a key-code value from the above
282 list, and returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG> according to whether the
283 current terminal type recognizes a key with that value.
285 The library also supports these extensions:
287 <STRONG>define_key</STRONG>
288 defines a key-code for a given string (see <STRONG>de-</STRONG>
289 <STRONG><A HREF="define_key.3x.html">fine_key(3x)</A></STRONG>).
291 <STRONG>key_defined</STRONG>
292 checks if there is a key-code defined for a given
293 string (see <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>).
296 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
297 All routines return the integer <STRONG>ERR</STRONG> upon failure and an
298 integer value other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of ungetch())
299 upon successful completion.
301 <STRONG>ungetch</STRONG>
302 returns ERR if there is no more room in the FIFO.
304 <STRONG>wgetch</STRONG>
305 returns ERR if the window pointer is null, or if
306 its timeout expires without having any data.
308 Functions with a "mv" prefix first perform a cursor move-
309 ment using <STRONG>wmove</STRONG>, and return an error if the position is
310 outside the window, or if the window pointer is null.
313 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
314 Use of the escape key by a programmer for a single charac-
315 ter function is discouraged, as it will cause a delay of
316 up to one second while the keypad code looks for a follow-
317 ing function-key sequence.
319 Some keys may be the same as commonly used control keys,
320 e.g., <STRONG>KEY_ENTER</STRONG> versus control/M, <STRONG>KEY_BACKSPACE</STRONG> versus
321 control/H. Some curses implementations may differ accord-
322 ing to whether they treat these control keys specially
323 (and ignore the terminfo), or use the terminfo defini-
324 tions. <STRONG>Ncurses</STRONG> uses the terminfo definition. If it says
325 that <STRONG>KEY_ENTER</STRONG> is control/M, <STRONG>getch</STRONG> will return <STRONG>KEY_ENTER</STRONG>
326 when you press control/M.
328 Generally, <STRONG>KEY_ENTER</STRONG> denotes the character(s) sent by the
329 <EM>Enter</EM> key on the numeric keypad:
331 <STRONG>o</STRONG> the terminal description lists the most useful keys,
333 <STRONG>o</STRONG> the <EM>Enter</EM> key on the regular keyboard is already han-
334 dled by the standard ASCII characters for carriage-re-
337 <STRONG>o</STRONG> depending on whether <STRONG>nl</STRONG> or <STRONG>nonl</STRONG> was called, pressing
338 "Enter" on the regular keyboard may return either a
339 carriage-return or line-feed, and finally
341 <STRONG>o</STRONG> "Enter or send" is the standard description for this
344 When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or <STRONG>mvwgetch</STRONG>, nocbreak
345 mode (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) should not be used at
346 the same time. Depending on the state of the tty driver
347 when each character is typed, the program may produce un-
350 Note that <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be macros.
352 Historically, the set of keypad macros was largely defined
353 by the extremely function-key-rich keyboard of the AT&T
354 7300, aka 3B1, aka Safari 4. Modern personal computers
355 usually have only a small subset of these. IBM PC-style
356 consoles typically support little more than <STRONG>KEY_UP</STRONG>,
357 <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>,
358 <STRONG>KEY_NPAGE</STRONG>, <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12. The
359 Ins key is usually mapped to <STRONG>KEY_IC</STRONG>.
362 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
363 The *get* functions are described in the XSI Curses stan-
364 dard, Issue 4. They read single-byte characters only.
365 The standard specifies that they return <STRONG>ERR</STRONG> on failure,
366 but specifies no error conditions.
368 The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or
369 backspace characters was not specified in the SVr4 docu-
370 mentation. This description is adopted from the XSI Curs-
373 The behavior of <STRONG>getch</STRONG> and friends in the presence of han-
374 dled signals is unspecified in the SVr4 and XSI Curses
375 documentation. Under historical curses implementations,
376 it varied depending on whether the operating system's im-
377 plementation of handled signal receipt interrupts a
378 <STRONG>read(2)</STRONG> call in progress or not, and also (in some imple-
379 mentations) depending on whether an input timeout or non-
380 blocking mode has been set.
382 <STRONG>KEY_MOUSE</STRONG> is mentioned in XSI Curses, along with a few re-
383 lated terminfo capabilities, but no higher-level functions
384 use the feature. The implementation in ncurses is an ex-
387 <STRONG>KEY_RESIZE</STRONG> is an extension first implemented for ncurses.
388 NetBSD curses later added this extension.
390 Programmers concerned about portability should be prepared
391 for either of two cases: (a) signal receipt does not in-
392 terrupt <STRONG>getch</STRONG>; (b) signal receipt interrupts <STRONG>getch</STRONG> and
393 causes it to return ERR with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. Under
394 the <STRONG>ncurses</STRONG> implementation, handled signals never inter-
395 rupt <STRONG>getch</STRONG>.
397 The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>. We recommend
398 that any code using it be conditionalized on the <STRONG>NCURS-</STRONG>
399 <STRONG>ES_VERSION</STRONG> feature macro.
402 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
403 <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>,
404 <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>,
405 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>.
407 Comparable functions in the wide-character (ncursesw) li-
408 brary are described in <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>.
412 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
416 <li><a href="#h2-NAME">NAME</a></li>
417 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
418 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
420 <li><a href="#h3-Reading-characters">Reading characters</a></li>
421 <li><a href="#h3-Keypad-mode">Keypad mode</a></li>
422 <li><a href="#h3-Ungetting-characters">Ungetting characters</a></li>
423 <li><a href="#h3-Predefined-key-codes">Predefined key-codes</a></li>
424 <li><a href="#h3-Testing-key-codes">Testing key-codes</a></li>
427 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
428 <li><a href="#h2-NOTES">NOTES</a></li>
429 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
430 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>