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, such as those
affecting the terminal's mode or line discipline, 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.
This canonical ("cooked") line discipline also supports software flow
control, simple line editing functions (character and word erase, and
whole-line erasure or "kill"), and job control. 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 restores canonical
("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 tenth-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) then when an input character reading function reads a
character that is a common prefix to multiple key-defining string
capabilities (typically ESC), it waits for further input corresponding
to an escape sequence defined by the terminal type description. If a
valid sequence populates the input stream, 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 the sequence is invalid, the input character reading
function returns only its last character. If disabled (bf is FALSE),
curses does not treat function keys specially; the application must
itself interpret any character sequences they transmit. If the
terminal type description defines the keypad_local (rmkx) and
keypad_xmit (smkx) capabilities, enabling a window's keypad mode sets
the terminal's keypad to transmit, and disabling keypad mode sets the
terminal's keypad to work locally. 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; on POSIX
systems, 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. curses ignores the window argument win. If
the terminfo string capabilities meta_on (smm) and meta_off (rmm) are
defined for the terminal type, enabling meta mode sends smm's value to
the terminal and disabling it sends that of 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; on POSIX systems, see termios(3).
nl configures the terminal to perform this translation. nonl disables
it. Under its canonical ("cooked") line discipline, 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 keypad has been called on a window and the input character reading
function reads an ambiguous prefix character (typically ESC) from it,
curses sets a timer while waiting for the next character. If the timer
elapses, curses interprets the prefix as an explicit press of the key
corresponding thereto, such as Escape for ESC. 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. If
this timer is disabled, curses waits forever for subsequent keystrokes
until it determines the escape sequence to be valid or invalid.
qiflush and noqiflush configure the terminal driver's treatment of its
input and output queues when it handles the interrupt, suspend, or quit
characters under the canonical ("cooked") or cbreak line disciplines 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 (discarding their contents) 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,
after the handler exits, you want output to continue as though the
signal 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 restores
the terminal's canonical ("cooked") line discipline.
wtimeout configures whether a curses input character reading function
called on window win uses blocking or non-blocking reads. If delay is
negative, curses uses a blocking read, waiting indefinitely for input.
If delay is zero, the read is non-blocking; 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's input file descriptor
for activity with poll(2) or select(2) while updating the screen; if it
finds any, it postpones output 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 library's TERMINAL structure for the device has not been
initialized with initscr(3x), newterm(3x), or setupterm(3x), or
o win is a null pointer (except with 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 the terminal's canonical ("cooked") line discipline from raw
and cbreak, 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.
curses documentation uses the terms "delay" and "timeout" freely to
describe two related but distinct aspects of input handling, at the
risk of confusing the user. The functions halfdelay, nodelay, timeout,
and wtimeout configure whether the input character reading function
(wgetch(3x) or wget_wch(3x)) waits for keyboard input to begin, and for
how long. keypad configures whether that function waits for further
input if the first character it reads is an ambiguous prefix (like
ESC). Calling notimeout, which has nothing to do with timeout or
wtimeout, makes this delay in expectation of further characters
effectively infinite. X/Open Curses affords no means of otherwise
configuring the length of this second delay, but an AIX and ncurses
extension, ESCDELAY, is available both as an environment variable and a
global symbol permitting the user and application, respectively, to do
so; see ncurses(3x) and curs_variables(3x).
When keypad is first enabled for a window, ncurses loads the standard
function key string capabilities for the terminal type description of
its screen; see the table entries containing "key_" in terminfo(5). If
that description includes extended string capabilities (produced by the
-x option of tic(1), for example), then for each extended function key
whose capability code begins with "k", ncurses generates a numeric key
code. These code values are affected by previous loads of terminal
type descriptions, and may differ from one execution of the application
to the next. In ncurses, keyname(3x) recognizes these generated key
codes and returns a name beginning with "k" denoting the extended term-
info capability code rather than one starting with "KEY_", which
standard curses key names use. Further, an application can use
define_key(3x) to bind any key code to a string of the programmer's
choice. This feature enables an application to check for a function
key's presence with tigetstr(3x), and reassign the key code to match
its own needs.
Applications employing the lower-level terminfo API can use
tigetstr(3x) to obtain the contents of any string capability, including
extended ones. Applications employing the higher-level curses API use
an input character reading function to obtain key codes from input; the
result can vary depending upon the order in which 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. ncurses
loads extended capabilities after standard ones. Thus, if an extended
string capability's value is the same as one previously loaded, the
input character reading function returns the last matching extended
one.
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 unset, or
-1 if the library's TERMINAL structure for the device has not been
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 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 retains the terminal's
canonical ("cooked") line discipline.
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 turned 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 does not alter.
4BSD (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 conversions 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.6 2026-09-19 curs_inopts(3x)