3 ****************************************************************************
4 * Copyright (c) 1998-2012,2014 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.39 2014/05/24 20:16:31 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>curs_getch 3x</H1>
45 <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 <H2><a name="h2-NAME">NAME</a></H2><PRE>
52 <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, <STRONG>ungetch</STRONG>, <STRONG>has_key</STRONG> - get
53 (or push back) characters from <STRONG>curses</STRONG> terminal keyboard
57 <H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
58 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
60 <STRONG>int</STRONG> <STRONG>getch(void);</STRONG>
61 <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*win);</STRONG>
62 <STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
63 <STRONG>int</STRONG> <STRONG>mvwgetch(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x);</STRONG>
64 <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <STRONG>ch);</STRONG>
65 <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <STRONG>ch);</STRONG>
69 <H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
70 The <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG> and <STRONG>mvwgetch</STRONG>, routines read a
71 character from the window. In no-delay mode, if no input
72 is waiting, the value <STRONG>ERR</STRONG> is returned. In delay mode, the
73 program waits until the system passes text through to the
74 program. Depending on the setting of <STRONG>cbreak</STRONG>, this is af-
75 ter one character (cbreak mode), or after the first new-
76 line (nocbreak mode). In half-delay mode, the program
77 waits until a character is typed or the specified timeout
80 If <STRONG>echo</STRONG> is enabled, and the window is not a pad, then the
81 character will also be echoed into the designated window
82 according to the following rules:
84 <STRONG>o</STRONG> If the character is the current erase character, left
85 arrow, or backspace, the cursor is moved one space to
86 the left and that screen position is erased as if
87 <STRONG>delch</STRONG> had been called.
89 <STRONG>o</STRONG> If the character value is any other <STRONG>KEY_</STRONG> define, the
90 user is alerted with a <STRONG>beep</STRONG> call.
92 <STRONG>o</STRONG> If the character is a carriage-return, and if <STRONG>nl</STRONG> is
93 enabled, it is translated to a line-feed after echo-
96 <STRONG>o</STRONG> Otherwise the character is simply output to the
99 If the window is not a pad, and it has been moved or modi-
100 fied since the last call to <STRONG>wrefresh</STRONG>, <STRONG>wrefresh</STRONG> will be
101 called before another character is read.
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
105 characters. Possible function keys are defined in <STRONG><curs-</STRONG>
106 <STRONG>es.h></STRONG> as macros with values outside the range of 8-bit
107 characters whose names begin with <STRONG>KEY_</STRONG>. Thus, a variable
108 intended to hold the return value of a function key must
109 be of short size or larger.
111 When a character that could be the beginning of a function
112 key is received (which, on modern terminals, means an es-
113 cape character), <STRONG>curses</STRONG> sets a timer. If the remainder of
114 the sequence does not come in within the designated time,
115 the character is passed through; otherwise, the function
116 key value is returned. For this reason, many terminals
117 experience a delay between the time a user presses the es-
118 cape key and the escape is returned to the program.
120 The <STRONG>ungetch</STRONG> routine places <EM>ch</EM> back onto the input queue to
121 be returned by the next call to <STRONG>wgetch</STRONG>. There is just one
122 input queue for all windows.
126 <H3><a name="h3-Function-Keys">Function Keys</a></H3><PRE>
127 The following function keys, defined in <STRONG><curses.h></STRONG>, might
128 be returned by <STRONG>getch</STRONG> if <STRONG>keypad</STRONG> has been enabled. Note
129 that not all of these are necessarily supported on any
132 <EM>Name</EM> <EM>Key</EM> <EM>name</EM>
133 -------------------------------------------------
135 KEY_DOWN The four arrow keys ...
139 KEY_HOME Home key (upward+left arrow)
140 KEY_BACKSPACE Backspace
141 KEY_F0 Function keys; space for 64 keys
143 KEY_F(<EM>n</EM>) For 0 <= <EM>n</EM> <= 63
146 KEY_DC Delete character
147 KEY_IC Insert char or enter insert mode
148 KEY_EIC Exit insert char mode
149 KEY_CLEAR Clear screen
150 KEY_EOS Clear to end of screen
151 KEY_EOL Clear to end of line
152 KEY_SF Scroll 1 line forward
153 KEY_SR Scroll 1 line backward (reverse)
155 KEY_PPAGE Previous page
158 KEY_CATAB Clear all tabs
159 KEY_ENTER Enter or send
160 KEY_SRESET Soft (partial) reset
161 KEY_RESET Reset or hard reset
162 KEY_PRINT Print or copy
163 KEY_LL Home down or bottom (lower left)
164 KEY_A1 Upper left of keypad
165 KEY_A3 Upper right of keypad
166 KEY_B2 Center of keypad
167 KEY_C1 Lower left of keypad
168 KEY_C3 Lower right of keypad
169 KEY_BTAB Back tab key
170 KEY_BEG Beg(inning) key
171 KEY_CANCEL Cancel key
173 KEY_COMMAND Cmd (command) key
175 KEY_CREATE Create key
181 KEY_MESSAGE Message key
182 KEY_MOUSE Mouse event read
185 KEY_NEXT Next object key
187 KEY_OPTIONS Options key
188 KEY_PREVIOUS Previous object key
190 KEY_REFERENCE Ref(erence) key
191 KEY_REFRESH Refresh key
192 KEY_REPLACE Replace key
193 KEY_RESIZE Screen resized
194 KEY_RESTART Restart key
195 KEY_RESUME Resume key
197 KEY_SBEG Shifted beginning key
198 KEY_SCANCEL Shifted cancel key
199 KEY_SCOMMAND Shifted command key
200 KEY_SCOPY Shifted copy key
201 KEY_SCREATE Shifted create key
202 KEY_SDC Shifted delete char key
203 KEY_SDL Shifted delete line key
204 KEY_SELECT Select key
205 KEY_SEND Shifted end key
206 KEY_SEOL Shifted clear line key
207 KEY_SEXIT Shifted exit key
208 KEY_SFIND Shifted find key
209 KEY_SHELP Shifted help key
210 KEY_SHOME Shifted home key
211 KEY_SIC Shifted input key
212 KEY_SLEFT Shifted left arrow key
213 KEY_SMESSAGE Shifted message key
214 KEY_SMOVE Shifted move key
215 KEY_SNEXT Shifted next key
216 KEY_SOPTIONS Shifted options key
217 KEY_SPREVIOUS Shifted prev key
218 KEY_SPRINT Shifted print key
219 KEY_SREDO Shifted redo key
220 KEY_SREPLACE Shifted replace key
221 KEY_SRIGHT Shifted right arrow
222 KEY_SRSUME Shifted resume key
223 KEY_SSAVE Shifted save key
224 KEY_SSUSPEND Shifted suspend key
225 KEY_SUNDO Shifted undo key
226 KEY_SUSPEND Suspend key
229 Keypad is arranged like this:
232 +-----+------+-------+
233 | <STRONG>A1</STRONG> | <STRONG>up</STRONG> | <STRONG>A3</STRONG> |
234 +-----+------+-------+
235 |<STRONG>left</STRONG> | <STRONG>B2</STRONG> | <STRONG>right</STRONG> |
236 +-----+------+-------+
237 | <STRONG>C1</STRONG> | <STRONG>down</STRONG> | <STRONG>C3</STRONG> |
238 +-----+------+-------+
239 The <STRONG>has_key</STRONG> routine takes a key value from the above list,
240 and returns TRUE or FALSE according to whether the current
241 terminal type recognizes a key with that value. Note that
242 a few values do not correspond to a real key, e.g.,
243 <STRONG>KEY_RESIZE</STRONG> and <STRONG>KEY_MOUSE</STRONG>. See <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> for more de-
244 tails about <STRONG>KEY_RESIZE</STRONG>, and <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> for a discus-
245 sion of <STRONG>KEY_MOUSE</STRONG>.
249 <H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
250 All routines return the integer <STRONG>ERR</STRONG> upon failure and an
251 integer value other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of ungetch())
252 upon successful completion.
254 <STRONG>ungetch</STRONG>
255 returns ERR if there is no more room in the FIFO.
257 <STRONG>wgetch</STRONG>
258 returns ERR if the window pointer is null, or if
259 its timeout expires without having any data.
261 Functions with a "mv" prefix first perform a cursor move-
262 ment using <STRONG>wmove</STRONG>, and return an error if the position is
263 outside the window, or if the window pointer is null.
267 <H2><a name="h2-NOTES">NOTES</a></H2><PRE>
268 Use of the escape key by a programmer for a single charac-
269 ter function is discouraged, as it will cause a delay of
270 up to one second while the keypad code looks for a follow-
271 ing function-key sequence.
273 Note that some keys may be the same as commonly used con-
274 trol keys, e.g., <STRONG>KEY_ENTER</STRONG> versus control/M, <STRONG>KEY_BACKSPACE</STRONG>
275 versus control/H. Some curses implementations may differ
276 according to whether they treat these control keys spe-
277 cially (and ignore the terminfo), or use the terminfo def-
278 initions. <STRONG>Ncurses</STRONG> uses the terminfo definition. If it
279 says that <STRONG>KEY_ENTER</STRONG> is control/M, <STRONG>getch</STRONG> will return
280 <STRONG>KEY_ENTER</STRONG> when you press control/M.
282 Generally, <STRONG>KEY_ENTER</STRONG> denotes the character(s) sent by the
283 <EM>Enter</EM> key on the numeric keypad:
285 <STRONG>o</STRONG> the terminal description lists the most useful keys,
287 <STRONG>o</STRONG> the <EM>Enter</EM> key on the regular keyboard is already han-
288 dled by the standard ASCII characters for carriage-re-
291 <STRONG>o</STRONG> depending on whether <STRONG>nl</STRONG> or <STRONG>nonl</STRONG> was called, pressing
292 "Enter" on the regular keyboard may return either a
293 carriage-return or line-feed, and finally
295 <STRONG>o</STRONG> "Enter or send" is the standard description for this
298 When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or <STRONG>mvwgetch</STRONG>, nocbreak
299 mode (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) should not be used at
300 the same time. Depending on the state of the tty driver
301 when each character is typed, the program may produce un-
304 Note that <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be macros.
306 Historically, the set of keypad macros was largely defined
307 by the extremely function-key-rich keyboard of the AT&T
308 7300, aka 3B1, aka Safari 4. Modern personal computers
309 usually have only a small subset of these. IBM PC-style
310 consoles typically support little more than <STRONG>KEY_UP</STRONG>,
311 <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>,
312 <STRONG>KEY_NPAGE</STRONG>, <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12. The
313 Ins key is usually mapped to <STRONG>KEY_IC</STRONG>.
317 <H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
318 The *get* functions are described in the XSI Curses stan-
319 dard, Issue 4. They read single-byte characters only.
320 The standard specifies that they return <STRONG>ERR</STRONG> on failure,
321 but specifies no error conditions.
323 The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or
324 backspace characters was not specified in the SVr4 docu-
325 mentation. This description is adopted from the XSI Curs-
328 The behavior of <STRONG>getch</STRONG> and friends in the presence of han-
329 dled signals is unspecified in the SVr4 and XSI Curses
330 documentation. Under historical curses implementations,
331 it varied depending on whether the operating system's im-
332 plementation of handled signal receipt interrupts a
333 <STRONG>read(2)</STRONG> call in progress or not, and also (in some imple-
334 mentations) depending on whether an input timeout or non-
335 blocking mode has been set.
337 Programmers concerned about portability should be prepared
338 for either of two cases: (a) signal receipt does not in-
339 terrupt <STRONG>getch</STRONG>; (b) signal receipt interrupts <STRONG>getch</STRONG> and
340 causes it to return ERR with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. Under
341 the <STRONG>ncurses</STRONG> implementation, handled signals never inter-
342 rupt <STRONG>getch</STRONG>.
344 The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>. We recommend
345 that any code using it be conditionalized on the <STRONG>NCURS-</STRONG>
346 <STRONG>ES_VERSION</STRONG> feature macro.
350 <H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
351 <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>,
352 <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>
353 <STRONG><A HREF="resizeterm.3x.html">sizeterm(3x)</A></STRONG>.
355 Comparable functions in the wide-character (ncursesw) li-
356 brary are described in <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>.
360 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
364 <li><a href="#h2-NAME">NAME</a></li>
365 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
366 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
368 <li><a href="#h3-Function-Keys">Function Keys</a></li>
371 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
372 <li><a href="#h2-NOTES">NOTES</a></li>
373 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
374 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>