]> ncurses.scripts.mit.edu Git - ncurses.git/blob - man/curs_getch.3x
9433c6148583bcc421f253134e28cd27e2ea7e54
[ncurses.git] / man / curs_getch.3x
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
4 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
5 .\"                                                                          *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
7 .\" copy of this software and associated documentation files (the            *
8 .\" "Software"), to deal in the Software without restriction, including      *
9 .\" without limitation the rights to use, copy, modify, merge, publish,      *
10 .\" distribute, distribute with modifications, sublicense, and/or sell       *
11 .\" copies of the Software, and to permit persons to whom the Software is    *
12 .\" furnished to do so, subject to the following conditions:                 *
13 .\"                                                                          *
14 .\" The above copyright notice and this permission notice shall be included  *
15 .\" in all copies or substantial portions of the Software.                   *
16 .\"                                                                          *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
24 .\"                                                                          *
25 .\" Except as contained in this notice, the name(s) of the above copyright   *
26 .\" holders shall not be used in advertising or otherwise to promote the     *
27 .\" sale, use or other dealings in this Software without prior written       *
28 .\" authorization.                                                           *
29 .\"***************************************************************************
30 .\"
31 .\" $Id: curs_getch.3x,v 1.87 2024/04/20 19:18:18 tom Exp $
32 .TH curs_getch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
33 .ie \n(.g \{\
34 .ds `` \(lq
35 .ds '' \(rq
36 .ds ^  \(ha
37 .\}
38 .el \{\
39 .ie t .ds `` ``
40 .el   .ds `` ""
41 .ie t .ds '' ''
42 .el   .ds '' ""
43 .ds       ^  ^
44 .\}
45 .
46 .ie \n(.g .ds : \:
47 .el       .ds : \" empty
48 .
49 .de bP
50 .ie n  .IP \(bu 4
51 .el    .IP \(bu 2
52 ..
53 .SH NAME
54 \fB\%getch\fP,
55 \fB\%wgetch\fP,
56 \fB\%mvgetch\fP,
57 \fB\%mvwgetch\fP,
58 \fB\%ungetch\fP,
59 \fB\%has_key\fP \-
60 get (or push back) characters from \fIcurses\fR terminal keyboard
61 .SH SYNOPSIS
62 .nf
63 .B #include <curses.h>
64 .PP
65 .B int getch(void);
66 .B int wgetch(WINDOW *\fIwin\fP);
67 .B int mvgetch(int \fIy\fP, int \fIx\fP);
68 .B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
69 .PP
70 .B int ungetch(int \fIc\fP);
71 .PP
72 .\" XXX: Move has_key into its own page like define_key and key_defined?
73 \fI/* extension */\fP
74 .B int has_key(int \fIc\fP);
75 .fi
76 .SH DESCRIPTION
77 .SS "Reading Characters"
78 .B \%wgetch
79 gathers a key stroke from the terminal keyboard associated with a
80 .I curses
81 window
82 .IR win .
83 \fB\%ncurses\fP(3X) describes the variants of this function.
84 .PP
85 When input is pending,
86 .B \%wgetch
87 returns an integer identifying the key stroke;
88 for alphanumeric and punctuation keys,
89 this value corresponds to the character encoding used by the terminal.
90 Use of the control key as a modifier often results in a distinct code.
91 The behavior of other keys depends on whether
92 .I win
93 is in keypad mode;
94 see subsection \*(``Keypad Mode\*('' below.
95 .PP
96 If no input is pending,
97 then if the no-delay flag is set in the window
98 (see \fB\%nodelay\fP(3X)),
99 the function returns
100 .BR ERR ;
101 otherwise,
102 .I curses
103 waits until the terminal has input.
104 If \fB\%cbreak\fP(3X)
105 has been called,
106 this happens after one character is read.
107 If \fB\%nocbreak\fP(3X)
108 has been called,
109 it occurs when the next newline is read.
110 If \fB\%halfdelay\fP(3X)
111 has been called,
112 .I curses
113 waits until a character is typed or the specified delay elapses.
114 .PP
115 If \fB\%echo\fP(3X) has been called,
116 and the window is not a pad,
117 .I curses
118 writes the returned character
119 .I c
120 to the window
121 (at the cursor position)
122 per the following rules.
123 .bP
124 If
125 .I c
126 matches the terminal's erase character,
127 the cursor moves leftward one position
128 and the new position is erased
129 as if \fB\%wmove\fP(3X) and then \fB\%wdelch\fP(3X) were called.
130 When the window's keypad mode is enabled
131 (see below),
132 .B \%KEY_LEFT
133 and
134 .B \%KEY_BACKSPACE
135 are handled the same way.
136 .bP
137 .I curses
138 writes any other
139 .I c
140 to the window,
141 as with \fB\%wechochar\fP(3X).
142 .bP
143 If the window has been moved or modified since the last call to
144 \fB\%wrefresh\fP(3X),
145 .I curses
146 calls
147 .BR \%wrefresh .
148 .PP
149 If
150 .I c
151 is a carriage return and \fBnl\fP(3X) has been called,
152 .B \%wgetch
153 returns the character code for line feed instead.
154 .SS "Keypad Mode"
155 To
156 .IR curses ,
157 key strokes not from the alphabetic section of the keyboard
158 (those corresponding to the ECMA-6 character set\(emsee
159 \fIascii\fP(7)\(emoptionally modified by either the control or shift
160 keys)
161 are treated as
162 .I function
163 keys.
164 (In
165 .IR curses ,
166 the term \*(``function key\*('' includes but is not limited to keycaps
167 engraved with \*(``F1\*('',
168 \*(``PF1\*('',
169 and so on.)
170 If the window is in keypad mode,
171 these produce a numeric code corresponding to the
172 .B KEY_
173 symbols listed in subsection \*(``Predefined Key Codes\*('' below;
174 otherwise,
175 they transmit a sequence of codes typically starting with the escape
176 character,
177 and which must be collected with multiple
178 .B \%wgetch
179 calls.
180 .bP
181 The
182 .I \%curses.h
183 header file declares many
184 .I "predefined function keys"
185 whose names begin with
186 .BR KEY_ ;
187 these object-like macros have values outside the range of eight-bit
188 character codes.
189 .bP
190 In
191 .IR \%ncurses ,
192 .I "user-defined function keys"
193 are configured with \fB\%define_key\fP(3X);
194 they have no names,
195 but are also expected to have values outside the range of eight-bit
196 codes.
197 .PP
198 A variable intended to hold a function key code must thus be of type
199 .I short
200 or larger.
201 .PP
202 Most terminals one encounters follow the ECMA-48 standard insofar as
203 their function keys produce character sequences prefixed with the
204 escape character ESC.
205 This fact implies that
206 .I curses
207 cannot know whether the terminal has sent an ESC key stroke or the
208 beginning of a function key's character sequence without waiting to see
209 if,
210 and how soon,
211 further input arrives.
212 When
213 .I curses
214 reads such an ambiguous character,
215 it sets a timer.
216 If the remainder of the sequence does not arrive within the designated
217 time,
218 .B \%wgetch
219 returns the prefix character;
220 otherwise,
221 it returns the function key code corresponding to the unique sequence
222 defined by the terminal.
223 Consequently,
224 a user of a
225 .I curses
226 application may experience a delay after pressing ESC while
227 .I curses
228 disambiguates the input;
229 see section \*(``EXTENSIONS\*('' below.
230 If the window is in \*(``no time-out\*('' mode,
231 the timer does not expire;
232 it is an infinite
233 (or very large)
234 value.
235 See \fB\%notimeout\fP(3X).
236 Because function key sequences usually begin with an escape character,
237 the terminal may appear to hang in no time-out mode after the user has
238 pressed ESC.
239 Generally,
240 further typing \*(``awakens\*(''
241 .IR curses .
242 .SS "Ungetting Characters"
243 .B \%ungetch
244 places
245 .I c
246 into the input queue to be returned by the next call to
247 .BR \%wgetch .
248 A single input queue serves all windows.
249 .SS "Predefined Key Codes"
250 The header file
251 .I \%curses.h
252 defines the following function key codes.
253 .bP
254 Except for the special case of
255 .BR \%KEY_RESIZE ,
256 a window's keypad mode must be enabled for
257 .B \%wgetch
258 to read these codes from it.
259 .bP
260 Not all of these are necessarily supported on any particular terminal.
261 .bP
262 The naming convention may seem obscure,
263 with some apparent misspellings
264 (such as \*(``RSUME\*('' for \*(``resume\*('');
265 the names correspond to the
266 .I \%term\%info
267 capability names for the keys,
268 and were standardized before the IBM PC/AT keyboard layout achieved a
269 dominant position in industry.
270 .PP
271 .RS
272 .\" XXX: Move this list into ncurses(3X), rather than duplicating it in
273 .\" get_wch(3X) or having that page cross reference this one?
274 .TS
275 Lb Lb
276 Lb Lx.
277 Symbol  Key name
278 =
279 KEY_BREAK       Break key
280 KEY_DOWN        Arrow keys
281 KEY_UP  \^
282 KEY_LEFT        \^
283 KEY_RIGHT       \^
284 KEY_HOME        Home key (upward+left arrow)
285 KEY_BACKSPACE   Backspace
286 KEY_F0  T{
287 Function keys; space for 64 keys is reserved
288 T}
289 KEY_F(\fIn\fP)  T{
290 Function key \fIn\fP where 0 \(<= \fIn\fP \(<= 63
291 T}
292 KEY_DL  Delete line
293 KEY_IL  Insert line
294 KEY_DC  Delete character
295 KEY_IC  Insert character/Enter insert mode
296 KEY_EIC Exit insert character mode
297 KEY_CLEAR       Clear screen
298 KEY_EOS Clear to end of screen
299 KEY_EOL Clear to end of line
300 KEY_SF  Scroll one line forward
301 KEY_SR  Scroll one line backward (reverse)
302 KEY_NPAGE       Next page/Page up
303 KEY_PPAGE       Previous page/Page down
304 KEY_STAB        Set tab
305 KEY_CTAB        Clear tab
306 KEY_CATAB       Clear all tabs
307 KEY_ENTER       Enter/Send
308 KEY_SRESET      Soft (partial) reset
309 KEY_RESET       (Hard) reset
310 KEY_PRINT       Print/Copy
311 KEY_LL  Home down/Bottom (lower left)
312 KEY_A1  Upper left of keypad
313 KEY_A3  Upper right of keypad
314 KEY_B2  Center of keypad
315 KEY_C1  Lower left of keypad
316 KEY_C3  Lower right of keypad
317 KEY_BTAB        Back tab key
318 KEY_BEG Beg(inning) key
319 KEY_CANCEL      Cancel key
320 KEY_CLOSE       Close key
321 KEY_COMMAND     Cmd (command) key
322 KEY_COPY        Copy key
323 KEY_CREATE      Create key
324 KEY_END End key
325 KEY_EXIT        Exit key
326 KEY_FIND        Find key
327 KEY_HELP        Help key
328 KEY_MARK        Mark key
329 KEY_MESSAGE     Message key
330 KEY_MOUSE       Mouse event occurred
331 KEY_MOVE        Move key
332 KEY_NEXT        Next object key
333 KEY_OPEN        Open key
334 KEY_OPTIONS     Options key
335 KEY_PREVIOUS    Previous object key
336 KEY_REDO        Redo key
337 KEY_REFERENCE   Ref(erence) key
338 KEY_REFRESH     Refresh key
339 KEY_REPLACE     Replace key
340 KEY_RESIZE      Screen resized
341 KEY_RESTART     Restart key
342 KEY_RESUME      Resume key
343 KEY_SAVE        Save key
344 KEY_SELECT      Select key
345 KEY_SUSPEND     Suspend key
346 KEY_UNDO        Undo key
347 _
348 KEY_SBEG        Shifted beginning key
349 KEY_SCANCEL     Shifted cancel key
350 KEY_SCOMMAND    Shifted command key
351 KEY_SCOPY       Shifted copy key
352 KEY_SCREATE     Shifted create key
353 KEY_SDC Shifted delete character key
354 KEY_SDL Shifted delete line key
355 KEY_SEND        Shifted end key
356 KEY_SEOL        Shifted clear line key
357 KEY_SEXIT       Shifted exit key
358 KEY_SFIND       Shifted find key
359 KEY_SHELP       Shifted help key
360 KEY_SHOME       Shifted home key
361 KEY_SIC Shifted insert key
362 KEY_SLEFT       Shifted left arrow key
363 KEY_SMESSAGE    Shifted message key
364 KEY_SMOVE       Shifted move key
365 KEY_SNEXT       Shifted next object key
366 KEY_SOPTIONS    Shifted options key
367 KEY_SPREVIOUS   Shifted previous object key
368 KEY_SPRINT      Shifted print key
369 KEY_SREDO       Shifted redo key
370 KEY_SREPLACE    Shifted replace key
371 KEY_SRIGHT      Shifted right arrow key
372 KEY_SRSUME      Shifted resume key
373 KEY_SSAVE       Shifted save key
374 KEY_SSUSPEND    Shifted suspend key
375 KEY_SUNDO       Shifted undo key
376 .TE
377 .RE
378 .PP
379 Many keyboards feature a nine-key directional pad.
380 .PP
381 .RS
382 .TS
383 allbox center;
384 C C C.
385 A1      up      A3
386 left    B2      right
387 C1      down    C3
388 .TE
389 .RE
390 .sp
391 Two of the symbols in the list above do
392 .I not
393 correspond to a physical key.
394 .bP
395 .B \%wgetch
396 returns
397 .BR \%KEY_RESIZE ,
398 even if the window's keypad mode is disabled,
399 when
400 .I \%ncurses
401 handles a
402 .B \%SIGWINCH
403 signal;
404 see \fB\%initscr\fP(3X) and \fB\%resizeterm\fP(3X).
405 .bP
406 .B \%wgetch
407 returns
408 .B \%KEY_MOUSE
409 to indicate that a mouse event is pending collection;
410 see \fB\%curs_mouse\fP(3X).
411 Receipt of this code requires a window's keypad mode to be enabled,
412 because to interpret mouse input
413 (as with with \fI\%xterm\fP(1)'s mouse prototocol),
414 .I \%ncurses
415 must read an escape sequence,
416 as with a function key.
417 .SS "Testing Key Codes"
418 In
419 .IR \%ncurses ,
420 .B \%has_key
421 returns a Boolean value indicating whether the terminal type recognizes
422 its parameter as a key code value.
423 See also
424 \fB\%define_key\fP(3X) and \fB\%key_defined\fP(3X).
425 .SH RETURN VALUE
426 Except for
427 .BR \%has_key ,
428 these functions return
429 .B OK
430 on success and
431 .B ERR
432 on failure.
433 .PP
434 Functions taking a
435 .I \%WINDOW
436 pointer argument fail if the pointer is
437 .BR NULL .
438 .PP
439 Functions prefixed with \*(``mv\*('' first perform cursor movement and
440 fail if the position
441 .RI ( y ,
442 .IR x )
443 is outside the window boundaries.
444 .PP
445 .B \%wgetch
446 also fails if
447 .bP
448 its timeout expires without any data arriving,
449 or
450 .bP
451 execution was interrupted by a signal,
452 in which case
453 .B \%errno
454 is set to
455 .BR \%EINTR .
456 .PP
457 .B \%ungetch
458 fails if there is no more room in the input queue.
459 .PP
460 .B \%has_key
461 returns
462 .B TRUE
463 or
464 .BR FALSE .
465 .SH NOTES
466 .I curses
467 discourages assignment of the ESC key to a discrete function by the
468 programmer because the library requires a delay while it awaits the
469 potential remainder of a terminal escape sequence.
470 .PP
471 Some key strokes are indistinguishable from control characters;
472 for example,
473 .B \%KEY_ENTER
474 may be the same as
475 .BR \*^M ,
476 .\" as with att630 or pccon+keys
477 and
478 .B \%KEY_BACKSPACE
479 may be the same as
480 .B \*^H
481 .\" as with att505 or vt52-basic
482 or
483 .BR \*^? .
484 .\" as with pccon+keys or vt320
485 Consult the terminal's
486 .I \%term\%info
487 entry to determine whether this is the case;
488 see \fB\%infocmp\fP(1).
489 Some
490 .I curses
491 implementations,
492 including
493 .IR \%ncurses ,
494 honor the
495 .I \%term\%info
496 key definitions;
497 others treat such control characters specially.
498 .PP
499 .I curses
500 distinguishes the Enter keys in the alphabetic and numeric keypad
501 sections of a keyboard because (most) terminals do.
502 .B \%KEY_ENTER
503 refers to the key on the numeric keypad and,
504 like other function keys,
505 and is reliably recognized only if the window's keypad mode is enabled.
506 .bP
507 The
508 .I \%term\%info
509 .B \%key_enter
510 .RB ( kent )
511 capability describes the character (sequence) sent by the Enter key of
512 a terminal's numeric
513 (or similar)
514 keypad.
515 .bP
516 \*(``Enter or send\*('' is X/Open Curses's description of this key.
517 .PP
518 .I curses
519 treats the Enter or Return key in the
520 .I alphabetic
521 section of the keyboard differently.
522 .bP
523 It usually produces a control code for carriage return
524 .RB ( \*^M )
525 or line feed
526 .RB ( \*^J ).
527 .bP
528 Depending on the terminal mode
529 (raw,
530 cbreak,
531 or
532 \*(``cooked\*(''),
533 and whether \fB\%nl\fP(3X) or \fB\%nonl\fP(3X) has been called,
534 .B \%wgetch
535 may return either a carriage return or line feed upon an Enter or Return
536 key stroke.
537 .PP
538 Use of
539 .B \%wgetch
540 with \fB\%echo\fP(3X) and neither \fB\%cbreak\fP(3X) nor \fB\%raw\fP(3X)
541 is not well-defined.
542 .PP
543 Historically,
544 the list of key code macros above was influenced by the
545 function-key-rich keyboard of the AT&T 7300
546 (also known variously as the \*(``3B1\*('', \*(``Safari 4\*('', and
547 \*(``UNIX PC\*(''),
548 a 1985 machine.
549 Today's computer keyboards are based that of the IBM PC/AT and tend to
550 have fewer.
551 A
552 .I curses
553 application can expect such a keyboard to transmit key codes
554 .BR \%KEY_UP ,
555 .BR \%KEY_DOWN ,
556 .BR \%KEY_LEFT ,
557 .BR \%KEY_RIGHT ,
558 .BR \%KEY_HOME ,
559 .BR \%KEY_END ,
560 .B \%KEY_PPAGE
561 (Page Up),
562 .B \%KEY_NPAGE
563 (Page Down),
564 .B \%KEY_IC
565 (Insert),
566 .B \%KEY_DC
567 (Delete),
568 and
569 .BI \%KEY_F( n )
570 for 1 \(<=
571 .I n
572 \(<= 12.
573 .PP
574 .BR \%getch ,
575 .BR \%mvgetch ,
576 and
577 .B \%mvwgetch
578 may be implemented as macros.
579 .SH EXTENSIONS
580 In
581 .IR \%ncurses ,
582 when a window's \*(``no time-out\*('' mode is
583 .I not
584 set,
585 the
586 .B \%ESCDELAY
587 variable configures the duration of the timer used to disambiguate a
588 function key character sequence from a series of key strokes beginning
589 with ESC typed by the user;
590 see
591 \fB\%curs_variables\fP(3X).
592 .PP
593 \fB\%has_key\fP was designed for \fB\%ncurses\fP(3X),
594 and is not found in SVr4
595 .IR curses ,
596 4.4BSD
597 .IR curses ,
598 or any other previous curses implementation.
599 .SH PORTABILITY
600 Applications employing
601 .I \%ncurses
602 extensions should condition their use on the visibility of the
603 .B \%NCURSES_VERSION
604 preprocessor macro.
605 .PP
606 X/Open Curses,
607 Issue 4 describes
608 \fB\%getch\fP,
609 \fB\%wgetch\fP,
610 \fB\%mvgetch\fP,
611 \fB\%mvwgetch\fP,
612 and
613 \fB\%ungetch\fP.
614 It specifies no error conditions for them.
615 .PP
616 .B \%wgetch
617 reads only single-byte characters.
618 .PP
619 The echo behavior of these functions on input of
620 .B KEY_
621 or backspace characters was not specified in the SVr4 documentation.
622 This description is adapted from X/Open Curses.
623 .PP
624 The behavior of
625 .B \%wgetch
626 in the presence of signal handlers is unspecified in the SVr4
627 documentation and X/Open Curses.
628 In historical
629 .I curses
630 implementations,
631 it varied depending on whether the operating system's dispatch of a
632 signal to a handler interrupting a \fIread\fP(2) call in progress,
633 and also
634 (in some implementations)
635 whether an input timeout or non-blocking mode has been set.
636 Programmers concerned about portability should be prepared for either of
637 two cases:
638 (a) signal receipt does not interrupt
639 .BR \%wgetch ;
640 or
641 (b) signal receipt interrupts
642 .B \%wgetch
643 and causes it to return
644 .B ERR
645 with
646 .B \%errno
647 set to
648 .BR \%EINTR .
649 .PP
650 .B \%KEY_MOUSE
651 is mentioned in X/Open Curses,
652 along with a few related
653 .I \%term\%info
654 capabilities,
655 but no higher-level functions use the feature.
656 The implementation in
657 .I \%ncurses
658 is an extension.
659 .PP
660 .B \%KEY_RESIZE
661 and
662 .B \%has_key
663 are extensions first implemented for
664 .IR \%ncurses .
665 By 2022,
666 .I \%PDCurses
667 .\" https://web.archive.org/web/20220117232009/https://pdcurses.org/docs/MANUAL.html
668 and
669 NetBSD
670 .I curses
671 .\" https://web.archive.org/web/20200923185647/https://man.netbsd.org/curses_input.3
672 had added them along with
673 .BR \%KEY_MOUSE .
674 .SH SEE ALSO
675 \fB\%curs_get_wch\fP(3X) describes comparable functions of the
676 .I \%ncurses
677 library in its wide-character configuration
678 .RI ( \%ncursesw ).
679 .PP
680 \fB\%curses\fP(3X),
681 \fB\%curs_addch\fP(3X),
682 \fB\%curs_inopts\fP(3X),
683 \fB\%curs_mouse\fP(3X),
684 \fB\%curs_move\fP(3X),
685 \fB\%curs_outopts\fP(3X),
686 \fB\%curs_refresh\fP(3X),
687 \fB\%curs_variables\fP(3X),
688 \fB\%resizeterm\fP(3X),
689 \fB\%ascii\fP(7)
690 .PP
691 ECMA-6 \*(``7-bit coded Character Set\*(''
692 \%<https://\*:ecma\-international\*:.org/\
693 \*:publications\-and\-standards/\*:standards/\*:ecma\-6/>
694 .PP
695 ECMA-48 \*(``Control Functions for Coded Character Sets\*(''
696 \%<https://\*:ecma\-international\*:.org/\
697 \*:publications\-and\-standards/\*:standards/\*:ecma\-48/>