1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
4 ****************************************************************************
5 * Copyright (c) 1998-2012,2014 Free Software Foundation, Inc. *
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: *
15 * The above copyright notice and this permission notice shall be included *
16 * in all copies or substantial portions of the Software. *
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. *
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 *
30 ****************************************************************************
31 * @Id: curs_getch.3x,v 1.39 2014/05/24 20:16:31 tom Exp @
35 <TITLE>curs_getch 3x</TITLE>
36 <link rev=made href="mailto:bug-ncurses@gnu.org">
37 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
40 <H1>curs_getch 3x</H1>
43 <!-- Manpage converted by man2html 3.0.1 -->
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>
51 <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, <STRONG>ungetch</STRONG>, <STRONG>has_key</STRONG> - get
52 (or push back) characters from <STRONG>curses</STRONG> terminal keyboard
56 <H2>SYNOPSIS</H2><PRE>
57 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
59 <STRONG>int</STRONG> <STRONG>getch(void);</STRONG>
60 <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*win);</STRONG>
61 <STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
62 <STRONG>int</STRONG> <STRONG>mvwgetch(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
63 <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <STRONG>ch);</STRONG>
64 <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <STRONG>ch);</STRONG>
68 <H2>DESCRIPTION</H2><PRE>
69 The <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG> and <STRONG>mvwgetch</STRONG>, routines read a
70 character from the window. In no-delay mode, if no input
71 is waiting, the value <STRONG>ERR</STRONG> is returned. In delay mode, the
72 program waits until the system passes text through to the
73 program. Depending on the setting of <STRONG>cbreak</STRONG>, this is af-
74 ter one character (cbreak mode), or after the first new-
75 line (nocbreak mode). In half-delay mode, the program
76 waits until a character is typed or the specified timeout
79 If <STRONG>echo</STRONG> is enabled, and the window is not a pad, then the
80 character will also be echoed into the designated window
81 according to the following rules:
83 <STRONG>o</STRONG> If the character is the current erase character, left
84 arrow, or backspace, the cursor is moved one space to
85 the left and that screen position is erased as if
86 <STRONG>delch</STRONG> had been called.
88 <STRONG>o</STRONG> If the character value is any other <STRONG>KEY_</STRONG> define, the
89 user is alerted with a <STRONG>beep</STRONG> call.
91 <STRONG>o</STRONG> If the character is a carriage-return, and if <STRONG>nl</STRONG> is
92 enabled, it is translated to a line-feed after echo-
95 <STRONG>o</STRONG> Otherwise the character is simply output to the
98 If the window is not a pad, and it has been moved or modi-
99 fied since the last call to <STRONG>wrefresh</STRONG>, <STRONG>wrefresh</STRONG> will be
100 called before another character is read.
102 If <STRONG>keypad</STRONG> is <STRONG>TRUE</STRONG>, and a function key is pressed, the to-
103 ken for that function key is returned instead of the raw
104 characters. Possible function keys are defined in <STRONG><curs-</STRONG>
105 <STRONG>es.h></STRONG> as macros with values outside the range of 8-bit
106 characters whose names begin with <STRONG>KEY_</STRONG>. Thus, a variable
107 intended to hold the return value of a function key must
108 be of short size or larger.
110 When a character that could be the beginning of a function
111 key is received (which, on modern terminals, means an es-
112 cape character), <STRONG>curses</STRONG> sets a timer. If the remainder of
113 the sequence does not come in within the designated time,
114 the character is passed through; otherwise, the function
115 key value is returned. For this reason, many terminals
116 experience a delay between the time a user presses the es-
117 cape key and the escape is returned to the program.
119 The <STRONG>ungetch</STRONG> routine places <EM>ch</EM> back onto the input queue to
120 be returned by the next call to <STRONG>wgetch</STRONG>. There is just one
121 input queue for all windows.
123 <STRONG>Function</STRONG> <STRONG>Keys</STRONG>
124 The following function keys, defined in <STRONG><curses.h></STRONG>, might
125 be returned by <STRONG>getch</STRONG> if <STRONG>keypad</STRONG> has been enabled. Note
126 that not all of these are necessarily supported on any
129 <EM>Name</EM> <EM>Key</EM> <EM>name</EM>
130 -------------------------------------------------
132 KEY_DOWN The four arrow keys ...
136 KEY_HOME Home key (upward+left arrow)
137 KEY_BACKSPACE Backspace
138 KEY_F0 Function keys; space for 64 keys
140 KEY_F(<EM>n</EM>) For 0 <= <EM>n</EM> <= 63
143 KEY_DC Delete character
144 KEY_IC Insert char or enter insert mode
145 KEY_EIC Exit insert char mode
146 KEY_CLEAR Clear screen
147 KEY_EOS Clear to end of screen
148 KEY_EOL Clear to end of line
149 KEY_SF Scroll 1 line forward
150 KEY_SR Scroll 1 line backward (reverse)
152 KEY_PPAGE Previous page
155 KEY_CATAB Clear all tabs
156 KEY_ENTER Enter or send
157 KEY_SRESET Soft (partial) reset
158 KEY_RESET Reset or hard reset
159 KEY_PRINT Print or copy
160 KEY_LL Home down or bottom (lower left)
161 KEY_A1 Upper left of keypad
162 KEY_A3 Upper right of keypad
163 KEY_B2 Center of keypad
164 KEY_C1 Lower left of keypad
165 KEY_C3 Lower right of keypad
166 KEY_BTAB Back tab key
167 KEY_BEG Beg(inning) key
168 KEY_CANCEL Cancel key
170 KEY_COMMAND Cmd (command) key
172 KEY_CREATE Create key
178 KEY_MESSAGE Message key
179 KEY_MOUSE Mouse event read
182 KEY_NEXT Next object key
184 KEY_OPTIONS Options key
185 KEY_PREVIOUS Previous object key
187 KEY_REFERENCE Ref(erence) key
188 KEY_REFRESH Refresh key
189 KEY_REPLACE Replace key
190 KEY_RESIZE Screen resized
191 KEY_RESTART Restart key
192 KEY_RESUME Resume key
194 KEY_SBEG Shifted beginning key
195 KEY_SCANCEL Shifted cancel key
196 KEY_SCOMMAND Shifted command key
197 KEY_SCOPY Shifted copy key
198 KEY_SCREATE Shifted create key
199 KEY_SDC Shifted delete char key
200 KEY_SDL Shifted delete line key
201 KEY_SELECT Select key
202 KEY_SEND Shifted end key
203 KEY_SEOL Shifted clear line key
204 KEY_SEXIT Shifted exit key
205 KEY_SFIND Shifted find key
206 KEY_SHELP Shifted help key
207 KEY_SHOME Shifted home key
208 KEY_SIC Shifted input key
209 KEY_SLEFT Shifted left arrow key
210 KEY_SMESSAGE Shifted message key
211 KEY_SMOVE Shifted move key
212 KEY_SNEXT Shifted next key
213 KEY_SOPTIONS Shifted options key
214 KEY_SPREVIOUS Shifted prev key
215 KEY_SPRINT Shifted print key
216 KEY_SREDO Shifted redo key
217 KEY_SREPLACE Shifted replace key
218 KEY_SRIGHT Shifted right arrow
219 KEY_SRSUME Shifted resume key
220 KEY_SSAVE Shifted save key
221 KEY_SSUSPEND Shifted suspend key
222 KEY_SUNDO Shifted undo key
223 KEY_SUSPEND Suspend key
226 Keypad is arranged like this:
229 +-----+------+-------+
230 | <STRONG>A1</STRONG> | <STRONG>up</STRONG> | <STRONG>A3</STRONG> |
231 +-----+------+-------+
232 |<STRONG>left</STRONG> | <STRONG>B2</STRONG> | <STRONG>right</STRONG> |
233 +-----+------+-------+
234 | <STRONG>C1</STRONG> | <STRONG>down</STRONG> | <STRONG>C3</STRONG> |
235 +-----+------+-------+
236 The <STRONG>has_key</STRONG> routine takes a key value from the above list,
237 and returns TRUE or FALSE according to whether the current
238 terminal type recognizes a key with that value. Note that
239 a few values do not correspond to a real key, e.g.,
240 <STRONG>KEY_RESIZE</STRONG> and <STRONG>KEY_MOUSE</STRONG>. See <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> for more de-
241 tails about <STRONG>KEY_RESIZE</STRONG>, and <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> for a discus-
242 sion of <STRONG>KEY_MOUSE</STRONG>.
246 <H2>RETURN VALUE</H2><PRE>
247 All routines return the integer <STRONG>ERR</STRONG> upon failure and an
248 integer value other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of ungetch())
249 upon successful completion.
251 <STRONG>ungetch</STRONG>
252 returns ERR if there is no more room in the FIFO.
254 <STRONG>wgetch</STRONG>
255 returns ERR if the window pointer is null, or if
256 its timeout expires without having any data.
258 Functions with a "mv" prefix first perform a cursor move-
259 ment using <STRONG>wmove</STRONG>, and return an error if the position is
260 outside the window, or if the window pointer is null.
265 Use of the escape key by a programmer for a single charac-
266 ter function is discouraged, as it will cause a delay of
267 up to one second while the keypad code looks for a follow-
268 ing function-key sequence.
270 Note that some keys may be the same as commonly used con-
271 trol keys, e.g., <STRONG>KEY_ENTER</STRONG> versus control/M, <STRONG>KEY_BACKSPACE</STRONG>
272 versus control/H. Some curses implementations may differ
273 according to whether they treat these control keys spe-
274 cially (and ignore the terminfo), or use the terminfo def-
275 initions. <STRONG>Ncurses</STRONG> uses the terminfo definition. If it
276 says that <STRONG>KEY_ENTER</STRONG> is control/M, <STRONG>getch</STRONG> will return
277 <STRONG>KEY_ENTER</STRONG> when you press control/M.
279 Generally, <STRONG>KEY_ENTER</STRONG> denotes the character(s) sent by the
280 <EM>Enter</EM> key on the numeric keypad:
282 <STRONG>o</STRONG> the terminal description lists the most useful keys,
284 <STRONG>o</STRONG> the <EM>Enter</EM> key on the regular keyboard is already han-
285 dled by the standard ASCII characters for carriage-re-
288 <STRONG>o</STRONG> depending on whether <STRONG>nl</STRONG> or <STRONG>nonl</STRONG> was called, pressing
289 "Enter" on the regular keyboard may return either a
290 carriage-return or line-feed, and finally
292 <STRONG>o</STRONG> "Enter or send" is the standard description for this
295 When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or <STRONG>mvwgetch</STRONG>, nocbreak
296 mode (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) should not be used at
297 the same time. Depending on the state of the tty driver
298 when each character is typed, the program may produce un-
301 Note that <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be macros.
303 Historically, the set of keypad macros was largely defined
304 by the extremely function-key-rich keyboard of the AT&T
305 7300, aka 3B1, aka Safari 4. Modern personal computers
306 usually have only a small subset of these. IBM PC-style
307 consoles typically support little more than <STRONG>KEY_UP</STRONG>,
308 <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>,
309 <STRONG>KEY_NPAGE</STRONG>, <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12. The
310 Ins key is usually mapped to <STRONG>KEY_IC</STRONG>.
314 <H2>PORTABILITY</H2><PRE>
315 The *get* functions are described in the XSI Curses stan-
316 dard, Issue 4. They read single-byte characters only.
317 The standard specifies that they return <STRONG>ERR</STRONG> on failure,
318 but specifies no error conditions.
320 The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or
321 backspace characters was not specified in the SVr4 docu-
322 mentation. This description is adopted from the XSI Curs-
325 The behavior of <STRONG>getch</STRONG> and friends in the presence of han-
326 dled signals is unspecified in the SVr4 and XSI Curses
327 documentation. Under historical curses implementations,
328 it varied depending on whether the operating system's im-
329 plementation of handled signal receipt interrupts a
330 <STRONG>read(2)</STRONG> call in progress or not, and also (in some imple-
331 mentations) depending on whether an input timeout or non-
332 blocking mode has been set.
334 Programmers concerned about portability should be prepared
335 for either of two cases: (a) signal receipt does not in-
336 terrupt <STRONG>getch</STRONG>; (b) signal receipt interrupts <STRONG>getch</STRONG> and
337 causes it to return ERR with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. Under
338 the <STRONG>ncurses</STRONG> implementation, handled signals never inter-
339 rupt <STRONG>getch</STRONG>.
341 The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>. We recommend
342 that any code using it be conditionalized on the <STRONG>NCURS-</STRONG>
343 <STRONG>ES_VERSION</STRONG> feature macro.
347 <H2>SEE ALSO</H2><PRE>
348 <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>,
349 <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>
350 <STRONG><A HREF="resizeterm.3x.html">sizeterm(3x)</A></STRONG>.
352 Comparable functions in the wide-character (ncursesw) li-
353 brary are described in <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>.
357 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
361 Man(1) output converted with
362 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>