1curs_getch(3X)                                                  curs_getch(3X)
2
3
4

NAME

6       getch, wgetch, mvgetch, mvwgetch, ungetch, has_key - get (or push back)
7       characters from curses terminal keyboard
8

SYNOPSIS

10       #include <curses.h>
11
12       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

DESCRIPTION

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
28       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
36       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
40       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
47       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
55       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
59   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
64
65                  Name            Key name
66
67                  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
133                  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
162       Keypad is arranged like this:
163
164
165                                ┌─────┬──────┬───────┐
166A1  up  A3   
167                                ├─────┼──────┼───────┤
168left B2  right 
169                                ├─────┼──────┼───────┤
170C1  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

RETURN VALUE

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
184          ungetch
185               returns ERR if there is no more room in the FIFO.
186
187          wgetch
188               returns  ERR  if  the window pointer is null, or if its timeout
189               expires without having any data.
190
191       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

NOTES

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
200       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
208       Generally, KEY_ENTER denotes the character(s) sent by the Enter key  on
209       the numeric keypad:
210
211       ·   the terminal description lists the most useful keys,
212
213       ·   the  Enter  key  on  the regular keyboard is already handled by the
214           standard ASCII characters for carriage-return and line-feed,
215
216       ·   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
220       ·   "Enter or send" is the standard description for this key.
221
222       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
227       Note that getch, mvgetch, and mvwgetch may be macros.
228
229       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

PORTABILITY

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
242       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
246       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
253       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
259       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

SEE ALSO

263       curses(3X),    curs_inopts(3X),    curs_outopts(3X),    curs_mouse(3X),
264       curs_move(3X), curs_refresh(3X), resizeterm(3X).
265
266       Comparable functions in the wide-character (ncursesw) library  are  de‐
267       scribed in curs_get_wch(3X).
268
269
270
271                                                                curs_getch(3X)
Impressum