curs_inopts(3x) Library calls curs_inopts(3x)
cbreak, echo, halfdelay, intrflush, is_cbreak, is_echo, is_nl, is_raw,
keypad, meta, nl, nocbreak, nodelay, noecho, nonl, noqiflush, noraw,
notimeout, qiflush, raw, timeout, wtimeout, typeahead - get and set
curses terminal input options
#include <curses.h>
int cbreak(void);
int nocbreak(void);
int echo(void);
int noecho(void);
int intrflush(WINDOW * win /* ignored */, bool bf);
int keypad(WINDOW * win, bool bf);
int meta(WINDOW * win /* ignored */, bool bf);
int nodelay(WINDOW * win, bool bf);
int notimeout(WINDOW * win, bool bf);
int nl(void);
int nonl(void);
void qiflush(void);
void noqiflush(void);
int raw(void);
int noraw(void);
int halfdelay(int tenths);
void timeout(int delay);
void wtimeout(WINDOW * win, int delay);
int typeahead(int fd);
/* extensions */
int is_cbreak(void);
int is_echo(void);
int is_nl(void);
int is_raw(void);
curses offers configurable parameters permitting an application to
control the handling of input from the terminal. Some are global,
applying to all windows; others apply only to a specific window. The
library does not automatically apply such parameters to new or derived
windows; an application must configure each window for the desired
behavior.
Some descriptions below make reference to an input character reading
function: this is wgetch(3x) in the non-wide character curses API and
wget_wch(3x) in the wide character API. In addition to the variant
forms of these described in ncurses(3x), the curses functions
wgetstr(3x) and wget_wstr(3x) and their own variants call the
appropriate input character reading function.
Normally, the terminal driver buffers typed characters, not delivering
them to an application until a line feed or carriage return is typed.
cbreak configures the terminal in cbreak mode, which disables line
buffering and erase and kill character processing (the interrupt, quit,
suspend, and flow control characters are unaffected) and makes
characters typed by the user immediately available to the program.
nocbreak returns the terminal to normal ("cooked") mode.
The state of the terminal is unknown to a curses application when it
starts; therefore, a program should call cbreak or nocbreak explicitly.
Most interactive programs using curses set cbreak mode. Calling cbreak
overrides raw. The man page for the input character reading function
discusses how cbreak and nocbreak interact with echo and noecho.
echo and noecho determine whether characters typed by the user are
written to the curses window by the input character reading function as
they are typed. curses always disables the terminal driver's own
echoing. By default, a curses screen's echo option is set. Authors of
most interactive programs prefer to do their own echoing in a
controlled area of the screen, or not to echo at all, so they call
noecho. The man page for the input character reading function
discusses how echo and noecho interact with cbreak and nocbreak.
halfdelay configures half-delay mode, which is similar to cbreak mode
in that characters typed by the user are immediately available to the
program. However, after blocking for tenths tenths of seconds, an
input character reading function returns ERR if no input is pending.
The value of tenths must be between 1 and 255. Use nocbreak to leave
half-delay mode.
intrflush calls qiflush (see below) if bf is TRUE, and noqiflush if bf
is FALSE. It ignores its win argument.
keypad enables recognition of a terminal's function keys. If enabled
(bf is TRUE), the input character reading function returns a value
representing the function key, such as KEY_LEFT. (Wide-character API
users: wget_wch(3x) returns KEY_CODE_YES to indicate the availability
of a function key code in its wch parameter.) If disabled (bf is
FALSE), curses does not treat function keys specially and the program
has to interpret escape sequences itself. If the terminal's keypad can
be turned on (made to transmit) and off (made to work locally), keypad
configures it consistently with the bf parameter. By default, a
window's keypad mode is off.
Initially, whether the terminal returns 7- or 8-bit character codes on
input depends on the configuration of the terminal driver; see
termios(3). To force 8 bits to be returned, call meta(..., TRUE); this
is equivalent, on POSIX systems, to setting the CS8 flag on the
terminal. To force 7 bits to be returned, call meta(..., FALSE); this
is equivalent, on POSIX systems, to setting the CS7 flag on the
terminal. The window argument, win, is always ignored. If the term-
info string capabilities meta_on (smm) and meta_off (rmm) are defined
for the terminal type, enabling meta mode sends smm to the terminal and
disabling it sends rmm to the terminal.
Initially, whether the terminal reports a carriage return using the
character code for a line feed in cbreak or raw modes depends on the
configuration of the terminal driver; see termios(3). nl configures
the terminal to perform this translation. nonl disables it. In normal
(or "cooked") mode, the terminal driver always translates carriage
returns to line feeds.
nodelay configures the input character reading function to be non-
blocking for window win. If no input is ready, the reading function
returns ERR. If disabled (bf is FALSE), the reading function does not
return until it has input.
When the input character reading function reads an ESC character, it
sets a timer while waiting for the next character. notimeout(win,
TRUE) disables this timer. The purpose of the timeout is to
distinguish sequences produced by a function key from those typed by a
user. To configure the timeout rather than disabling it, see wtimeout
below.
qiflush and noqiflush configure the terminal driver's treatment of its
input and output queues when it handles the interrupt, suspend, or quit
characters in cbreak and "cooked" modes; on POSIX systems, see
termios(3). The default behavior is inherited from the terminal driver
settings. Calling qiflush configures the terminal to flush the queues
when any of these events occurs, giving the impression of faster
response to user input, but making the library's model of the screen
contents incorrect. Calling noqiflush prevents such flushing, but
might frustrate impatient users on slow connections if a curses update
of the screen is in progress when the event occurs; see typeahead below
for a mitigation of this problem. You may want to call noqiflush in a
signal handler if you want output to continue after the handler exits
as though the interrupt had not occurred.
raw configures the terminal to read input in raw mode, which is similar
to cbreak mode (see cbreak above) except that it furthermore passes
through the terminal's configured interrupt, quit, suspend, and flow
control characters uninterpreted to the application, instead of
generating a signal or acting on I/O flow. The behavior of the
terminal's "Break" key (if any) depends on terminal driver
configuration parameters that curses does not handle. noraw returns
the terminal to normal ("cooked") mode.
wtimeout configures whether a curses input character reading function
called on window win uses blocking or non-blocking reads. If delay is
negative, a blocking read is used, waiting indefinitely for input. If
delay is zero, a non-blocking read is used; an input character reading
function returns ERR if no input is pending. If delay is positive, an
input character reading function blocks for delay milliseconds, and
returns ERR if the delay elapses and there is still no input pending.
timeout calls wtimeout on stdscr.
Normally, a curses library checks the terminal for input while updating
the screen. If any is found, the update is postponed until the next
wrefresh(3x) or doupdate(3x) call, allowing faster response to user key
strokes. The library tests the file descriptor corresponding to the
FILE stream pointer passed to newterm(3x) (or stdin if initscr(3x) was
called), for pending input. typeahead instructs curses to test file
descriptor fd instead. An fd of -1 disables the check.
timeout and wtimeout return no value.
cbreak, nocbreak, echo, noecho, halfdelay, intrflush, keypad, meta,
nodelay, notimeout, nl, nonl, raw, noraw, and typeahead return OK on
success and ERR on failure.
In ncurses, the functions in the previous paragraph return ERR if
o the terminal is not initialized or
o win is NULL (except for intrflush and meta, which ignore its
value).
Further, halfdelay returns ERR if delay is outside the range 1..255.
See section "EXTENSIONS" below for the return values of is_cbreak,
is_echo, is_nl, and is_raw.
echo, noecho, halfdelay, intrflush, meta, nl, nonl, nodelay, notimeout,
noqiflush, qiflush, timeout, and wtimeout may be implemented as macros.
noraw and nocbreak follow historical practice in that they attempt to
restore normal ("cooked") mode from raw and cbreak modes, respectively.
Mixing raw/noraw calls with cbreak/nocbreak calls leads to terminal
driver control states that are hard to predict or understand; doing so
is not recommended.
ncurses provides four "is_" functions corresponding to cbreak, echo,
nl, and raw, permitting their states to be queried by the application.
Query Set Reset
------------------------------
is_cbreak cbreak nocbreak
is_echo echo noecho
is_nl nl nonl
is_raw raw noraw
In each case, the function returns
1 if the option is set,
0 if the option is reset, or
-1 if the library is not initialized.
Applications employing ncurses extensions should condition their use on
the visibility of the NCURSES_VERSION preprocessor macro.
Except as noted in section "EXTENSIONS" above, X/Open Curses, Issue 4
describes these functions. It specifies no error conditions for them.
SVr4 curses describes a successful return value only as "an integer
value other than ERR".
ncurses follows X/Open Curses and the historical practice of System V
curses, clearing the terminal driver's "echo" flag when initializing
the screen. BSD curses did not, but its raw function turned it off as
a side effect. For best portability, call echo or noecho explicitly
just after initialization, even if your program remains in normal
("cooked") mode.
X/Open Curses is ambiguous regarding whether raw should disable the
carriage return and line feed translation feature controlled by nl and
nonl. BSD curses did turn off these translations; System V curses did
not. ncurses does so, on the assumption that a programmer requesting
raw input wants a clean (ideally, 8-bit clean) connection that the
operating system will not alter.
When keypad is first enabled, ncurses loads the key definitions for the
current terminal description. If the terminal description includes
extended string capabilities, for example, by using the -x option of
tic(1), then ncurses also defines keys for the capabilities whose names
begin with "k". Corresponding key codes are generated and (depending
on previous loads of terminal descriptions) may differ from one
execution of a program to the next. The generated key codes are
recognized by keyname(3x), which then returns a name beginning with "k"
denoting the terminfo capability name rather than "K", used for curses
key names. On the other hand, an application can use define_key(3x) to
bind a specific key to a string of the programmer's choice. This
feature enables an application to check for its presence with
tigetstr(3x), and reassign the key code to match its own needs.
Low-level applications can use tigetstr(3x) to obtain the definition of
any string capability. curses applications use the input character
reading function to obtain key codes from input and rely upon the order
in which the string capabilities are loaded. Multiple key capability
strings can have the same value, but the input character reading
function can report only one key code. Most curses implementations
(including ncurses) load key definitions in the order they appear in
the strfnames array of string capability names; see term_variables(3x).
The last capability read using a particular definition determines the
key code to be reported. In ncurses, extended capabilities can be
interpreted as key definitions. These are loaded after the predefined
keys, and if a capability's value is the same as a previously loaded
key definition, the later definition is the one used.
4BSD curses (1980) introduced echo, noecho, nl, nonl, raw, and noraw.
SVr2 (1984) featured a new terminal driver, extending the curses API to
support it with cbreak, nocbreak, intrflush, keypad, meta, nodelay, and
typeahead.
SVr3 (1987) added halfdelay, notimeout, and wtimeout. qiflush and
noqiflush appeared in SVr3.1 (1987), at which point intrflush became a
wrapper for either of these functions, depending on the value of its
Boolean argument. SVr3.1 also added timeout.
ncurses 6.5 (2024) introduced is_cbreak, is_echo, is_nl, and is_raw.
Formerly, ncurses used nl and nonl to control the conversion of
newlines to carriage return/line feed on output as well as input.
X/Open Curses documents the use of these functions only for input.
This difference arose from converting the pcurses source (1986), which
used ioctl(2) calls and the sgttyb structure, to termios (the POSIX
terminal API). In the former, both input and output were controlled
via a single option "CRMOD", while the latter separates these features.
Because that conversion interferes with output optimization, ncurses
6.2 (2020) amended nl and nonl to eliminate their effect on output.
curses(3x), curs_getch(3x), curs_initscr(3x), curs_util(3x),
define_key(3x), termios(3), term_variables(3x).
ncurses 6.5 2024-06-08 curs_inopts(3x)