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