'\" t
.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getch.3x,v 1.67 2023/07/01 15:43:20 tom Exp $
-.TH curs_getch 3X 2023-07-01 "ncurses 6.4" "Library calls"
-.na
-.hy 0
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_getch.3x,v 1.78 2024/02/17 19:27:03 tom Exp $
+.TH curs_getch 3X 2024-02-17 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
.SH NAME
-\fBgetch\fP,
-\fBwgetch\fP,
-\fBmvgetch\fP,
-\fBmvwgetch\fP,
-\fBungetch\fP,
-\fBhas_key\fP \- get (or push back) characters from \fBcurses\fP terminal keyboard
-.ad
-.hy
+\fB\%getch\fP,
+\fB\%wgetch\fP,
+\fB\%mvgetch\fP,
+\fB\%mvwgetch\fP,
+\fB\%ungetch\fP,
+\fB\%has_key\fP \-
+get (or push back) characters from \fIcurses\fR terminal keyboard
.SH SYNOPSIS
+.nf
.B #include <curses.h>
.PP
.B int getch(void);
-.br
-.B int wgetch(WINDOW *\fIwin\fB);
-.sp
-.B int mvgetch(int \fIy\fB, int \fIx\fB);
-.br
-.B int mvwgetch(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);
-.sp
-.B int ungetch(int \fIch\fB);
-.sp
-/* extension */
-.br
-.B int has_key(int \fIch\fB);
-.br
+.B int wgetch(WINDOW *\fIwin\fP);
+.B int mvgetch(int \fIy\fP, int \fIx\fP);
+.B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.PP
+.B int ungetch(int \fIch\fP);
+.PP
+\fI/* extension */\fP
+.B int has_key(int \fIch\fP);
+.fi
.SH DESCRIPTION
-.SS Reading characters
+.SS "Reading Characters"
The \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP and \fBmvwgetch\fP, routines read
a character from the window.
In no-delay mode, if no input is waiting, the value \fBERR\fP is returned.
If the window is not a pad, and it has been moved or modified since the last
call to \fBwrefresh\fP, \fBwrefresh\fP will be called before another character
is read.
-.SS Keypad mode
+.SS "Keypad Mode"
If \fBkeypad\fP is \fBTRUE\fP, and a function key is pressed, the token for
that function key is returned instead of the raw characters:
.bP
For this reason, many terminals experience a delay between the time
a user presses the escape key and the escape is returned to the program.
.PP
-In \fBncurses\fP, the timer normally expires after
+In \fI\%ncurses\fP, the timer normally expires after
the value in \fBESCDELAY\fP (see \fBcurs_variables\fP(3X)).
If \fBnotimeout\fP is \fBTRUE\fP, the timer does not expire;
it is an infinite (or very large) value.
Because function keys usually begin with an escape character,
the terminal may appear to hang in notimeout mode after pressing the escape key
until another key is pressed.
-.SS Ungetting characters
+.SS "Ungetting Characters"
The \fBungetch\fP routine places \fIch\fP back onto the input queue to be
returned by the next call to \fBwgetch\fP.
There is just one input queue for all windows.
-.SS Predefined key-codes
+.SS "Predefined Key Codes"
The following special keys are defined in \fB<curses.h>\fP.
.bP
Except for the special case \fBKEY_RESIZE\fP,
The names correspond to the long terminfo capability names for the keys,
and were defined long ago, in the 1980s.
.PP
+.RS
.TS
-center tab(/) ;
+tab(/) ;
l l .
\fBName\fP/\fBKey\fP \fBname\fP
_
KEY_SUSPEND/Suspend key
KEY_UNDO/Undo key
.TE
+.RE
.PP
Keypad is arranged like this:
-.br
+.PP
+.RS
.TS
-center allbox tab(/) ;
+allbox tab(/) ;
c c c .
\fBA1\fP/\fBup\fP/\fBA3\fP
\fBleft\fP/\fBB2\fP/\fBright\fP
\fBC1\fP/\fBdown\fP/\fBC3\fP
.TE
+.RE
.sp
A few of these predefined values do \fInot\fP correspond to a real key:
.bP
.B KEY_MOUSE
is returned for mouse-events (see \fBcurs_mouse\fP(3X)).
This code relies upon whether or not \fBkeypad\fP(3X) has been enabled,
-because (e.g., with \fBxterm\fP(1) mouse prototocol) ncurses must
-read escape sequences,
+because
+(e.g.,
+with \fBxterm\fP(1) mouse prototocol)
+\fI\%ncurses\fP must read escape sequences,
just like a function key.
-.SS Testing key-codes
+.SS "Testing Key Codes"
The \fBhas_key\fP routine takes a key-code value from the above list, and
returns \fBTRUE\fP or \fBFALSE\fP according to whether
the current terminal type recognizes a key with that value.
.TP
\fBwgetch\fP
returns \fBERR\fP
+.RS
+.bP
if the window pointer is null, or
+.bP
if its timeout expires without having any data, or
+.bP
if the execution was interrupted by a signal (\fBerrno\fP will be set to
\fBEINTR\fP).
.RE
+.RE
.PP
Functions with a \*(``mv\*('' prefix first perform a cursor movement using
\fBwmove\fP, and return an error if the position is outside the window,
Some curses implementations may differ according to whether they
treat these control keys specially (and ignore the terminfo), or
use the terminfo definitions.
-\fBNcurses\fP uses the terminfo definition.
+\fI\%ncurses\fP uses the terminfo definition.
If it says that \fBKEY_ENTER\fP is control/M,
\fBgetch\fP will return \fBKEY_ENTER\fP
when you press control/M.
\fBKEY_NPAGE\fP, \fBKEY_PPAGE\fP, and function keys 1 through 12.
The Ins key
is usually mapped to \fBKEY_IC\fP.
+.SH EXTENSIONS
+\fB\%has_key\fP was designed for \fB\%ncurses\fP(3X),
+and is not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous curses implementation.
.SH PORTABILITY
-The *get* functions are described in the XSI Curses standard, Issue 4.
-They
-read single-byte characters only.
-The standard specifies that they return
-\fBERR\fP on failure, but specifies no error conditions.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
.PP
-The echo behavior of these functions on input of \fBKEY_\fP or backspace
-characters was not specified in the SVr4 documentation.
-This description is
-adopted from the XSI Curses standard.
+X/Open Curses, Issue 4, Version 2, describes
+\fB\%getch\fP,
+\fB\%wgetch\fP,
+\fB\%mvgetch\fP,
+\fB\%mvwgetch\fP,
+and
+\fB\%ungetch\fP.
+They read single-byte characters only.
+The standard specifies that they return \fBERR\fP on failure,
+but describes no failure conditions.
.PP
-The behavior of \fBgetch\fP and friends in the presence of handled signals is
-unspecified in the SVr4 and XSI Curses documentation.
-Under historical curses
-implementations, it varied depending on whether the operating system's
-implementation of handled signal receipt interrupts a \fBread\fP(2) call in
-progress or not, and also (in some implementations) depending on whether an
-input timeout or non-blocking mode has been set.
+The echo behavior of these functions on input of
+.B KEY_
+or backspace characters was not specified in the SVr4 documentation.
+This description is adapted from X/Open Curses.
.PP
-\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related
-terminfo capabilities, but no higher-level functions use the feature.
-The implementation in ncurses is an extension.
+The behavior of \fBgetch\fP and friends in the presence of signal
+handlers is unspecified in the SVr4 documentation and X/Open Curses.
+Under historical curses implementations,
+it varied depending on whether the operating system's dispatch of a
+signal to a handler interrupts a \fBread\fP(2) call in progress or not,
+and also
+(in some implementations)
+whether an input timeout or non-blocking mode has been set.
.PP
-\fBKEY_RESIZE\fP is an extension first implemented for ncurses.
-NetBSD curses later added this extension.
+.B KEY_MOUSE
+is mentioned in X/Open Curses,
+along with a few related
+.I \%term\%info
+capabilities,
+but no higher-level functions use the feature.
+The implementation in
+.I \%ncurses
+is an extension.
+.PP
+.B KEY_RESIZE
+is an extension first implemented for
+.I \%ncurses.
+NetBSD
+.I curses
+later added this extension.
.PP
Programmers concerned about portability should be prepared for either of two
cases: (a) signal receipt does not interrupt \fBgetch\fP; (b) signal receipt
interrupts \fBgetch\fP and causes it to return \fBERR\fP with \fBerrno\fP set to
\fBEINTR\fP.
.PP
-The \fBhas_key\fP function is unique to \fBncurses\fP.
+The \fBhas_key\fP function is unique to \fI\%ncurses\fP.
We recommend that
any code using it be conditionalized on the \fBNCURSES_VERSION\fP feature macro.
.SH SEE ALSO
-\fBcurses\fP(3X),
-\fBcurs_inopts\fP(3X),
-\fBcurs_mouse\fP(3X),
-\fBcurs_move\fP(3X),
-\fBcurs_outopts\fP(3X),
-\fBcurs_refresh\fP(3X),
-\fBcurs_variables\fP(3X),
-\fBresizeterm\fP(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_inopts\fP(3X),
+\fB\%curs_mouse\fP(3X),
+\fB\%curs_move\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_variables\fP(3X),
+\fB\%resizeterm\fP(3X)
.PP
Comparable functions in the wide-character (ncursesw) library are
described in
-\fBcurs_get_wch\fP(3X).
+\fB\%curs_get_wch\fP(3X).
projects / ncurses.git / blobdiff