'\" 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_inopts.3x,v 1.55 2023/10/07 21:19:07 tom Exp $
-.TH curs_inopts 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_inopts.3x,v 1.66 2024/04/13 22:20:29 tom Exp $
+.TH curs_inopts 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint is_raw(void);
.fi
.SH DESCRIPTION
-The \fIncurses\fP library provides several functions which let an application
-change the way input from the terminal is handled.
-Some are global, applying to all windows.
+.I \%ncurses
+provides several functions that let an application change the way input
+from the terminal is handled.
+Some are global,
+applying to all windows.
Others apply only to a specific window.
Window-specific settings are not automatically applied to new or derived
windows.
-An application must apply these to each window, if the same behavior
-is needed.
+An application must apply these to each window if the same behavior is
+desired.
.\"
-.SS cbreak/nocbreak
-Normally, the tty driver buffers typed characters until a newline or carriage
+.SS "cbreak, nocbreak"
+Normally,
+the terminal driver buffers typed characters until a newline or carriage
return is typed.
The \fB\%cbreak\fP routine disables line buffering and
-erase/kill character-processing (interrupt and flow control characters are
-unaffected), making characters typed by the user immediately available to the
+erase/kill character-processing
+(interrupt and flow control characters are unaffected),
+making characters typed by the user immediately available to the
program.
The \fB\%nocbreak\fP routine returns the terminal to normal (cooked)
mode.
.PP
-Initially the terminal may or may not be in \fB\%cbreak\fP mode, as the mode is
-inherited; therefore, a program should call \fB\%cbreak\fP or \fB\%nocbreak\fP
-explicitly.
-Most interactive programs using \fIcurses\fP set the \fB\%cbreak\fP
-mode.
+Initially the terminal may or may not be in \fB\%cbreak\fP mode,
+as the mode is inherited;
+therefore,
+a program should call \fB\%cbreak\fP or \fB\%nocbreak\fP explicitly.
+Most interactive programs using
+.I curses
+set the \fB\%cbreak\fP mode.
Note that \fB\%cbreak\fP overrides \fBraw\fP.
-[See \fB\%curs_getch\fP(3X) for a
-discussion of how these routines interact with \fBecho\fP and \fB\%noecho\fP.]
+[See \fB\%curs_getch\fP(3X) for a discussion of how these routines
+interact with \fBecho\fP and \fB\%noecho\fP.]
.\"
-.SS echo/noecho
-The \fBecho\fP and \fB\%noecho\fP routines control whether characters typed by
-the user are echoed by \fB\%getch\fP(3X) as they are typed.
-Echoing by the tty
-driver is always disabled, but initially \fB\%getch\fP is in echo mode, so
-characters typed are echoed.
+.SS "echo, noecho"
+The \fBecho\fP and \fB\%noecho\fP routines control whether characters
+typed by the user are echoed by \fB\%getch\fP(3X) as they are typed.
+Echoing by the terminal driver is always disabled,
+but initially \fB\%getch\fP is in echo mode,
+so characters typed are echoed.
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 disable echoing by calling \fB\%noecho\fP.
+their own echoing in a controlled area of the screen,
+or not to echo at all,
+so they disable echoing by calling \fB\%noecho\fP.
[See \fB\%curs_getch\fP(3X) for a
discussion of how these routines interact with \fB\%cbreak\fP and
\fB\%nocbreak\fP.]
.\"
.SS halfdelay
-The \fB\%halfdelay\fP routine is used for half-delay mode, which is similar to
-\fB\%cbreak\fP mode in that characters typed by the user are immediately
-available to the program.
-However, after blocking for \fItenths\fP tenths of
-seconds, \fBERR\fP is returned if nothing has been typed.
-The value of \fItenths\fP
-must be a number between 1 and 255.
-Use \fB\%nocbreak\fP to leave half-delay
-mode.
+The \fB\%halfdelay\fP routine is used for half-delay mode,
+which is similar to \fB\%cbreak\fP mode in that characters typed by the
+user are immediately available to the program.
+However,
+after blocking for \fItenths\fP tenths of seconds,
+\fBERR\fP is returned if nothing has been typed.
+The value of \fItenths\fP must be a number between 1 and 255.
+Use \fB\%nocbreak\fP to leave half-delay mode.
.\"
.SS intrflush
-If the \fB\%intrflush\fP option is enabled (\fIbf\fP is \fBTRUE\fP), and an
-interrupt key is pressed on the keyboard (interrupt, break, quit), all output in
-the tty driver queue will be flushed, giving the effect of faster response to
-the interrupt, but causing \fIcurses\fP to have the wrong idea of what is on
-the screen.
-Disabling the option (\fIbf\fP is \fBFALSE\fP) prevents the
-flush.
-The default for the option is inherited from the tty driver settings.
-The window argument is ignored.
+If the \fB\%intrflush\fP option is enabled
+.RI ( bf
+is
+.BR TRUE ),
+and an interrupt key is pressed on the keyboard
+(interrupt,
+break,
+quit),
+all output in the terminal driver queue is flushed,
+giving the effect of faster response to the interrupt,
+but causing
+.I curses
+to have the wrong idea of what is on the screen.
+Disabling the option
+.RI ( bf
+is
+.BR FALSE ),
+prevents the flush.
+The default for the option is inherited from the terminal driver
+settings.
+The
+.I win
+argument is ignored.
.\"
.SS keypad
The \fB\%keypad\fP option enables the keypad of the user's terminal.
If
-enabled (\fIbf\fP is \fBTRUE\fP), the user can press a function key
-(such as an arrow key) and \fB\%wgetch\fP(3X) returns a single value
-representing the function key, as in \fB\%KEY_LEFT\fP.
+enabled
+.RI ( bf
+is
+.BR TRUE ),
+the user can press a function key
+(such as an arrow key)
+and \fB\%wgetch\fP(3X) returns a single value representing the function
+key,
+as in \fB\%KEY_LEFT\fP.
If disabled
-(\fIbf\fP is \fBFALSE\fP), \fIcurses\fP does not treat function keys
-specially and the program has to interpret the escape sequences
-itself.
-If the keypad in the terminal can be turned on (made to
-transmit) and off (made to work locally), turning on this option
-causes the terminal keypad to be turned on when \fB\%wgetch\fP(3X) is
-called.
+(\fIbf\fP is \fBFALSE\fP),
+.I curses
+does not treat function keys specially and the program has to interpret
+the escape sequences itself.
+If the keypad in the terminal can be turned on
+(made to transmit)
+and off
+(made to work locally),
+turning on this option causes the terminal keypad to be turned on when
+\fB\%wgetch\fP(3X) is called.
The default value for keypad is \fBFALSE\fP.
.\"
.SS meta
-Initially, whether the terminal returns 7 or 8 significant bits on
-input depends on the control mode of the tty driver [see \fB\%termios\fP(3)].
-To force 8 bits to be returned, invoke \fBmeta\fP(\fIwin\fP,
-\fBTRUE\fP); this is equivalent, under POSIX, to setting the CS8 flag
-on the terminal.
-To force 7 bits to be returned, invoke
-\fBmeta\fP(\fIwin\fP, \fBFALSE\fP); this is equivalent, under POSIX,
+Initially,
+whether the terminal returns 7 or 8 significant bits on input depends on
+the control mode of the terminal driver [see \fI\%termios\fP(3)].
+To force 8 bits to be returned,
+invoke
+\fBmeta\fP(\fIwin\fP, \fBTRUE\fP);
+this is equivalent,
+under POSIX,
+to setting the CS8 flag on the terminal.
+To force 7 bits to be returned,
+invoke
+\fBmeta\fP(\fIwin\fP, \fBFALSE\fP);
+this is equivalent,
+under POSIX,
to setting the CS7 flag on the terminal.
The window argument,
-\fIwin\fP, is always ignored.
-If the terminfo capabilities \fBsmm\fP
-(meta_on) and \fBrmm\fP (meta_off) are defined for the terminal,
-\fBsmm\fP is sent to the terminal when \fBmeta\fP(\fIwin\fP,
-\fBTRUE\fP) is called and \fBrmm\fP is sent when \fBmeta\fP(\fIwin\fP,
-\fBFALSE\fP) is called.
+.IR win ,
+is always ignored.
+If the terminfo capabilities
+\fBsmm\fP (meta_on) and
+\fBrmm\fP (meta_off) are defined for the terminal,
+\fBsmm\fP is sent to the terminal when
+\fBmeta\fP(\fIwin\fP, \fBTRUE\fP)
+is called and \fBrmm\fP is sent when
+\fBmeta\fP(\fIwin\fP, \fBFALSE\fP) is called.
.\"
-.SS nl/nonl
-The \fBnl\fP and \fBnonl\fP routines control whether the underlying display
-device translates the return key into newline on input.
+.SS "nl, nonl"
+The \fBnl\fP and \fBnonl\fP routines control whether the underlying
+display device translates the return key into newline on input.
.\"
.SS nodelay
-The \fB\%nodelay\fP option causes \fB\%getch\fP to be a non-blocking call.
-If no input is ready, \fB\%getch\fP returns \fBERR\fP.
+The \fB\%nodelay\fP option causes \fB\%getch\fP to be a non-blocking
+call.
+If no input is ready,
+\fB\%getch\fP returns \fBERR\fP.
If disabled
-(\fIbf\fP is \fBFALSE\fP), \fB\%getch\fP waits until a key is pressed.
+.RI ( bf
+is
+.BR FALSE ),
+\fB\%getch\fP waits until a key is pressed.
.SS notimeout
-When interpreting an escape sequence, \fB\%wgetch\fP(3X) sets a timer
+When interpreting an escape sequence,
+\fB\%wgetch\fP(3X) sets a timer
while waiting for the next character.
-If \fB\%notimeout(\fIwin\fR,
-\fBTRUE\fP) is called, then \fB\%wgetch\fP does not set a timer.
-The
-purpose of the timeout is to differentiate between sequences received
-from a function key and those typed by a user.
+If
+\fB\%notimeout(\fIwin\fR, \fBTRUE\fP)
+is called,
+then \fB\%wgetch\fP does not set a timer.
+The purpose of the timeout is to distinguish sequences produced by a
+function key from those typed by a user.
.\"
-.SS raw/noraw
-The \fBraw\fP and \fB\%noraw\fP routines place the terminal into or out of raw
-mode.
-Raw mode is similar to \fB\%cbreak\fP mode, in that characters typed are
-immediately passed through to the user program.
-The differences are that in
-raw mode, the interrupt, quit, suspend, and flow control characters are all
-passed through uninterpreted, instead of generating a signal.
-The behavior of
-the BREAK key depends on other bits in the tty driver that are not set by
-\fIcurses\fP.
+.SS "raw, noraw"
+The \fBraw\fP and \fB\%noraw\fP routines place the terminal into or out
+of raw mode.
+Raw mode is similar to \fB\%cbreak\fP mode,
+in that characters typed are immediately passed through to the user
+program.
+The differences are that in raw mode,
+the interrupt,
+quit,
+suspend,
+and flow control characters are all
+passed through uninterpreted,
+instead of generating a signal.
+The behavior of the BREAK key depends on other bits in the terminal
+driver that are not set by
+.IR curses .
.\"
-.SS qiflush/noqiflush
-When the \fB\%noqiflush\fP routine is used, normal flush of input and
-output queues associated with the \fBINTR\fP, \fBQUIT\fP and
-\fBSUSP\fP characters will not be done [see \fB\%termios\fP(3)].
+.SS "qiflush, nqiflush"
+When the \fB\%noqiflush\fP routine is used,
+normal flush of input and output queues associated with the \fBINTR\fP,
+\fBQUIT\fP and \fBSUSP\fP characters will not be done
+[see \fB\%termios\fP(3)].
When
-\fB\%qiflush\fP is called, the queues will be flushed when these control
-characters are read.
-You may want to call \fB\%noqiflush\fP in a signal
-handler if you want output to continue as though the interrupt
-had not occurred, after the handler exits.
+\fB\%qiflush\fP is called,
+the queues will be flushed when these control characters are read.
+You may want to call \fB\%noqiflush\fP in a signal handler if you want
+output to continue as though the interrupt had not occurred,
+after the handler exits.
.\"
-.SS timeout/wtimeout
+.SS "timeout, wtimeout"
The \fB\%timeout\fP and \fB\%wtimeout\fP routines set blocking or
non-blocking read for a given window.
If \fIdelay\fP is negative,
-blocking read is used (i.e., waits indefinitely for
-input).
-If \fIdelay\fP is zero, then non-blocking read is used
-(i.e., read returns \fBERR\fP if no input is waiting).
+a blocking read is used
+(i.e.,
+waits indefinitely for input).
+If \fIdelay\fP is zero,
+then a non-blocking read is used
+(i.e.,
+.I read
+returns \fBERR\fP if no input is waiting).
If
-\fIdelay\fP is positive, then read blocks for \fIdelay\fP
-milliseconds, and returns \fBERR\fP if there is still no input.
-Hence, these routines provide the same functionality as \fB\%nodelay\fP,
+\fIdelay\fP is positive,
+then
+.I read
+blocks for \fIdelay\fP milliseconds,
+and returns \fBERR\fP if there is still no input.
+Hence,
+these routines provide the same functionality as \fB\%nodelay\fP,
plus the additional capability of being able to block for only
-\fIdelay\fP milliseconds (where \fIdelay\fP is positive).
+\fIdelay\fP milliseconds
+(where \fIdelay\fP is positive).
.\"
.SS typeahead
-The \fIcurses\fP library does \*(``line-breakout optimization\*(''
-by looking for typeahead periodically while updating the screen.
-If input is found, and it is coming from a tty,
+.I curses
+does \*(``line-breakout optimization\*('' by looking for typeahead
+periodically while updating the screen.
+If input is found,
+and it is coming from a terminal,
the current update is postponed until
\fB\%refresh\fP(3X) or \fB\%doupdate\fP is called again.
This allows faster response to commands typed in advance.
-Normally, the input FILE
-pointer passed to \fB\%newterm\fP, or \fBstdin\fP in the case that
-\fB\%initscr\fP was used, will be used to do this typeahead checking.
+Normally,
+the input
+.I FILE
+pointer passed to \fB\%newterm\fP,
+or \fBstdin\fP in the case that \fB\%initscr\fP was used,
+will be used to do this typeahead checking.
The \fB\%typeahead\fP routine specifies that the file descriptor
\fIfd\fP is to be used to check for typeahead instead.
If \fIfd\fP is
-\-1, then no typeahead checking is done.
+\-1,
+then no typeahead checking is done.
.\"
.SH RETURN VALUE
-All routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
+All routines that return an integer return \fBERR\fP upon failure and
+\fBOK\fP
(SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('')
upon successful completion,
unless otherwise noted in the preceding routine descriptions.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not specify any error conditions.
In this implementation,
functions with a window parameter will return an error if it is null.
-Any function will also return an error if the terminal was not initialized.
+Any function will also return an error if the terminal was not
+initialized.
Also,
.RS 3
.TP 5
returns an error
if its parameter is outside the range 1..255.
.RE
+.SH NOTES
+\fBecho\fP,
+\fB\%noecho\fP,
+\fB\%halfdelay\fP,
+\fB\%intrflush\fP,
+\fBmeta\fP,
+\fBnl\fP,
+\fBnonl\fP,
+\fB\%nodelay\fP,
+\fB\%notimeout\fP,
+\fB\%noqiflush\fP,
+\fB\%qiflush\fP,
+\fB\%timeout\fP,
+and
+\fB\%wtimeout\fP
+may be implemented as macros.
+.PP
+\fB\%noraw\fP and \fB\%nocbreak\fP follow historical practice in that
+they attempt to restore normal (\*(``cooked\*('') mode
+from raw and cbreak modes respectively.
+Mixing \fBraw\fP/\fB\%noraw\fP and \fB\%cbreak\fP/\fB\%nocbreak\fP calls
+leads to terminal driver control states that are hard to predict or
+understand;
+doing so is not recommended.
.SH EXTENSIONS
-This implementation provides four functions which may be used to detect
-if the corresponding flags were set or reset:
+.I \%ncurses
+provides four \*(``is_\*('' functions that may be used to detect if the
+corresponding flags were set or reset.
.PP
.TS
-l l l.
-\fBQuery\fP \fBSet\fP \fBReset\fP
+center;
+Lb Lb Lb
+L L L .
+Query Set Reset
_
is_cbreak cbreak nocbreak
is_echo echo noecho
is_raw raw noraw
.TE
.PP
-In each case, the function returns
-.TP 5
+In each case,
+the function returns
+.TP 4 \" "-1" + 2n
1
if the flag is set,
-.TP 5
+.TP
0
-if the flag is reset, or
-.TP 5
+if the flag is reset,
+or
+.TP
\-1
-if the \fIcurses\fP library was not initialized.
+if the library is not initialized.
.PP
-These routines are specific to \fIncurses\fP.
-They were not supported on Version 7, BSD or System V implementations.
-It is recommended that any code depending on \fIncurses\fP extensions
-be conditioned using NCURSES_VERSION.
+They were designed for
+\fB\%ncurses\fP(3X),
+and are not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous
+.I curses
+implementation.
.SH PORTABILITY
-Except as noted in the section on extensions,
-these functions are described in the XSI Curses standard, Issue 4.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
.PP
-The \fIncurses\fP library obeys the XPG4 standard and the historical practice of the
-AT&T \fIcurses\fP implementations, in that the echo bit is cleared when \fIcurses\fP
+Except as noted in section \*(``EXTENSIONS\*('' above,
+X/Open Curses, Issue 4, Version 2 describes these functions.
+.PP
+.I \%ncurses
+follows X/Open Curses
+and the historical practice of AT&T
+.I curses
+implementations,
+in that the echo bit is cleared when
+.I curses
initializes the terminal state.
-BSD \fIcurses\fP differed from this slightly; it
-left the echo bit on at initialization, but the BSD \fBraw\fP call turned it
-off as a side-effect.
-For best portability, set \fBecho \fPor \fB\%noecho\fP explicitly
-just after initialization, even if your program remains in cooked mode.
+BSD
+.I curses
+differed from this slightly;
+it left the echo bit on at initialization,
+but the BSD \fBraw\fP call turned it off as a side effect.
+For best portability,
+set \fBecho\fP or \fB\%noecho\fP explicitly just after initialization,
+even if your program remains in cooked mode.
.PP
-The XSI Curses standard is ambiguous on the question of whether \fBraw\fP
-should disable the CRLF translations controlled by \fBnl\fP and \fBnonl\fP.
-BSD \fIcurses\fP did turn off these translations; AT&T \fIcurses\fP (at least as late as
-SVr1) did not.
-We chose to do so, on the theory that a programmer requesting
-raw input wants a clean (ideally 8-bit clean) connection that the operating
-system will not alter.
+X/Open Curses is ambiguous regarding whether \fBraw\fP should disable
+the CR/LF translations controlled by \fBnl\fP and \fBnonl\fP.
+BSD
+.I curses
+did turn off these translations;
+AT&T
+.I curses
+(at least as late as SVr1)
+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 \fB\%keypad\fP is first enabled,
-\fIncurses\fP loads the key-definitions for the current terminal description.
+.I \%ncurses
+loads the key definitions for the current terminal description.
If the terminal description includes extended string capabilities,
-e.g., from using the \fB\-x\fP option of \fB@TIC@\fP,
-then \fIncurses\fP also defines keys for the capabilities whose names
-begin with \*(``k\*(''.
-The corresponding keycodes are generated and (depending on previous
-loads of terminal descriptions) may differ from one execution of a
-program to the next.
-The generated keycodes are recognized by the \fB\%keyname\fP function
+e.g.,
+from using the
+.B \-x
+option of \fB\%@TIC@\fP,
+then
+.I \%ncurses
+also defines keys for the capabilities whose names begin with
+\*(``k\*(''.
+The corresponding keycodes are generated and
+(depending on previous loads of terminal descriptions)
+may differ from one execution of a program to the next.
+The generated keycodes are recognized by the \fB\%keyname\fP(3X)
+function
(which will then return a name beginning with \*(``k\*('' denoting the
-terminfo capability name rather than \*(``K\*('', used for \fIcurses\fP key-names).
-On the other hand, an application can use \fB\%define_key\fP to establish
+terminfo capability name rather than \*(``K\*('',
+used for
+.I curses
+key names).
+On the other hand,
+an application can use \fB\%define_key\fP(3X) to establish
a specific keycode for a given string.
This makes it possible for an application to check for an extended
capability's presence with \fB\%tigetstr\fP,
.PP
Low-level applications can use \fB\%tigetstr\fP to obtain the definition
of any particular string capability.
-Higher-level applications which use the \fIcurses\fP \fB\%wgetch\fP
-and similar functions to return keycodes rely upon the order in which
-the strings are loaded.
+Higher-level applications which use the
+.I curses
+\fB\%wgetch\fP and similar functions to return keycodes rely upon the
+order in which the strings are loaded.
If more than one key definition has the same string value,
then \fB\%wgetch\fP can return only one keycode.
-Most \fIcurses\fP implementations (including \fIncurses\fP)
+Most
+.I curses
+implementations
+(including
+.IR \%ncurses )
load key definitions in the order
defined by the array of string capability names.
The last key to be loaded determines the keycode which will be returned.
-In \fIncurses\fP, you may also have extended capabilities interpreted as
-key definitions.
+In
+.IR \%ncurses ,
+you may also have extended capabilities 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.
-.SH NOTES
-Note that
-\fBecho\fP,
-\fB\%noecho\fP,
-\fB\%halfdelay\fP,
-\fB\%intrflush\fP,
-\fBmeta\fP,
-\fBnl\fP,
-\fBnonl\fP,
-\fB\%nodelay\fP,
-\fB\%notimeout\fP,
-\fB\%noqiflush\fP,
-\fB\%qiflush\fP,
-\fB\%timeout\fP, and
-\fB\%wtimeout\fP may be macros.
-.PP
-The \fB\%noraw\fP and \fB\%nocbreak\fP calls follow historical practice in that
-they attempt to restore to normal (\*(``cooked\*('') mode
-from raw and cbreak modes respectively.
-Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver
-control states that are hard to predict or understand; it is not recommended.
+.SH HISTORY
+Formerly,
+.I \%ncurses
+used
+.B \%nl
+and
+.B \%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 were controlled via a single option
+.BR \%CRMOD ,
+while the latter separates these features.
+Because that conversion interferes with output optimization,
+.I \%ncurses
+6.2 (2020) amended
+.B \%nl
+and
+.B \%nonl
+to eliminate their effect on output.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_getch\fP(3X),
projects / ncurses.git / blobdiff