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 The getch, wgetch, mvgetch and mvwgetch, routines read a character from
21 the window. In no-delay mode, if no input is waiting, the value ERR is
22 returned. In delay mode, the program waits until the system passes
23 text through to the program. Depending on the setting of cbreak, this
24 is after one character (cbreak mode), or after the first newline
25 (nocbreak mode). In half-delay mode, the program waits until a charac‐
26 ter is typed or the specified timeout has been reached.
27 Unless noecho has been set, then the character will also be echoed into
29 the designated window according to the following rules: if the charac‐
30 ter is the current erase character, left arrow, or backspace, the cur‐
31 sor is moved one space to the left and that screen position is erased
32 as if delch had been called. If the character value is any other KEY_
33 define, the user is alerted with a beep call. Otherwise the character
34 is simply output to the screen.
35 If the window is not a pad, and it has been moved or modified since the
37 last call to wrefresh, wrefresh will be called before another character
38 is read.
39 If keypad is TRUE, and a function key is pressed, the token for that
41 function key is returned instead of the raw characters. Possible func‐
42 tion keys are defined in <curses.h> as macros with values outside the
43 range of 8-bit characters whose names begin with KEY_. Thus, a variable
44 intended to hold the return value of a function key must be of short
45 size or larger.
46 When a character that could be the beginning of a function key is re‐
48 ceived (which, on modern terminals, means an escape character), curses
49 sets a timer. If the remainder of the sequence does not come in within
50 the designated time, the character is passed through; otherwise, the
51 function key value is returned. For this reason, many terminals expe‐
52 rience a delay between the time a user presses the escape key and the
53 escape is returned to the program.
54 The ungetch routine places ch back onto the input queue to be returned
56 by the next call to wgetch. There is just one input queue for all win‐
57 dows.
58 Function Keys
60 The following function keys, defined in <curses.h>, might be returned
61 by getch if keypad has been enabled. Note that not all of these are
62 necessarily supported on any particular terminal.
63 Name Key name
66 KEY_BREAK Break key
68 KEY_DOWN The four arrow keys ...
69 KEY_UP
70 KEY_LEFT
71 KEY_RIGHT
72 KEY_HOME Home key (upward+left arrow)
73 KEY_BACKSPACE Backspace
74 KEY_F0 Function keys; space for 64 keys
75 is reserved.
76 KEY_F(n) For 0 ≤ n ≤ 63
77 KEY_DL Delete line
78 KEY_IL Insert line
79 KEY_DC Delete character
80 KEY_IC Insert char or enter insert mode
81 KEY_EIC Exit insert char mode
82 KEY_CLEAR Clear screen
83 KEY_EOS Clear to end of screen
84 KEY_EOL Clear to end of line
85 KEY_SF Scroll 1 line forward
86 KEY_SR Scroll 1 line backward (reverse)
87 KEY_NPAGE Next page
88 KEY_PPAGE Previous page
89 KEY_STAB Set tab
90 KEY_CTAB Clear tab
91 KEY_CATAB Clear all tabs
92 KEY_ENTER Enter or send
93 KEY_SRESET Soft (partial) reset
94 KEY_RESET Reset or hard reset
95 KEY_PRINT Print or copy
96 KEY_LL Home down or bottom (lower left)
97 KEY_A1 Upper left of keypad
98 KEY_A3 Upper right of keypad
99 KEY_B2 Center of keypad
100 KEY_C1 Lower left of keypad
101 KEY_C3 Lower right of keypad
102 KEY_BTAB Back tab key
103 KEY_BEG Beg(inning) key
104 KEY_CANCEL Cancel key
105 KEY_CLOSE Close key
106 KEY_COMMAND Cmd (command) key
107 KEY_COPY Copy key
108 KEY_CREATE Create key
109 KEY_END End key
110 KEY_EXIT Exit key
111 KEY_FIND Find key
112 KEY_HELP Help key
113 KEY_MARK Mark key
114 KEY_MESSAGE Message key
115 KEY_MOUSE Mouse event read
116 KEY_MOVE Move key
117 KEY_NEXT Next object key
118 KEY_OPEN Open key
119 KEY_OPTIONS Options key
120 KEY_PREVIOUS Previous object key
121 KEY_REDO Redo key
122 KEY_REFERENCE Ref(erence) key
123 KEY_REFRESH Refresh key
124 KEY_REPLACE Replace key
125 KEY_RESIZE Screen resized
126 KEY_RESTART Restart key
127 KEY_RESUME Resume key
128 KEY_SAVE Save key
129 KEY_SBEG Shifted beginning key
130 KEY_SCANCEL Shifted cancel key
131 KEY_SCOMMAND Shifted command key
132 KEY_SCOPY Shifted copy key
134 KEY_SCREATE Shifted create key
135 KEY_SDC Shifted delete char key
136 KEY_SDL Shifted delete line key
137 KEY_SELECT Select key
138 KEY_SEND Shifted end key
139 KEY_SEOL Shifted clear line key
140 KEY_SEXIT Shifted exit key
141 KEY_SFIND Shifted find key
142 KEY_SHELP Shifted help key
143 KEY_SHOME Shifted home key
144 KEY_SIC Shifted input key
145 KEY_SLEFT Shifted left arrow key
146 KEY_SMESSAGE Shifted message key
147 KEY_SMOVE Shifted move key
148 KEY_SNEXT Shifted next key
149 KEY_SOPTIONS Shifted options key
150 KEY_SPREVIOUS Shifted prev key
151 KEY_SPRINT Shifted print key
152 KEY_SREDO Shifted redo key
153 KEY_SREPLACE Shifted replace key
154 KEY_SRIGHT Shifted right arrow
155 KEY_SRSUME Shifted resume key
156 KEY_SSAVE Shifted save key
157 KEY_SSUSPEND Shifted suspend key
158 KEY_SUNDO Shifted undo key
159 KEY_SUSPEND Suspend key
160 KEY_UNDO Undo key
161 Keypad is arranged like this:
163 ┌─────┬──────┬───────┐
166 │ A1 │ up │ A3 │
167 ├─────┼──────┼───────┤
168 │left │ B2 │ right │
169 ├─────┼──────┼───────┤
170 │ C1 │ down │ C3 │
171 └─────┴──────┴───────┘
172 The has_key routine takes a key value from the above list, and returns
173 TRUE or FALSE according to whether the current terminal type recognizes
174 a key with that value. Note that a few values do not correspond to a
175 real key, e.g., KEY_RESIZE and KEY_MOUSE. See resizeterm(3X) for more
176 details about KEY_RESIZE, and curs_mouse(3X) for a discussion of
177 KEY_MOUSE.
178
180 All routines return the integer ERR upon failure and an integer value
181 other than ERR (OK in the case of ungetch()) upon successful comple‐
182 tion.
183 ungetch
185 returns ERR if there is no more room in the FIFO.
186 wgetch
188 returns ERR if the window pointer is null, or if its timeout
189 expires without having any data.
190 Functions with a "mv" prefix first perform a cursor movement using
192 wmove, and return an error if the position is outside the window, or if
193 the window pointer is null.
194
196 Use of the escape key by a programmer for a single character function
197 is discouraged, as it will cause a delay of up to one second while the
198 keypad code looks for a following function-key sequence.
199 Note that some keys may be the same as commonly used control keys,
201 e.g., KEY_ENTER versus control/M, KEY_BACKSPACE versus control/H. Some
202 curses implementations may differ according to whether they treat these
203 control keys specially (and ignore the terminfo), or use the terminfo
204 definitions. Ncurses uses the terminfo definition. If it says that
205 KEY_ENTER is control/M, getch will return KEY_ENTER when you press con‐
206 trol/M.
207 Generally, KEY_ENTER denotes the character(s) sent by the Enter key on
209 the numeric keypad:
210 · the terminal description lists the most useful keys,
212 · the Enter key on the regular keyboard is already handled by the
214 standard ASCII characters for carriage-return and line-feed,
215 · depending on whether nl or nonl was called, pressing "Enter" on the
217 regular keyboard may return either a carriage-return or line-feed,
218 and finally
219 · "Enter or send" is the standard description for this key.
221 When using getch, wgetch, mvgetch, or mvwgetch, nocbreak mode
223 (nocbreak) and echo mode (echo) should not be used at the same time.
224 Depending on the state of the tty driver when each character is typed,
225 the program may produce undesirable results.
226 Note that getch, mvgetch, and mvwgetch may be macros.
228 Historically, the set of keypad macros was largely defined by the ex‐
230 tremely function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Sa‐
231 fari 4. Modern personal computers usually have only a small subset of
232 these. IBM PC-style consoles typically support little more than
233 KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END, KEY_NPAGE,
234 KEY_PPAGE, and function keys 1 through 12. The Ins key is usually
235 mapped to KEY_IC.
236
238 The *get* functions are described in the XSI Curses standard, Issue 4.
239 They read single-byte characters only. The standard specifies that
240 they return ERR on failure, but specifies no error conditions.
241 The echo behavior of these functions on input of KEY_ or backspace
243 characters was not specified in the SVr4 documentation. This descrip‐
244 tion is adopted from the XSI Curses standard.
245 The behavior of getch and friends in the presence of handled signals is
247 unspecified in the SVr4 and XSI Curses documentation. Under historical
248 curses implementations, it varied depending on whether the operating
249 system's implementation of handled signal receipt interrupts a read(2)
250 call in progress or not, and also (in some implementations) depending
251 on whether an input timeout or non-blocking mode has been set.
252 Programmers concerned about portability should be prepared for either
254 of two cases: (a) signal receipt does not interrupt getch; (b) signal
255 receipt interrupts getch and causes it to return ERR with errno set to
256 EINTR. Under the ncurses implementation, handled signals never inter‐
257 rupt getch.
258 The has_key function is unique to ncurses. We recommend that any code
260 using it be conditionalized on the NCURSES_VERSION feature macro.
261
263 curses(3X), curs_inopts(3X), curs_outopts(3X), curs_mouse(3X),
264 curs_move(3X), curs_refresh(3X), resizeterm(3X).
265 Comparable functions in the wide-character (ncursesw) library are de‐
267 scribed in curs_get_wch(3X).
268 curs_getch(3X)