1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
4 ****************************************************************************
5 * Copyright (c) 1998-2001,2002 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.21 2002/03/17 14:36:21 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 -->
47 <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, <STRONG>ungetch</STRONG>, <STRONG>has_key</STRONG> - get
48 (or push back) characters from <STRONG>curses</STRONG> terminal keyboard
52 <H2>SYNOPSIS</H2><PRE>
53 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
55 <STRONG>int</STRONG> <STRONG>getch(void);</STRONG>
56 <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*win);</STRONG>
57 <STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
58 <STRONG>int</STRONG> <STRONG>mvwgetch(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
59 <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <STRONG>ch);</STRONG>
60 <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <STRONG>ch);</STRONG>
64 <H2>DESCRIPTION</H2><PRE>
65 The <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG> and <STRONG>mvwgetch</STRONG>, routines read a
66 character from the window. In no-delay mode, if no input
67 is waiting, the value <STRONG>ERR</STRONG> is returned. In delay mode, the
68 program waits until the system passes text through to the
69 program. Depending on the setting of <STRONG>cbreak</STRONG>, this is
70 after one character (cbreak mode), or after the first new-
71 line (nocbreak mode). In half-delay mode, the program
72 waits until a character is typed or the specified timeout
75 Unless <STRONG>noecho</STRONG> has been set, then the character will also
76 be echoed into the designated window according to the fol-
77 lowing rules: If the character is the current erase char-
78 acter, left arrow, or backspace, the cursor is moved one
79 space to the left and that screen position is erased as if
80 <STRONG>delch</STRONG> had been called. If the character value is any
81 other <STRONG>KEY_</STRONG> define, the user is alerted with a <STRONG>beep</STRONG> call.
82 Otherwise the character is simply output to the screen.
84 If the window is not a pad, and it has been moved or modi-
85 fied since the last call to <STRONG>wrefresh</STRONG>, <STRONG>wrefresh</STRONG> will be
86 called before another character is read.
88 If <STRONG>keypad</STRONG> is <STRONG>TRUE</STRONG>, and a function key is pressed, the
89 token for that function key is returned instead of the raw
90 characters. Possible function keys are defined in
91 <STRONG><curses.h></STRONG> as macros with values outside the range of
92 8-bit characters whose names begin with <STRONG>KEY_.</STRONG> Thus, a
93 variable intended to hold the return value of a function
94 key must be of short size or larger.
96 When a character that could be the beginning of a function
97 key is received (which, on modern terminals, means an
98 escape character), <STRONG>curses</STRONG> sets a timer. If the remainder
99 of the sequence does not come in within the designated
100 time, the character is passed through; otherwise, the
101 function key value is returned. For this reason, many
102 terminals experience a delay between the time a user
103 presses the escape key and the escape is returned to the
106 The <STRONG>ungetch</STRONG> routine places <EM>ch</EM> back onto the input queue to
107 be returned by the next call to <STRONG>wgetch</STRONG>. There is just one
108 input queue for all windows.
111 <STRONG>Function</STRONG> <STRONG>Keys</STRONG>
112 The following function keys, defined in <STRONG><curses.h></STRONG>, might
113 be returned by <STRONG>getch</STRONG> if <STRONG>keypad</STRONG> has been enabled. Note
114 that not all of these are necessarily supported on any
117 <EM>Name</EM> <EM>Key</EM> <EM>name</EM>
120 KEY_DOWN The four arrow keys ...
124 KEY_HOME Home key (upward+left arrow)
125 KEY_BACKSPACE Backspace
126 KEY_F0 Function keys; space for 64 keys
128 KEY_F(<EM>n</EM>) For 0 <= <EM>n</EM> <= 63
131 KEY_DC Delete character
132 KEY_IC Insert char or enter insert mode
133 KEY_EIC Exit insert char mode
134 KEY_CLEAR Clear screen
135 KEY_EOS Clear to end of screen
136 KEY_EOL Clear to end of line
137 KEY_SF Scroll 1 line forward
138 KEY_SR Scroll 1 line backward (reverse)
140 KEY_PPAGE Previous page
143 KEY_CATAB Clear all tabs
144 KEY_ENTER Enter or send
145 KEY_SRESET Soft (partial) reset
146 KEY_RESET Reset or hard reset
147 KEY_PRINT Print or copy
148 KEY_LL Home down or bottom (lower left).
149 KEY_A1 Upper left of keypad
150 KEY_A3 Upper right of keypad
151 KEY_B2 Center of keypad
152 KEY_C1 Lower left of keypad
153 KEY_C3 Lower right of keypad
154 KEY_BTAB Back tab key
155 KEY_BEG Beg(inning) key
156 KEY_CANCEL Cancel key
159 KEY_COMMAND Cmd (command) key
161 KEY_CREATE Create key
167 KEY_MESSAGE Message key
168 KEY_MOUSE Mouse event read
170 KEY_NEXT Next object key
172 KEY_OPTIONS Options key
173 KEY_PREVIOUS Previous object key
175 KEY_REFERENCE Ref(erence) key
176 KEY_REFRESH Refresh key
177 KEY_REPLACE Replace key
178 KEY_RESIZE Screen resized
179 KEY_RESTART Restart key
180 KEY_RESUME Resume key
182 KEY_SBEG Shifted beginning key
183 KEY_SCANCEL Shifted cancel key
184 KEY_SCOMMAND Shifted command key
185 KEY_SCOPY Shifted copy key
186 KEY_SCREATE Shifted create key
187 KEY_SDC Shifted delete char key
188 KEY_SDL Shifted delete line key
189 KEY_SELECT Select key
190 KEY_SEND Shifted end key
191 KEY_SEOL Shifted clear line key
192 KEY_SEXIT Shifted exit key
193 KEY_SFIND Shifted find key
194 KEY_SHELP Shifted help key
195 KEY_SHOME Shifted home key
196 KEY_SIC Shifted input key
197 KEY_SLEFT Shifted left arrow key
198 KEY_SMESSAGE Shifted message key
199 KEY_SMOVE Shifted move key
200 KEY_SNEXT Shifted next key
201 KEY_SOPTIONS Shifted options key
202 KEY_SPREVIOUS Shifted prev key
203 KEY_SPRINT Shifted print key
204 KEY_SREDO Shifted redo key
205 KEY_SREPLACE Shifted replace key
206 KEY_SRIGHT Shifted right arrow
207 KEY_SRSUME Shifted resume key
208 KEY_SSAVE Shifted save key
209 KEY_SSUSPEND Shifted suspend key
210 KEY_SUNDO Shifted undo key
212 KEY_SUSPEND Suspend key
215 Keypad is arranged like this:
217 +-----+------+-------+
218 | <STRONG>A1</STRONG> | <STRONG>up</STRONG> | <STRONG>A3</STRONG> |
219 +-----+------+-------+
220 |<STRONG>left</STRONG> | <STRONG>B2</STRONG> | <STRONG>right</STRONG> |
221 +-----+------+-------+
222 | <STRONG>C1</STRONG> | <STRONG>down</STRONG> | <STRONG>C3</STRONG> |
223 +-----+------+-------+
224 The <STRONG>has_key</STRONG> routine takes a key value from the above list,
225 and returns TRUE or FALSE according to whether the current
226 terminal type recognizes a key with that value.
231 <H2>RETURN VALUE</H2><PRE>
232 All routines return the integer <STRONG>ERR</STRONG> upon failure and an
233 integer value other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of ungetch())
234 upon successful completion.
239 Use of the escape key by a programmer for a single charac-
240 ter function is discouraged, as it will cause a delay of
241 up to one second while the keypad code looks for a follow-
242 ing function-key sequence.
244 Note that some keys may be the same as commonly used con-
245 trol keys, e.g., KEY_ENTER versus control/M, KEY_BACKSPACE
246 versus control/H. Some curses implementations may differ
247 according to whether they treat these control keys spe-
248 cially (and ignore the terminfo), or use the terminfo def-
249 initions. <STRONG>Ncurses</STRONG> uses the terminfo definition. If it
250 says that KEY_ENTER is control/M, <STRONG>getch</STRONG>, will return
251 KEY_ENTER when you press control/M.
253 When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or <STRONG>mvwgetch</STRONG>, nocbreak
254 mode (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) should not be used at
255 the same time. Depending on the state of the tty driver
256 when each character is typed, the program may produce
259 Note that <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be macros.
261 Historically, the set of keypad macros was largely defined
262 by the extremely function-key-rich keyboard of the AT&T
263 7300, aka 3B1, aka Safari 4. Modern personal computers
264 usually have only a small subset of these. IBM PC-style
265 consoles typically support little more than <STRONG>KEY_UP</STRONG>,
266 <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>,
267 <STRONG>KEY_NPAGE</STRONG>, <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12. The
268 Ins key is usually mapped to <STRONG>KEY_IC</STRONG>.
272 <H2>PORTABILITY</H2><PRE>
273 The *get* functions are described in the XSI Curses stan-
274 dard, Issue 4. They read single-byte characters only.
275 The standard specifies that they return <STRONG>ERR</STRONG> on failure,
276 but specifies no error conditions.
278 The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or
279 backspace characters was not specified in the SVr4 docu-
280 mentation. This description is adopted from the XSI
283 The behavior of <STRONG>getch</STRONG> and friends in the presence of han-
284 dled signals is unspecified in the SVr4 and XSI Curses
285 documentation. Under historical curses implementations,
286 it varied depending on whether the operating system's
287 implementation of handled signal receipt interrupts a
288 <STRONG><A HREF="read.2.html">read(2)</A></STRONG> call in progress or not, and also (in some imple-
289 mentations) depending on whether an input timeout or non-
290 blocking mode hsd been set.
292 Programmers concerned about portability should be prepared
293 for either of two cases: (a) signal receipt does not
294 interrupt <STRONG>getch</STRONG>; (b) signal receipt interrupts <STRONG>getch</STRONG> and
295 causes it to return ERR with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. Under
296 the <STRONG>ncurses</STRONG> implementation, handled signals never inter-
297 rupt <STRONG>getch</STRONG>.
299 The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>. We recommend
300 that any code using it be conditionalized on the
301 <STRONG>NCURSES_VERSION</STRONG> feature macro.
305 <H2>SEE ALSO</H2><PRE>
306 <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_mouse.3x.html">curs_mouse(3x)</A></STRONG>,
307 <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><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>.
331 Man(1) output converted with
332 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>