4 <!-- Manpage converted by man2html 3.0.1 -->
8 <B>getch</B>, <B>wgetch</B>, <B>mvgetch</B>, <B>mvwgetch</B>, <B>ungetch</B>, <B>has_key</B> - get
9 (or push back) characters from <B>curses</B> terminal keyboard
13 <H2>SYNOPSIS</H2><PRE>
14 <B>#include</B> <B><curses.h></B>
16 <B>int</B> <B>getch(void);</B>
17 <B>int</B> <B>wgetch(WINDOW</B> <B>*win);</B>
18 <B>int</B> <B>mvgetch(int</B> <B>y,</B> <B>int</B> <B>x);</B>
19 <B>int</B> <B>mvwgetch(WINDOW</B> <B>*win,</B> <B>int</B> <B>y,</B> <B>int</B> <B>x);</B>
20 <B>int</B> <B>ungetch(int</B> <B>ch);</B>
21 <B>int</B> <B>has_key(int</B> <B>ch);</B>
25 <H2>DESCRIPTION</H2><PRE>
26 The <B>getch</B>, <B>wgetch</B>, <B>mvgetch</B> and <B>mvwgetch</B>, routines read a
27 character from the window. In no-delay mode, if no input
28 is waiting, the value <B>ERR</B> is returned. In delay mode, the
29 program waits until the system passes text through to the
30 program. Depending on the setting of <B>cbreak</B>, this is
31 after one character (cbreak mode), or after the first new-
32 line (nocbreak mode). In half-delay mode, the program
33 waits until a character is typed or the specified timeout
36 Unless <B>noecho</B> has been set, then the character will also
37 be echoed into the designated window according to the fol-
38 lowing rules: If the character is the current erase char-
39 acter, left arrow, or backspace, the cursor is moved one
40 space to the left and that screen position is erased as if
41 <B>delch</B> had been called. If the character value is any
42 other <B>KEY_</B> define, the user is alerted with a <B>beep</B> call.
43 Otherwise the character is simply output to the screen.
45 If the window is not a pad, and it has been moved or modi-
46 fied since the last call to <B>wrefresh</B>, <B>wrefresh</B> will be
47 called before another character is read.
49 If <B>keypad</B> is <B>TRUE</B>, and a function key is pressed, the
50 token for that function key is returned instead of the raw
51 characters. Possible function keys are defined in
52 <B><curses.h></B> as macros with values outside the range of
53 8-bit characters whose names begin with <B>KEY_.</B> Thus, a
54 variable intended to hold the return value of a function
55 key must be of short size or larger.
57 When a character that could be the beginning of a function
58 key is received (which, on modern terminals, means an
59 escape character), <B>curses</B> sets a timer. If the remainder
60 of the sequence does not come in within the designated
61 time, the character is passed through; otherwise, the
62 function key value is returned. For this reason, many
63 terminals experience a delay between the time a user
64 presses the escape key and the escape is returned to the
67 The <B>ungetch</B> routine places <I>ch</I> back onto the input queue to
68 be returned by the next call to <B>wgetch</B>. Note that there
69 is, in effect, just one input queue for all windows.
72 <B>Function</B> <B>Keys</B>
73 The following function keys, defined in <B><curses.h></B>, might
74 be returned by <B>getch</B> if <B>keypad</B> has been enabled. Note
75 that not all of these are necessarily supported on any
78 <I>Name</I> <I>Key</I> <I>name</I>
81 KEY_DOWN The four arrow keys ...
85 KEY_HOME Home key (upward+left arrow)
86 KEY_BACKSPACE Backspace
87 KEY_F0 Function keys; space for 64 keys
89 KEY_F(<I>n</I>) For 0 <= <I>n</I> <= 63
92 KEY_DC Delete character
93 KEY_IC Insert char or enter insert mode
94 KEY_EIC Exit insert char mode
95 KEY_CLEAR Clear screen
96 KEY_EOS Clear to end of screen
97 KEY_EOL Clear to end of line
98 KEY_SF Scroll 1 line forward
99 KEY_SR Scroll 1 line backward (reverse)
101 KEY_PPAGE Previous page
104 KEY_CATAB Clear all tabs
105 KEY_ENTER Enter or send
106 KEY_SRESET Soft (partial) reset
107 KEY_RESET Reset or hard reset
108 KEY_PRINT Print or copy
109 KEY_LL Home down or bottom (lower left).
110 KEY_A1 Upper left of keypad
111 KEY_A3 Upper right of keypad
112 KEY_B2 Center of keypad
113 KEY_C1 Lower left of keypad
114 KEY_C3 Lower right of keypad
115 KEY_BTAB Back tab key
116 KEY_BEG Beg(inning) key
117 KEY_CANCEL Cancel key
120 KEY_COMMAND Cmd (command) key
122 KEY_CREATE Create key
128 KEY_MESSAGE Message key
129 KEY_MOUSE Mouse event read
131 KEY_NEXT Next object key
133 KEY_OPTIONS Options key
134 KEY_PREVIOUS Previous object key
136 KEY_REFERENCE Ref(erence) key
137 KEY_REFRESH Refresh key
138 KEY_REPLACE Replace key
139 KEY_RESIZE Screen resized
140 KEY_RESTART Restart key
141 KEY_RESUME Resume key
143 KEY_SBEG Shifted beginning key
144 KEY_SCANCEL Shifted cancel key
145 KEY_SCOMMAND Shifted command key
146 KEY_SCOPY Shifted copy key
147 KEY_SCREATE Shifted create key
148 KEY_SDC Shifted delete char key
149 KEY_SDL Shifted delete line key
150 KEY_SELECT Select key
151 KEY_SEND Shifted end key
152 KEY_SEOL Shifted clear line key
153 KEY_SEXIT Shifted exit key
154 KEY_SFIND Shifted find key
155 KEY_SHELP Shifted help key
156 KEY_SHOME Shifted home key
157 KEY_SIC Shifted input key
158 KEY_SLEFT Shifted left arrow key
159 KEY_SMESSAGE Shifted message key
160 KEY_SMOVE Shifted move key
161 KEY_SNEXT Shifted next key
162 KEY_SOPTIONS Shifted options key
163 KEY_SPREVIOUS Shifted prev key
164 KEY_SPRINT Shifted print key
165 KEY_SREDO Shifted redo key
166 KEY_SREPLACE Shifted replace key
167 KEY_SRIGHT Shifted right arrow
168 KEY_SRSUME Shifted resume key
169 KEY_SSAVE Shifted save key
170 KEY_SSUSPEND Shifted suspend key
171 KEY_SUNDO Shifted undo key
173 KEY_SUSPEND Suspend key
176 Keypad is arranged like this:
178 +-----+------+-------+
179 | <B>A1</B> | <B>up</B> | <B>A3</B> |
180 +-----+------+-------+
181 |<B>left</B> | <B>B2</B> | <B>right</B> |
182 +-----+------+-------+
183 | <B>C1</B> | <B>down</B> | <B>C3</B> |
184 +-----+------+-------+
185 The <B>has_key</B> routine takes a key value from the above list,
186 and returns TRUE or FALSE according as the current termi-
187 nal type recognizes a key with that value.
192 <H2>RETURN VALUE</H2><PRE>
193 All routines return the integer <B>ERR</B> upon failure and an
194 integer value other than <B>ERR</B> (<B>OK</B> in the case of ungetch())
195 upon successful completion.
200 Use of the escape key by a programmer for a single charac-
201 ter function is discouraged, as it will cause a delay of
202 up to one second while the keypad code looks for a follow-
203 ing function-key sequence.
205 When using <B>getch</B>, <B>wgetch</B>, <B>mvgetch</B>, or <B>mvwgetch</B>, nocbreak
206 mode (<B>nocbreak</B>) and echo mode (<B>echo</B>) should not be used at
207 the same time. Depending on the state of the tty driver
208 when each character is typed, the program may produce
211 Note that <B>getch</B>, <B>mvgetch</B>, and <B>mvwgetch</B> may be macros.
213 Historically, the set of keypad macros was largely defined
214 by the extremely function-key-rich keyboard of the AT&T
215 7300, aka 3B1, aka Safari 4. Modern personal computers
216 usually have only a small subset of these. IBM PC-style
217 consoles typically support little more than <B>KEY_UP</B>,
218 <B>KEY_DOWN</B>, <B>KEY_LEFT</B>, <B>KEY_RIGHT</B>, <B>KEY_HOME</B>, <B>KEY_END</B>,
219 <B>KEY_NPAGE</B>, <B>KEY_PPAGE</B>, and function keys 1 through 12. The
220 Ins key is usually mapped to <B>KEY_IC</B>.
224 <H2>PORTABILITY</H2><PRE>
225 The *get* functions are described in the XSI Curses stan-
226 dard, Issue 4. They read single-byte characters only.
227 The standard specifies that they return <B>ERR</B> on failure,
228 but specifies no error conditions.
230 The echo behavior of these functions on input of <B>KEY_</B> or
231 backspace characters was not specified in the SVr4 docu-
232 mentation. This description is adopted from the XSI
235 The behavior of <B>getch</B> and friends in the presence of han-
236 dled signals is unspecified in the SVr4 and XSI Curses
237 documentation. Under historical curses implementations,
238 it varied depending on whether the operating system's
239 implementation of handled signal receipt interrupts a
240 <B><A HREF="read.2.html">read(2)</A></B> call in progress or not, and also (in some imple-
241 mentations) depending on whether an input timeout or non-
242 blocking mode hsd been set.
244 Programmers concerned about portability should be prepared
245 for either of two cases: (a) signal receipt does not
246 interrupt <B>getch</B>; (b) signal receipt interrupts <B>getch</B> and
247 causes it to return ERR with <B>errno</B> set to <B>EINTR</B>. Under
248 the <B>ncurses</B> implementation, handled signals never inter-
251 The <B>has_key</B> function is unique to <B>ncurses</B>. We recommend
252 that any code using it be conditionalized on the
253 <B>NCURSES_VERSION</B> feature macro.
257 <H2>SEE ALSO</H2><PRE>
258 <B><A HREF="ncurses.3x.html">curses(3x)</A></B>, <B><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></B>, <B><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></B>,
259 <B><A HREF="curs_move.3x.html">curs_move(3x)</A></B>, <B><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></B>. <B><A HREF="resizeterm.3x.html">resizeterm(3x)</A></B>.
292 Man(1) output converted with
293 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>