1curs_getch(3X) curs_getch(3X)
2
6 getch, wgetch, mvgetch, mvwgetch, ungetch, has_key - get (or push back)
7 characters from curses terminal keyboard
8
10 #include <curses.h>
11 int getch(void);
13 int wgetch(WINDOW *win);
14 int mvgetch(int y, int x);
15 int mvwgetch(WINDOW *win, int y, int x);
16 int ungetch(int ch);
17 int has_key(int ch);
18
20 Reading characters
21 The getch, wgetch, mvgetch and mvwgetch, routines read a character from
22 the window. In no-delay mode, if no input is waiting, the value ERR is
23 returned. In delay mode, the program waits until the system passes
24 text through to the program. Depending on the setting of cbreak, this
25 is after one character (cbreak mode), or after the first newline
26 (nocbreak mode). In half-delay mode, the program waits until a charac‐
27 ter is typed or the specified timeout has been reached.
28 If echo is enabled, and the window is not a pad, then the character
30 will also be echoed into the designated window according to the follow‐
31 ing rules:
32 · If the character is the current erase character, left arrow, or
34 backspace, the cursor is moved one space to the left and that
35 screen position is erased as if delch had been called.
36 · If the character value is any other KEY_ define, the user is alert‐
38 ed with a beep call.
39 · If the character is a carriage-return, and if nl is enabled, it is
41 translated to a line-feed after echoing.
42 · Otherwise the character is simply output to the screen.
44 If the window is not a pad, and it has been moved or modified since the
46 last call to wrefresh, wrefresh will be called before another character
47 is read.
48 Keypad mode
50 If keypad is TRUE, and a function key is pressed, the token for that
51 function key is returned instead of the raw characters:
52 · The predefined function keys are listed in <curses.h> as macros
54 with values outside the range of 8-bit characters. Their names be‐
55 gin with KEY_.
56 · Other (user-defined) function keys which may be defined using de‐
58 fine_key(3X) have no names, but also are expected to have values
59 outside the range of 8-bit characters.
60 Thus, a variable intended to hold the return value of a function key
62 must be of short size or larger.
63 When a character that could be the beginning of a function key is re‐
65 ceived (which, on modern terminals, means an escape character), curses
66 sets a timer. If the remainder of the sequence does not come in within
67 the designated time, the character is passed through; otherwise, the
68 function key value is returned. For this reason, many terminals expe‐
69 rience a delay between the time a user presses the escape key and the
70 escape is returned to the program.
71 In ncurses, the timer normally expires after the value in ESCDELAY (see
73 curs_variables(3X)). If notimeout is TRUE, the timer does not expire;
74 it is an infinite (or very large) value. Because function keys usually
75 begin with an escape character, the terminal may appear to hang in no‐
76 timeout mode after pressing the escape key until another key is
77 pressed.
78 Ungetting characters
80 The ungetch routine places ch back onto the input queue to be returned
81 by the next call to wgetch. There is just one input queue for all win‐
82 dows.
83 Predefined key-codes
85 The following special keys are defined in <curses.h>.
86 · Except for the special case KEY_RESIZE, it is necessary to enable
88 keypad for getch to return these codes.
89 · Not all of these are necessarily supported on any particular termi‐
91 nal.
92 · The naming convention may seem obscure, with some apparent mis‐
94 spellings (such as “RSUME” for “resume”). The names correspond to
95 the long terminfo capability names for the keys, and were defined
96 long ago, in the 1980s.
97 Name Key name
99 ─────────────────────────────────────────────────
100 KEY_BREAK Break key
101 KEY_DOWN The four arrow keys ...
102 KEY_UP
103 KEY_LEFT
104 KEY_RIGHT
105 KEY_HOME Home key (upward+left arrow)
106 KEY_BACKSPACE Backspace
107 KEY_F0 Function keys; space for 64 keys
108 is reserved.
109 KEY_F(n) For 0 ≤ n ≤ 63
110 KEY_DL Delete line
111 KEY_IL Insert line
112 KEY_DC Delete character
113 KEY_IC Insert char or enter insert mode
114 KEY_EIC Exit insert char mode
115 KEY_CLEAR Clear screen
116 KEY_EOS Clear to end of screen
117 KEY_EOL Clear to end of line
118 KEY_SF Scroll 1 line forward
119 KEY_SR Scroll 1 line backward (reverse)
120 KEY_NPAGE Next page
121 KEY_PPAGE Previous page
122 KEY_STAB Set tab
123 KEY_CTAB Clear tab
124 KEY_CATAB Clear all tabs
125 KEY_ENTER Enter or send
126 KEY_SRESET Soft (partial) reset
127 KEY_RESET Reset or hard reset
128 KEY_PRINT Print or copy
129 KEY_LL Home down or bottom (lower left)
130 KEY_A1 Upper left of keypad
131 KEY_A3 Upper right of keypad
132 KEY_B2 Center of keypad
134 KEY_C1 Lower left of keypad
135 KEY_C3 Lower right of keypad
136 KEY_BTAB Back tab key
137 KEY_BEG Beg(inning) key
138 KEY_CANCEL Cancel key
139 KEY_CLOSE Close key
140 KEY_COMMAND Cmd (command) key
141 KEY_COPY Copy key
142 KEY_CREATE Create key
143 KEY_END End key
144 KEY_EXIT Exit key
145 KEY_FIND Find key
146 KEY_HELP Help key
147 KEY_MARK Mark key
148 KEY_MESSAGE Message key
149 KEY_MOUSE Mouse event read
150 KEY_MOVE Move key
151 KEY_NEXT Next object key
152 KEY_OPEN Open key
153 KEY_OPTIONS Options key
154 KEY_PREVIOUS Previous object key
155 KEY_REDO Redo key
156 KEY_REFERENCE Ref(erence) key
157 KEY_REFRESH Refresh key
158 KEY_REPLACE Replace key
159 KEY_RESIZE Screen resized
160 KEY_RESTART Restart key
161 KEY_RESUME Resume key
162 KEY_SAVE Save key
163 KEY_SBEG Shifted beginning key
164 KEY_SCANCEL Shifted cancel key
165 KEY_SCOMMAND Shifted command key
166 KEY_SCOPY Shifted copy key
167 KEY_SCREATE Shifted create key
168 KEY_SDC Shifted delete char key
169 KEY_SDL Shifted delete line key
170 KEY_SELECT Select key
171 KEY_SEND Shifted end key
172 KEY_SEOL Shifted clear line key
173 KEY_SEXIT Shifted exit key
174 KEY_SFIND Shifted find key
175 KEY_SHELP Shifted help key
176 KEY_SHOME Shifted home key
177 KEY_SIC Shifted input key
178 KEY_SLEFT Shifted left arrow key
179 KEY_SMESSAGE Shifted message key
180 KEY_SMOVE Shifted move key
181 KEY_SNEXT Shifted next key
182 KEY_SOPTIONS Shifted options key
183 KEY_SPREVIOUS Shifted prev key
184 KEY_SPRINT Shifted print key
185 KEY_SREDO Shifted redo key
186 KEY_SREPLACE Shifted replace key
187 KEY_SRIGHT Shifted right arrow
188 KEY_SRSUME Shifted resume key
189 KEY_SSAVE Shifted save key
190 KEY_SSUSPEND Shifted suspend key
191 KEY_SUNDO Shifted undo key
192 KEY_SUSPEND Suspend key
193 KEY_UNDO Undo key
194 Keypad is arranged like this:
196 ┌─────┬──────┬───────┐
198 │ A1 │ up │ A3 │
199 ├─────┼──────┼───────┤
200 │left │ B2 │ right │
201 ├─────┼──────┼───────┤
202 │ C1 │ down │ C3 │
203 └─────┴──────┴───────┘
204 A few of these predefined values do not correspond to a real key:
205 · KEY_RESIZE is returned when the SIGWINCH signal has been detected
207 (see initscr(3X) and resizeterm(3X)). This code is returned
208 whether or not keypad has been enabled.
209 · KEY_MOUSE is returned for mouse-events (see curs_mouse(3X)). This
211 code relies upon whether or not keypad(3X) has been enabled, be‐
212 cause (e.g., with xterm mouse prototocol) ncurses must read escape
213 sequences, just like a function key.
214 Testing key-codes
216 The has_key routine takes a key-code value from the above list, and re‐
217 turns TRUE or FALSE according to whether the current terminal type rec‐
218 ognizes a key with that value.
219 The library also supports these extensions:
221 define_key
223 defines a key-code for a given string (see define_key(3X)).
224 key_defined
226 checks if there is a key-code defined for a given string (see
227 key_defined(3X)).
228
230 All routines return the integer ERR upon failure and an integer value
231 other than ERR (OK in the case of ungetch) upon successful completion.
232 ungetch
234 returns ERR if there is no more room in the FIFO.
235 wgetch
237 returns ERR if the window pointer is null, or if its timeout
238 expires without having any data, or if the execution was inter‐
239 rupted by a signal (errno will be set to EINTR).
240 Functions with a “mv” prefix first perform a cursor movement using
242 wmove, and return an error if the position is outside the window, or if
243 the window pointer is null.
244
246 Use of the escape key by a programmer for a single character function
247 is discouraged, as it will cause a delay of up to one second while the
248 keypad code looks for a following function-key sequence.
249 Some keys may be the same as commonly used control keys, e.g., KEY_EN‐
251 TER versus control/M, KEY_BACKSPACE versus control/H. Some curses im‐
252 plementations may differ according to whether they treat these control
253 keys specially (and ignore the terminfo), or use the terminfo defini‐
254 tions. Ncurses uses the terminfo definition. If it says that KEY_EN‐
255 TER is control/M, getch will return KEY_ENTER when you press control/M.
256 Generally, KEY_ENTER denotes the character(s) sent by the Enter key on
258 the numeric keypad:
259 · the terminal description lists the most useful keys,
261 · the Enter key on the regular keyboard is already handled by the
263 standard ASCII characters for carriage-return and line-feed,
264 · depending on whether nl or nonl was called, pressing “Enter” on the
266 regular keyboard may return either a carriage-return or line-feed,
267 and finally
268 · “Enter or send” is the standard description for this key.
270 When using getch, wgetch, mvgetch, or mvwgetch, nocbreak mode
272 (nocbreak) and echo mode (echo) should not be used at the same time.
273 Depending on the state of the tty driver when each character is typed,
274 the program may produce undesirable results.
275 Note that getch, mvgetch, and mvwgetch may be macros.
277 Historically, the set of keypad macros was largely defined by the ex‐
279 tremely function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Sa‐
280 fari 4. Modern personal computers usually have only a small subset of
281 these. IBM PC-style consoles typically support little more than
282 KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END, KEY_NPAGE,
283 KEY_PPAGE, and function keys 1 through 12. The Ins key is usually
284 mapped to KEY_IC.
285
287 The *get* functions are described in the XSI Curses standard, Issue 4.
288 They read single-byte characters only. The standard specifies that
289 they return ERR on failure, but specifies no error conditions.
290 The echo behavior of these functions on input of KEY_ or backspace
292 characters was not specified in the SVr4 documentation. This descrip‐
293 tion is adopted from the XSI Curses standard.
294 The behavior of getch and friends in the presence of handled signals is
296 unspecified in the SVr4 and XSI Curses documentation. Under historical
297 curses implementations, it varied depending on whether the operating
298 system's implementation of handled signal receipt interrupts a read(2)
299 call in progress or not, and also (in some implementations) depending
300 on whether an input timeout or non-blocking mode has been set.
301 KEY_MOUSE is mentioned in XSI Curses, along with a few related terminfo
303 capabilities, but no higher-level functions use the feature. The im‐
304 plementation in ncurses is an extension.
305 KEY_RESIZE is an extension first implemented for ncurses. NetBSD curs‐
307 es later added this extension.
308 Programmers concerned about portability should be prepared for either
310 of two cases: (a) signal receipt does not interrupt getch; (b) signal
311 receipt interrupts getch and causes it to return ERR with errno set to
312 EINTR.
313 The has_key function is unique to ncurses. We recommend that any code
315 using it be conditionalized on the NCURSES_VERSION feature macro.
316
318 curses(3X), curs_inopts(3X), curs_outopts(3X), curs_mouse(3X),
319 curs_move(3X), curs_refresh(3X), curs_variables(3X), resizeterm(3X).
320 Comparable functions in the wide-character (ncursesw) library are de‐
322 scribed in curs_get_wch(3X).
323 curs_getch(3X)