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