path: root/man/curs_inopts.3x

'\" t
.\"***************************************************************************
.\" Copyright 2018-2024,2025 Thomas E. Dickey                                *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
.\"                                                                          *
.\" Permission is hereby granted, free of charge, to any person obtaining a  *
.\" copy of this software and associated documentation files (the            *
.\" "Software"), to deal in the Software without restriction, including      *
.\" without limitation the rights to use, copy, modify, merge, publish,      *
.\" distribute, distribute with modifications, sublicense, and/or sell       *
.\" copies of the Software, and to permit persons to whom the Software is    *
.\" furnished to do so, subject to the following conditions:                 *
.\"                                                                          *
.\" The above copyright notice and this permission notice shall be included  *
.\" in all copies or substantial portions of the Software.                   *
.\"                                                                          *
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
.\"                                                                          *
.\" Except as contained in this notice, the name(s) of the above copyright   *
.\" holders shall not be used in advertising or otherwise to promote the     *
.\" sale, use or other dealings in this Software without prior written       *
.\" authorization.                                                           *
.\"***************************************************************************
.\"
.\" $Id: curs_inopts.3x,v 1.116 2025/10/04 20:15:02 tom Exp $
.TH curs_inopts 3X 2025-10-04 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "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
\fB\%cbreak\fP,
\fB\%echo\fP,
\fB\%halfdelay\fP,
\fB\%intrflush\fP,
\fB\%is_cbreak\fP,
\fB\%is_echo\fP,
\fB\%is_nl\fP,
\fB\%is_raw\fP,
\fB\%keypad\fP,
\fB\%meta\fP,
\fB\%nl\fP,
\fB\%nocbreak\fP,
\fB\%nodelay\fP,
\fB\%noecho\fP,
\fB\%nonl\fP,
\fB\%noqiflush\fP,
\fB\%noraw\fP,
\fB\%notimeout\fP,
\fB\%qiflush\fP,
\fB\%raw\fP,
\fB\%timeout\fP,
\fB\%wtimeout\fP,
\fB\%typeahead\fP \-
get and set \fIcurses\fR terminal input options
.SH SYNOPSIS
.nf
\fB#include <curses.h>
.PP
\fBint cbreak(void);
\fBint nocbreak(void);
.PP
\fBint echo(void);
\fBint noecho(void);
.PP
\fBint intrflush(WINDOW * \fIwin\fP \fI/* ignored */\fP, bool \fIbf\fP);
\fBint keypad(WINDOW * \fIwin\fP, bool \fIbf\fP);
\fBint meta(WINDOW * \fIwin\fP \fI/* ignored */\fP, bool \fIbf\fP);
\fBint nodelay(WINDOW * \fIwin\fP, bool \fIbf\fP);
\fBint notimeout(WINDOW * \fIwin\fP, bool \fIbf\fP);
.PP
\fBint nl(void);
\fBint nonl(void);
.PP
\fBvoid qiflush(void);
\fBvoid noqiflush(void);
.PP
\fBint raw(void);
\fBint noraw(void);
.PP
\fBint halfdelay(int \fItenths\fP);
\fBvoid timeout(int \fIdelay\fP);
\fBvoid wtimeout(WINDOW * \fIwin\fP, int \fIdelay\fP);
.PP
\fBint typeahead(int \fIfd\fP);
.PP
\fI/* extensions */
\fBint is_cbreak(void);
\fBint is_echo(void);
\fBint is_nl(void);
\fBint is_raw(void);
.fi
.SH DESCRIPTION
.I curses
offers configurable parameters permitting an application to control the
handling of input from the terminal.
Some,
such as those affecting the terminal's
.I 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.
.PP
Some descriptions below make reference to an
.IR "input character reading function" ":"
this is \fB\%wgetch\fP(3X) in the non-wide character
.I curses
API and \fB\%wget_wch\fP(3X) in the wide character API.
In addition to the variant forms of these described in
\fB\%ncurses\fP(3X),
the
.I curses
functions \fB\%wgetstr\fP(3X) and \fB\%wget_wstr\fP(3X) and their own
variants call the appropriate input character reading function.
.\"
.SS "cbreak, nocbreak"
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.
.B \%cbreak
configures the terminal in
.IR "cbreak mode" ","
which disables line buffering
and erase and kill character processing \(em
the interrupt,
quit,
suspend,
and flow control characters are unaffected \(em
and makes characters typed by the user immediately available to the
program.
.B \%nocbreak
restores canonical (\*(``cooked\*('') mode.
.PP
The state of the terminal is unknown to a
.I curses
application when it starts;
therefore,
a program should call
.B \%cbreak
or
.B \%nocbreak
explicitly.
Most interactive programs using
.I curses
set \%cbreak
mode.
Calling
.B \%cbreak
overrides
.BR raw "."
The man page for the input character reading function
discusses how
.B \%cbreak
and
.B \%nocbreak
interact with
.B echo
and
.BR \%noecho "."
.\"
.SS "echo, noecho"
.B echo
and
.B \%noecho
determine whether characters typed by the user are written to the
.I curses
window by the input character reading function as they are typed.
.I curses
always disables the terminal driver's own echoing.
By default,
a
.I 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
.BR \%noecho "."
The man page for the input character reading function
discusses how
.B echo
and
.B \%noecho
interact with
.B \%cbreak
and
.BR \%nocbreak "."
.\"
.SS halfdelay
.B \%halfdelay
configures
.IR "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
.I tenths
tenth-seconds,
an input character reading function returns
.B ERR
if no input is pending.
The value of
.I tenths
must be between 1 and 255.
Use
.B \%nocbreak
to leave half-delay mode.
.\"
.SS intrflush
.B \%intrflush
calls
.B \%qiflush
(see below)
if
.I bf
is
.BR TRUE ","
and
.B \%noqiflush
if
.I bf
is
.BR FALSE "."
It ignores its
.I win
argument.
.\"
.SS keypad
.B keypad
enables recognition of a terminal's function keys.
If
enabled
.RI ( bf
is
.BR TRUE ")"
then when an input character reading function reads 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
.BR KEY_LEFT "."
(Wide-character API users:
\fB\%wget_wch\fP(3X) returns
.B \%KEY_CODE_YES
to indicate the availability of a function key code in its
.I wch
parameter.)
If the sequence is invalid,
the input character reading function returns only its last character.
If disabled
.RI ( bf
is
.BR FALSE ),
.I curses
does not treat function keys specially and the program has to interpret
escape sequences itself.
If the terminal type description defines the
.B \%keypad_local
.RB ( rmkx )
and
.B \%keypad_xmit
.RB ( 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.
.\"
.SS meta
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 \fI\%termios\fP(3).
To force 8 bits to be returned,
call
.BR meta( .\|.\|. ,
.BR TRUE) ;
this is equivalent,
on POSIX systems,
to setting the CS8 flag on the terminal.
To force 7 bits to be returned,
call
.BR meta( .\|.\|. ,
.BR FALSE) ;
this is equivalent,
on POSIX systems,
to setting the CS7 flag on the terminal.
.I curses
ignores the window argument
.IR win "."
If the
.I \%term\%info
string capabilities
.B \%meta_on
.RB ( smm )
and
.B \%meta_off
.RB ( rmm )
are defined for the terminal type,
enabling meta mode sends
.BR smm 's
value to the terminal and disabling it sends that of
.B rmm
to the terminal.
.\"
.SS "nl, nonl"
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 \fI\%termios\fP(3).
.B nl
configures the terminal to perform this translation.
.B nonl
disables it.
Under its canonical (\*(``cooked\*('') line discipline,
the terminal driver always translates carriage returns to line feeds.
.\"
.SS nodelay
.B \%nodelay
configures the input character reading function to be non-blocking for
window
.IR "win" .
If no input is ready,
the reading function returns
.BR ERR "."
If disabled
.RI ( bf
is
.BR FALSE ),
the reading function does not return until it has input.
.SS notimeout
When
.B \%keypad
has been called on a window
and the input character reading function reads an ESC character from it,
.I curses
sets a timer while waiting for the next character.
If the timer elapses,
.I curses
interprets the ESC as an explicit press of the terminal's Escape key
(or equivalent).
.\" like Control+[
.BI \%notimeout( win ,
.B 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,
.I curses
waits forever for subsequent keystrokes
until it determines the escape sequence to be valid or invalid.
.\"
.SS "qiflush, noqiflush"
.\"
.B \%qiflush
and
.B \%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 \fI\%termios\fP(3).
The default behavior is inherited from the terminal driver settings.
Calling
.B \%qiflush
configures the terminal to
.I 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
.B \%noqiflush
prevents such flushing,
but might frustrate impatient users on slow connections if a
.I curses
update of the screen is in progress when the event occurs;
see
.B \%typeahead
below for a mitigation of this problem.
You may want to call
.B \%noqiflush
in a signal handler if,
after the handler exits,
you want output to continue
as though the signal had not occurred.
.\"
.SS "raw, noraw"
.B raw
configures the terminal to read input in
.IR "raw mode" ,
which is similar to cbreak mode
(see
.B \%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
.I curses
does not handle.
.B \%noraw
restores the terminal's canonical (\*(``cooked\*('') line discipline.
.\"
.SS "timeout, wtimeout"
.B \%wtimeout
configures whether a
.I curses
input character reading function called on window
.I win
uses blocking or non-blocking reads.
If
.I delay
is negative,
.I curses
uses a blocking read,
waiting indefinitely for input.
If
.I delay
is zero,
the read is non-blocking;
an input character reading function returns
.B ERR
if no input is pending.
If
.I delay
is positive,
an input character reading function
blocks for
.I delay
milliseconds,
and returns
.B ERR
if the delay elapses and there is still no input pending.
.B \%timeout
calls
.B \%wtimeout
on
.BR stdscr "."
.\"
.SS typeahead
Normally,
a
.I curses
library checks the terminal's input file descriptor for activity
with \fIpoll\fP(2) or \fI\%select\fP(2)
while updating the screen;
if it finds any,
it postpones output
until the next \fB\%wrefresh\fP(3X) or \fB\%doupdate\fP(3X) call,
allowing faster response to user key strokes.
The library tests the file descriptor corresponding to the
.I FILE
stream pointer passed to \fB\%newterm\fP(3X)
(or
.I stdin
if \fB\%initscr\fP(3X) was called),
for pending input.
.B \%typeahead
instructs
.I curses
to test file descriptor
.I fd
instead.
An
.I fd
of
.B \-1
disables the check.
.\"
.SH RETURN VALUE
.B \%timeout
and
.B \%wtimeout
return no value.
.PP
.BR \%cbreak ","
.BR \%nocbreak ","
.BR \%echo ","
.BR \%noecho ","
.BR \%halfdelay ","
.BR \%intrflush ","
.BR \%keypad ","
.BR \%meta ","
.BR \%nodelay ","
.BR \%notimeout ","
.BR \%nl ","
.BR \%nonl ","
.BR \%raw ","
.BR \%noraw ","
and
.B \%typeahead
return
.B OK
on success and
.B ERR
on failure.
.PP
In
.IR \%ncurses ","
the functions in the previous paragraph return
.B ERR
if
.bP
the library's
.I \%TERMINAL
structure for the device has not been initialized with
\fB\%initscr\fP(3X),
\fB\%newterm\fP(3X),
or
\fB\%setupterm\fP(3X),
or
.bP
.I win
is a null pointer
(except with
.B \%intrflush
and
.BR meta ","
which ignore its value).
.PP
Further,
.B \%halfdelay
returns
.B ERR
if
.I delay
is outside the range 1..255.
.PP
See section \*(``EXTENSIONS\*('' below for the
return values of
.BR is_cbreak ","
.BR is_echo ","
.BR is_nl ","
and
.BR is_raw "."
.SH NOTES
.BR echo ","
.BR \%noecho ","
.BR \%halfdelay ","
.BR \%intrflush ","
.BR meta ","
.BR nl ","
.BR nonl ","
.BR \%nodelay ","
.BR \%notimeout ","
.BR \%noqiflush ","
.BR \%qiflush ","
.BR \%timeout ","
and
.B \%wtimeout
may be implemented as macros.
.PP
.B \%noraw
and
.B \%nocbreak
follow historical practice in that they attempt to restore
the terminal's canonical (\*(``cooked\*('') line discipline
from raw and cbreak,
respectively.
Mixing
.BR \%raw / noraw
calls with
.BR \%cbreak / nocbreak
calls leads to terminal driver control states that are hard to predict
or understand;
doing so is not recommended.
.PP
.I 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
.BR \%halfdelay ","
.BR \%nodelay ","
.BR \%timeout ","
and
.B \%wtimeout
configure whether the input character reading function
\%(\fBwgetch\fP(3X) or \fB\%wget_wch\fP(3X))
waits for keyboard input to begin,
and for how long.
.B \%keypad
configures whether that function waits for further input
if the first character it reads is ESC.
Calling
.BR \%notimeout ","
which has nothing to do with
.B \%timeout
or
.BR \%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
.I \%ncurses
extension,
.BR \%ESCDELAY ,
is available both as an environment variable and a global symbol
permitting the user and application,
respectively,
to do so;
see \fB\%ncurses\fP(3X) and \fB\%curs_variables\fP(3X).
.SH EXTENSIONS
.I \%ncurses
provides four \*(``is_\*('' functions corresponding to
.BR \%cbreak ","
.BR echo ","
.BR nl ","
and
.BR raw ","
permitting their states to be queried by the application.
.PP
.TS
center;
Lb Lb Lb
L  L  L .
Query	Set	Reset
_
is_cbreak	cbreak	nocbreak
is_echo	echo	noecho
is_nl	nl	nonl
is_raw	raw	noraw
.TE
.PP
In each case,
the function returns
.TP 5 \" "-1" + 2n tag separation + 1n fudge for typesetters like grops
.B 1
if the option is set,
.TP
.B 0
if the option is unset,
or
.TP
.B \-1
if the library's
.I \%TERMINAL
structure for the device has not been initialized.
.SH PORTABILITY
Applications employing
.I \%ncurses
extensions should condition their use on the visibility of the
.B \%NCURSES_VERSION
preprocessor macro.
.PP
Except as noted in section \*(``EXTENSIONS\*('' above,
X/Open Curses Issue\ 4 describes these functions.
It specifies no error conditions for them.
.PP
SVr4 describes a successful return value only as
\*(``an integer value other than
.IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 508
.\" It continues "unless otherwise noted in the preceding routine
.\" descriptions", but no notes otherwise are present; the man page
.\" discusses getch()'s return value repeatedly, but never those of the
.\" functions the page ostensibly documents.
.PP
.I \%ncurses
follows X/Open Curses
and the historical practice of System\ V
.IR curses ","
clearing the terminal driver's \*(``echo\*('' flag when initializing the
screen.
BSD
.I curses
did not,
but its
.I raw
function turned it off as a side effect.
.\" SGTTY's sg_flags had a "RAW" symbol; termio in SVr1 for the PDP-11
.\" did not.
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/include/curses.h
.\" https://github.com/ryanwoodsmall/oldsysv/blob/master/sysv-pdp11_man/a_man/man7/termio.7
For best portability,
call
.I echo
or
.I \%noecho
explicitly just after initialization,
even if your program retains the terminal's canonical (\*(``cooked\*('')
line discipline.
.PP
X/Open Curses is ambiguous regarding whether
.I raw
should disable the carriage return and line feed translation feature
controlled by
.I nl
and
.IR \%nonl "."
BSD
.I curses
turned off these translations;
System\ V
.I curses
did not.
.I \%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.
.PP
When
.B \%keypad
is first enabled for a window,
.I \%ncurses
loads the standard function key string capabilities
for the terminal type description of its screen;
see the entries beginning with \*(``key_\*('' in \fB\%terminfo\fP(5).
If that description includes extended string capabilities,
produced by the
.B \-x
option of \fB\%@TIC@\fP(1),
for example,
then
.I \%ncurses
also defines keys for the capabilities whose codes begin with
\*(``k\*(''.
.I \%ncurses
generates a numeric key code for each such extended capability;
depending on previous loads of terminal type descriptions,
these may differ from one execution of a program to the next.
\fB\%keyname\fP(3X) recognizes the generated key codes
and returns a name beginning with \*(``k\*('' denoting the
.I \%term\%info
capability name rather than \*(``KEY_\*('',
used for
.I curses
key names.
On the other hand,
an application can use \fB\%define_key\fP(3X) to bind
a selected key to a string of the programmer's choice.
This feature enables an application to check for its presence
with \fB\%tigetstr\fP(3X),
and reassign the numeric key code to match its own needs.
.PP
Low-level applications can use \fB\%tigetstr\fP(3X) to obtain the
definition of any string capability.
.I 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
.I curses
implementations
(including
.IR \%ncurses )
load key definitions in the order
they appear in the
.B \%strfnames
array of string capability names;
see \fB\%term_variables\fP(3X).
.\" ncurses/tinfo/parse_entry.c:lookup_fullname, I think --GBR
The last capability read using a particular definition determines the
key code to be reported.
In
.IR \%ncurses ,
extended capabilities can be interpreted as key definitions.
The library loads these after its built-in definitions,
and if an extended capability's value
is the same as one previously loaded,
the library uses the later definition.
.SH HISTORY
4BSD (1980)
introduced
.IR echo ","
.IR \%noecho ","
.IR nl ","
.IR \%nonl ","
.IR raw ","
and
.IR \%noraw "." \" also crmod and nocrmod, never standardized
.PP
SVr2 (1984)
featured a new terminal driver,
extending the
.I curses
API to support it with
.IR \%cbreak ","
.IR \%nocbreak ","
.IR \%intrflush ","
.IR \%keypad ","
.IR \%meta ","
.IR \%nodelay ","
and
.IR \%typeahead "."
.PP
SVr3 (1987)
added
.IR \%halfdelay ","
.IR \%notimeout ","
and
.IR \%wtimeout "."
.I \%qiflush
and
.I \%noqiflush
appeared in SVr3.1 (1987),
at which point
.I \%intrflush
became a wrapper for either of these functions,
depending on the value of its Boolean argument.
SVr3.1 also added
.IR \%timeout "."
.PP
.I \%ncurses
6.5 (2024) introduced
.IR is_cbreak ","
.IR is_echo ","
.IR is_nl ","
and
.IR is_raw "."
.PP
Formerly,
.I \%ncurses
used
.I \%nl
and
.I \%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
.I \%pcurses
source (1986),
which used
\fI\%ioctl\fP(2) calls and the
.I \%sgttyb
structure,
to
.I \%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,
.I \%ncurses
6.2 (2020) amended
.I \%nl
and
.I \%nonl
to eliminate their effect on output.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_getch\fP(3X),
\fB\%curs_initscr\fP(3X),
\fB\%curs_util\fP(3X),
\fB\%define_key\fP(3X),
\fB\%termios\fP(3),
\fB\%term_variables\fP(3X)