3 ****************************************************************************
4 * Copyright (c) 1998-2014,2015 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.40 2015/04/11 10:23:49 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>
50 <H2><a name="h2-NAME">NAME</a></H2><PRE>
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><a name="h2-SYNOPSIS">SYNOPSIS</a></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><a name="h2-DESCRIPTION">DESCRIPTION</a></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.
125 <H3><a name="h3-Function-Keys">Function Keys</a></H3><PRE>
126 The following function keys, defined in <STRONG><curses.h></STRONG>, might
127 be returned by <STRONG>getch</STRONG> if <STRONG>keypad</STRONG> has been enabled. Note
128 that not all of these are necessarily supported on any
131 <EM>Name</EM> <EM>Key</EM> <EM>name</EM>
132 -------------------------------------------------
134 KEY_DOWN The four arrow keys ...
138 KEY_HOME Home key (upward+left arrow)
139 KEY_BACKSPACE Backspace
140 KEY_F0 Function keys; space for 64 keys
142 KEY_F(<EM>n</EM>) For 0 <= <EM>n</EM> <= 63
145 KEY_DC Delete character
146 KEY_IC Insert char or enter insert mode
147 KEY_EIC Exit insert char mode
148 KEY_CLEAR Clear screen
149 KEY_EOS Clear to end of screen
150 KEY_EOL Clear to end of line
151 KEY_SF Scroll 1 line forward
152 KEY_SR Scroll 1 line backward (reverse)
154 KEY_PPAGE Previous page
157 KEY_CATAB Clear all tabs
158 KEY_ENTER Enter or send
159 KEY_SRESET Soft (partial) reset
160 KEY_RESET Reset or hard reset
161 KEY_PRINT Print or copy
162 KEY_LL Home down or bottom (lower left)
163 KEY_A1 Upper left of keypad
164 KEY_A3 Upper right of keypad
165 KEY_B2 Center of keypad
166 KEY_C1 Lower left of keypad
167 KEY_C3 Lower right of keypad
168 KEY_BTAB Back tab key
169 KEY_BEG Beg(inning) key
170 KEY_CANCEL Cancel key
172 KEY_COMMAND Cmd (command) key
174 KEY_CREATE Create key
180 KEY_MESSAGE Message key
181 KEY_MOUSE Mouse event read
184 KEY_NEXT Next object key
186 KEY_OPTIONS Options key
187 KEY_PREVIOUS Previous object key
189 KEY_REFERENCE Ref(erence) key
190 KEY_REFRESH Refresh key
191 KEY_REPLACE Replace key
192 KEY_RESIZE Screen resized
193 KEY_RESTART Restart key
194 KEY_RESUME Resume key
196 KEY_SBEG Shifted beginning key
197 KEY_SCANCEL Shifted cancel key
198 KEY_SCOMMAND Shifted command key
199 KEY_SCOPY Shifted copy key
200 KEY_SCREATE Shifted create key
201 KEY_SDC Shifted delete char key
202 KEY_SDL Shifted delete line key
203 KEY_SELECT Select key
204 KEY_SEND Shifted end key
205 KEY_SEOL Shifted clear line key
206 KEY_SEXIT Shifted exit key
207 KEY_SFIND Shifted find key
208 KEY_SHELP Shifted help key
209 KEY_SHOME Shifted home key
210 KEY_SIC Shifted input key
211 KEY_SLEFT Shifted left arrow key
212 KEY_SMESSAGE Shifted message key
213 KEY_SMOVE Shifted move key
214 KEY_SNEXT Shifted next key
215 KEY_SOPTIONS Shifted options key
216 KEY_SPREVIOUS Shifted prev key
217 KEY_SPRINT Shifted print key
218 KEY_SREDO Shifted redo key
219 KEY_SREPLACE Shifted replace key
220 KEY_SRIGHT Shifted right arrow
221 KEY_SRSUME Shifted resume key
222 KEY_SSAVE Shifted save key
223 KEY_SSUSPEND Shifted suspend key
224 KEY_SUNDO Shifted undo key
225 KEY_SUSPEND Suspend key
228 Keypad is arranged like this:
231 +-----+------+-------+
232 | <STRONG>A1</STRONG> | <STRONG>up</STRONG> | <STRONG>A3</STRONG> |
233 +-----+------+-------+
234 |<STRONG>left</STRONG> | <STRONG>B2</STRONG> | <STRONG>right</STRONG> |
235 +-----+------+-------+
236 | <STRONG>C1</STRONG> | <STRONG>down</STRONG> | <STRONG>C3</STRONG> |
237 +-----+------+-------+
238 The <STRONG>has_key</STRONG> routine takes a key value from the above list,
239 and returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG> according to whether the current
240 terminal type recognizes a key with that value. Note that
241 a few values do not correspond to a real key, e.g.,
242 <STRONG>KEY_RESIZE</STRONG> and <STRONG>KEY_MOUSE</STRONG>. See <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> for more de-
243 tails about <STRONG>KEY_RESIZE</STRONG>, and <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> for a discus-
244 sion of <STRONG>KEY_MOUSE</STRONG>.
248 <H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
249 All routines return the integer <STRONG>ERR</STRONG> upon failure and an
250 integer value other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of ungetch())
251 upon successful completion.
253 <STRONG>ungetch</STRONG>
254 returns ERR if there is no more room in the FIFO.
256 <STRONG>wgetch</STRONG>
257 returns ERR if the window pointer is null, or if
258 its timeout expires without having any data.
260 Functions with a "mv" prefix first perform a cursor move-
261 ment using <STRONG>wmove</STRONG>, and return an error if the position is
262 outside the window, or if the window pointer is null.
266 <H2><a name="h2-NOTES">NOTES</a></H2><PRE>
267 Use of the escape key by a programmer for a single charac-
268 ter function is discouraged, as it will cause a delay of
269 up to one second while the keypad code looks for a follow-
270 ing function-key sequence.
272 Note that some keys may be the same as commonly used con-
273 trol keys, e.g., <STRONG>KEY_ENTER</STRONG> versus control/M, <STRONG>KEY_BACKSPACE</STRONG>
274 versus control/H. Some curses implementations may differ
275 according to whether they treat these control keys spe-
276 cially (and ignore the terminfo), or use the terminfo def-
277 initions. <STRONG>Ncurses</STRONG> uses the terminfo definition. If it
278 says that <STRONG>KEY_ENTER</STRONG> is control/M, <STRONG>getch</STRONG> will return
279 <STRONG>KEY_ENTER</STRONG> when you press control/M.
281 Generally, <STRONG>KEY_ENTER</STRONG> denotes the character(s) sent by the
282 <EM>Enter</EM> key on the numeric keypad:
284 <STRONG>o</STRONG> the terminal description lists the most useful keys,
286 <STRONG>o</STRONG> the <EM>Enter</EM> key on the regular keyboard is already han-
287 dled by the standard ASCII characters for carriage-re-
290 <STRONG>o</STRONG> depending on whether <STRONG>nl</STRONG> or <STRONG>nonl</STRONG> was called, pressing
291 "Enter" on the regular keyboard may return either a
292 carriage-return or line-feed, and finally
294 <STRONG>o</STRONG> "Enter or send" is the standard description for this
297 When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or <STRONG>mvwgetch</STRONG>, nocbreak
298 mode (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) should not be used at
299 the same time. Depending on the state of the tty driver
300 when each character is typed, the program may produce un-
303 Note that <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be macros.
305 Historically, the set of keypad macros was largely defined
306 by the extremely function-key-rich keyboard of the AT&T
307 7300, aka 3B1, aka Safari 4. Modern personal computers
308 usually have only a small subset of these. IBM PC-style
309 consoles typically support little more than <STRONG>KEY_UP</STRONG>,
310 <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>,
311 <STRONG>KEY_NPAGE</STRONG>, <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12. The
312 Ins key is usually mapped to <STRONG>KEY_IC</STRONG>.
316 <H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
317 The *get* functions are described in the XSI Curses stan-
318 dard, Issue 4. They read single-byte characters only.
319 The standard specifies that they return <STRONG>ERR</STRONG> on failure,
320 but specifies no error conditions.
322 The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or
323 backspace characters was not specified in the SVr4 docu-
324 mentation. This description is adopted from the XSI Curs-
327 The behavior of <STRONG>getch</STRONG> and friends in the presence of han-
328 dled signals is unspecified in the SVr4 and XSI Curses
329 documentation. Under historical curses implementations,
330 it varied depending on whether the operating system's im-
331 plementation of handled signal receipt interrupts a
332 <STRONG>read(2)</STRONG> call in progress or not, and also (in some imple-
333 mentations) depending on whether an input timeout or non-
334 blocking mode has been set.
336 Programmers concerned about portability should be prepared
337 for either of two cases: (a) signal receipt does not in-
338 terrupt <STRONG>getch</STRONG>; (b) signal receipt interrupts <STRONG>getch</STRONG> and
339 causes it to return ERR with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. Under
340 the <STRONG>ncurses</STRONG> implementation, handled signals never inter-
341 rupt <STRONG>getch</STRONG>.
343 The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>. We recommend
344 that any code using it be conditionalized on the <STRONG>NCURS-</STRONG>
345 <STRONG>ES_VERSION</STRONG> feature macro.
349 <H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
350 <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>,
351 <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>
352 <STRONG><A HREF="resizeterm.3x.html">sizeterm(3x)</A></STRONG>.
354 Comparable functions in the wide-character (ncursesw) li-
355 brary are described in <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>.
359 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
363 <li><a href="#h2-NAME">NAME</a></li>
364 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
365 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
367 <li><a href="#h3-Function-Keys">Function Keys</a></li>
370 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
371 <li><a href="#h2-NOTES">NOTES</a></li>
372 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
373 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>