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 an error if there is no more room in the FIFO.
186 wgetch
188 returns an error if the window pointer is null, or if its
189 timeout expires without having any data.
190
192 Use of the escape key by a programmer for a single character function
193 is discouraged, as it will cause a delay of up to one second while the
194 keypad code looks for a following function-key sequence.
195 Note that some keys may be the same as commonly used control keys,
197 e.g., KEY_ENTER versus control/M, KEY_BACKSPACE versus control/H. Some
198 curses implementations may differ according to whether they treat these
199 control keys specially (and ignore the terminfo), or use the terminfo
200 definitions. Ncurses uses the terminfo definition. If it says that
201 KEY_ENTER is control/M, getch will return KEY_ENTER when you press con‐
202 trol/M.
203 When using getch, wgetch, mvgetch, or mvwgetch, nocbreak mode
205 (nocbreak) and echo mode (echo) should not be used at the same time.
206 Depending on the state of the tty driver when each character is typed,
207 the program may produce undesirable results.
208 Note that getch, mvgetch, and mvwgetch may be macros.
210 Historically, the set of keypad macros was largely defined by the ex‐
212 tremely function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Sa‐
213 fari 4. Modern personal computers usually have only a small subset of
214 these. IBM PC-style consoles typically support little more than
215 KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END, KEY_NPAGE,
216 KEY_PPAGE, and function keys 1 through 12. The Ins key is usually
217 mapped to KEY_IC.
218
220 The *get* functions are described in the XSI Curses standard, Issue 4.
221 They read single-byte characters only. The standard specifies that
222 they return ERR on failure, but specifies no error conditions.
223 The echo behavior of these functions on input of KEY_ or backspace
225 characters was not specified in the SVr4 documentation. This descrip‐
226 tion is adopted from the XSI Curses standard.
227 The behavior of getch and friends in the presence of handled signals is
229 unspecified in the SVr4 and XSI Curses documentation. Under historical
230 curses implementations, it varied depending on whether the operating
231 system's implementation of handled signal receipt interrupts a read(2)
232 call in progress or not, and also (in some implementations) depending
233 on whether an input timeout or non-blocking mode has been set.
234 Programmers concerned about portability should be prepared for either
236 of two cases: (a) signal receipt does not interrupt getch; (b) signal
237 receipt interrupts getch and causes it to return ERR with errno set to
238 EINTR. Under the ncurses implementation, handled signals never inter‐
239 rupt getch.
240 The has_key function is unique to ncurses. We recommend that any code
242 using it be conditionalized on the NCURSES_VERSION feature macro.
243
245 curses(3X), curs_inopts(3X), curs_mouse(3X), curs_move(3X), curs_re‐
246 fresh(3X), resizeterm(3X).
247 Comparable functions in the wide-character (ncursesw) library are de‐
249 scribed in curs_get_wch(3X).
250 curs_getch(3X)