.\"***************************************************************************
-.\" Copyright (c) 1998-2003,2005 Free Software Foundation, Inc. *
+.\" Copyright 2018-2020,2021 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inopts.3x,v 1.13 2005/05/15 16:18:07 tom Exp $
+.\" $Id: curs_inopts.3x,v 1.35 2021/12/25 21:49:32 tom Exp $
.TH curs_inopts 3X ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.na
.hy 0
.SH NAME
-\fBcbreak\fR,
-\fBnocbreak\fR,
-\fBecho\fR,
-\fBnoecho\fR,
-\fBhalfdelay\fR,
-\fBintrflush\fR,
-\fBkeypad\fR,
-\fBmeta\fR,
-\fBnodelay\fR,
-\fBnotimeout\fR,
-\fBraw\fR,
-\fBnoraw\fR,
-\fBnoqiflush\fR,
-\fBqiflush\fR,
-\fBtimeout\fR,
-\fBwtimeout\fR,
-\fBtypeahead\fR - \fBcurses\fR input options
+\fBcbreak\fP,
+\fBnocbreak\fP,
+\fBecho\fP,
+\fBnoecho\fP,
+\fBhalfdelay\fP,
+\fBintrflush\fP,
+\fBkeypad\fP,
+\fBmeta\fP,
+\fBnl\fP,
+\fBnonl\fP,
+\fBnodelay\fP,
+\fBnotimeout\fP,
+\fBraw\fP,
+\fBnoraw\fP,
+\fBqiflush\fP,
+\fBnoqiflush\fP,
+\fBtimeout\fP,
+\fBwtimeout\fP,
+\fBtypeahead\fP \- \fBcurses\fP input options
.ad
.hy
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+\fB#include <curses.h>\fP
.PP
-\fBint cbreak(void);\fR
+\fBint cbreak(void);\fP
.br
-\fBint nocbreak(void);\fR
+\fBint nocbreak(void);\fP
+.sp
+\fBint echo(void);\fP
.br
-\fBint echo(void);\fR
+\fBint noecho(void);\fP
+.sp
+\fBint intrflush(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fP
.br
-\fBint noecho(void);\fR
+\fBint keypad(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fP
.br
-\fBint halfdelay(int tenths);\fR
+\fBint meta(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fP
.br
-\fBint intrflush(WINDOW *win, bool bf);\fR
+\fBint nodelay(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fP
.br
-\fBint keypad(WINDOW *win, bool bf);\fR
+\fBint notimeout(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fP
+.sp
+\fBint nl(void);\fP
.br
-\fBint meta(WINDOW *win, bool bf);\fR
+\fBint nonl(void);\fP
+.sp
+\fBint raw(void);\fP
.br
-\fBint nodelay(WINDOW *win, bool bf);\fR
+\fBint noraw(void);\fP
+.sp
+\fBvoid qiflush(void);\fP
.br
-\fBint raw(void);\fR
+\fBvoid noqiflush(void);\fP
+.sp
+\fBint halfdelay(int \fP\fItenths\fP\fB);\fP
.br
-\fBint noraw(void);\fR
+\fBvoid timeout(int \fP\fIdelay\fP\fB);\fP
.br
-\fBvoid noqiflush(void);\fR
-.br
-\fBvoid qiflush(void);\fR
-.br
-\fBint notimeout(WINDOW *win, bool bf);\fR
-.br
-\fBvoid timeout(int delay);\fR
-.br
-\fBvoid wtimeout(WINDOW *win, int delay);\fR
-.br
-\fBint typeahead(int fd);\fR
+\fBvoid wtimeout(WINDOW *\fP\fIwin\fP\fB, int \fP\fIdelay\fP\fB);\fP
+.sp
+\fBint typeahead(int \fP\fIfd\fP\fB);\fP
.br
.SH DESCRIPTION
+The \fBncurses\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.
+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.
+.\"
+.SS cbreak/nocbreak
Normally, the tty driver buffers typed characters until a newline or carriage
-return is typed. The \fBcbreak\fR routine disables line buffering and
+return is typed.
+The \fBcbreak\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
-program. The \fBnocbreak\fR routine returns the terminal to normal (cooked)
+program.
+The \fBnocbreak\fP routine returns the terminal to normal (cooked)
mode.
.PP
-Initially the terminal may or may not be in \fBcbreak\fR mode, as the mode is
-inherited; therefore, a program should call \fBcbreak\fR or \fBnocbreak\fR
-explicitly. Most interactive programs using \fBcurses\fR set the \fBcbreak\fR
-mode. Note that \fBcbreak\fR overrides \fBraw\fR.
-[See \fBcurs_getch\fR(3X) for a
-discussion of how these routines interact with \fBecho\fR and \fBnoecho\fR.]
-.PP
-The \fBecho\fR and \fBnoecho\fR routines control whether characters typed by
-the user are echoed by \fBgetch\fR as they are typed. Echoing by the tty
-driver is always disabled, but initially \fBgetch\fR is in echo mode, so
-characters typed are echoed. Authors of most interactive programs prefer to do
+Initially the terminal may or may not be in \fBcbreak\fP mode, as the mode is
+inherited; therefore, a program should call \fBcbreak\fP or \fBnocbreak\fP
+explicitly.
+Most interactive programs using \fBcurses\fP set the \fBcbreak\fP
+mode.
+Note that \fBcbreak\fP overrides \fBraw\fP.
+[See \fBcurs_getch\fP(3X) for a
+discussion of how these routines interact with \fBecho\fP and \fBnoecho\fP.]
+.\"
+.SS echo/noecho
+.PP
+The \fBecho\fP and \fBnoecho\fP routines control whether characters typed by
+the user are echoed by \fBgetch\fP(3X) as they are typed.
+Echoing by the tty
+driver is always disabled, but initially \fBgetch\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 \fBnoecho\fR.
-[See \fBcurs_getch\fR(3X) for a
-discussion of how these routines interact with \fBcbreak\fR and
-\fBnocbreak\fR.]
-.PP
-The \fBhalfdelay\fR routine is used for half-delay mode, which is similar to
-\fBcbreak\fR mode in that characters typed by the user are immediately
-available to the program. However, after blocking for \fItenths\fR tenths of
-seconds, ERR is returned if nothing has been typed. The value of \fBtenths\fR
-must be a number between 1 and 255. Use \fBnocbreak\fR to leave half-delay
+they disable echoing by calling \fBnoecho\fP.
+[See \fBcurs_getch\fP(3X) for a
+discussion of how these routines interact with \fBcbreak\fP and
+\fBnocbreak\fP.]
+.\"
+.SS halfdelay
+.PP
+The \fBhalfdelay\fP routine is used for half-delay mode, which is similar to
+\fBcbreak\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 \fBnocbreak\fP to leave half-delay
mode.
+.\"
+.SS intrflush
.PP
-If the \fBintrflush\fR option is enabled, (\fIbf\fR is \fBTRUE\fR), when an
-interrupt key is pressed on the keyboard (interrupt, break, quit) all output in
+If the \fBintrflush\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 \fBcurses\fR to have the wrong idea of what is on
-the screen. Disabling (\fIbf\fR is \fBFALSE\fR), the option prevents the
-flush. The default for the option is inherited from the tty driver settings.
+the interrupt, but causing \fBcurses\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.
+.\"
+.SS keypad
.PP
-The \fBkeypad\fR option enables the keypad of the user's terminal. If
-enabled (\fIbf\fR is \fBTRUE\fR), the user can press a function key
-(such as an arrow key) and \fBwgetch\fR returns a single value
-representing the function key, as in \fBKEY_LEFT\fR. If disabled
-(\fIbf\fR is \fBFALSE\fR), \fBcurses\fR does not treat function keys
+The \fBkeypad\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 \fBwgetch\fP(3X) returns a single value
+representing the function key, as in \fBKEY_LEFT\fP.
+If disabled
+(\fIbf\fP is \fBFALSE\fP), \fBcurses\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
+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 \fBwgetch\fR is
-called. The default value for keypad is false.
+causes the terminal keypad to be turned on when \fBwgetch\fP(3X) is
+called.
+The default value for keypad is \fBFALSE\fP.
+.\"
+.SS meta
.PP
Initially, whether the terminal returns 7 or 8 significant bits on
-input depends on the control mode of the tty driver [see termio(7)].
-To force 8 bits to be returned, invoke \fBmeta\fR(\fIwin\fR,
-\fBTRUE\fR); this is equivalent, under POSIX, to setting the CS8 flag
-on the terminal. To force 7 bits to be returned, invoke
-\fBmeta\fR(\fIwin\fR, \fBFALSE\fR); this is equivalent, under POSIX,
-to setting the CS7 flag on the terminal. The window argument,
-\fIwin\fR, is always ignored. If the terminfo capabilities \fBsmm\fR
-(meta_on) and \fBrmm\fR (meta_off) are defined for the terminal,
-\fBsmm\fR is sent to the terminal when \fBmeta\fR(\fIwin\fR,
-\fBTRUE\fR) is called and \fBrmm\fR is sent when \fBmeta\fR(\fIwin\fR,
-\fBFALSE\fR) is called.
-.PP
-The \fBnodelay\fR option causes \fBgetch\fR to be a non-blocking call.
-If no input is ready, \fBgetch\fR returns \fBERR\fR. If disabled
-(\fIbf\fR is \fBFALSE\fR), \fBgetch\fR waits until a key is pressed.
-.PP
-While interpreting an input escape sequence, \fBwgetch\fR sets a timer
-while waiting for the next character. If \fBnotimeout(\fR\fIwin\fR,
-\fBTRUE\fR) is called, then \fBwgetch\fR does not set a timer. The
+input depends on the control mode of the tty driver [see \fBtermios\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.
+.\"
+.SS nl/nonl
+.PP
+The \fBnl\fP and \fBnonl\fP routines control whether the underlying display
+device translates the return key into newline on input.
+.\"
+.SS nodelay
+.PP
+The \fBnodelay\fP option causes \fBgetch\fP to be a non-blocking call.
+If no input is ready, \fBgetch\fP returns \fBERR\fP.
+If disabled
+(\fIbf\fP is \fBFALSE\fP), \fBgetch\fP waits until a key is pressed.
+.SS notimeout
+.PP
+When interpreting an escape sequence, \fBwgetch\fP(3X) sets a timer
+while waiting for the next character.
+If \fBnotimeout(\fP\fIwin\fP,
+\fBTRUE\fP) is called, then \fBwgetch\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.
+.\"
+.SS raw/noraw
.PP
-The \fBraw\fR and \fBnoraw\fR routines place the terminal into or out of raw
-mode. Raw mode is similar to \fBcbreak\fR mode, in that characters typed are
-immediately passed through to the user program. The differences are that in
+The \fBraw\fP and \fBnoraw\fP routines place the terminal into or out of raw
+mode.
+Raw mode is similar to \fBcbreak\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
+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
-\fBcurses\fR.
+\fBcurses\fP.
+.\"
+.SS qiflush/noqiflush
.PP
-When the \fBnoqiflush\fR routine is used, normal flush of input and
-output queues associated with the \fBINTR\fR, \fBQUIT\fR and
-\fBSUSP\fR characters will not be done [see termio(7)]. When
-\fBqiflush\fR is called, the queues will be flushed when these control
-characters are read. You may want to call \fBnoqiflush()\fR in a signal
+When the \fBnoqiflush\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 \fBtermios\fP(3)].
+When
+\fBqiflush\fP is called, the queues will be flushed when these control
+characters are read.
+You may want to call \fBnoqiflush\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
.PP
-The \fBtimeout\fR and \fBwtimeout\fR routines set blocking or
-non-blocking read for a given window. If \fIdelay\fR is negative,
+The \fBtimeout\fP and \fBwtimeout\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\fR is zero, then non-blocking read is used
-(i.e., read returns \fBERR\fR if no input is waiting). If
-\fIdelay\fR is positive, then read blocks for \fIdelay\fR
-milliseconds, and returns \fBERR\fR if there is still no input.
-Hence, these routines provide the same functionality as \fBnodelay\fR,
+input).
+If \fIdelay\fP is zero, then non-blocking read is used
+(i.e., 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 \fBnodelay\fP,
plus the additional capability of being able to block for only
-\fIdelay\fR milliseconds (where \fIdelay\fR is positive).
-.PP
-The \fBcurses\fR 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, the current update is postponed until
-\fBrefresh\fR or \fBdoupdate\fR is called again. This allows faster
-response to commands typed in advance. Normally, the input FILE
-pointer passed to \fBnewterm\fR, or \fBstdin\fR in the case that
-\fBinitscr\fR was used, will be used to do this typeahead checking.
-The \fBtypeahead\fR routine specifies that the file descriptor
-\fIfd\fR is to be used to check for typeahead instead. If \fIfd\fR is
--1, then no typeahead checking is done.
+\fIdelay\fP milliseconds (where \fIdelay\fP is positive).
+.\"
+.SS typeahead
+.PP
+The \fBcurses\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,
+the current update is postponed until
+\fBrefresh\fP(3X) or \fBdoupdate\fP is called again.
+This allows faster response to commands typed in advance.
+Normally, the input FILE
+pointer passed to \fBnewterm\fP, or \fBstdin\fP in the case that
+\fBinitscr\fP was used, will be used to do this typeahead checking.
+The \fBtypeahead\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.
+.\"
.SH RETURN VALUE
-All routines that return an integer return \fBERR\fR upon failure and OK (SVr4
-specifies only "an integer value other than \fBERR\fR") upon successful
-completion, unless otherwise noted in the preceding routine descriptions.
+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.
In this implementation,
.PP
The ncurses library obeys the XPG4 standard and the historical practice of the
AT&T curses implementations, in that the echo bit is cleared when curses
-initializes the terminal state. BSD curses differed from this slightly; it
-left the echo bit on at initialization, but the BSD \fBraw\fR call turned it
-off as a side-effect. For best portability, set echo or noecho explicitly
+initializes the terminal state.
+BSD 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 \fPor \fBnoecho\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 curses did turn off these translations; AT&T curses (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.
+.PP
+When \fBkeypad\fP is first enabled,
+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 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 \fBkeyname\fP function
+(which will then return 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 \fBdefine_key\fP 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 \fBtigetstr\fP,
+and reassign the keycode to match its own needs.
+.PP
+Low-level applications can use \fBtigetstr\fP to obtain the definition
+of any particular string capability.
+Higher-level applications which use the curses \fBwgetch\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 \fBwgetch\fP can return only one keycode.
+Most curses implementations (including 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 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\fR, \fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR,
-\fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBnoqiflush\fR,
-\fBqiflush\fR, \fBtimeout\fR, and \fBwtimeout\fR may be macros.
+Note that
+\fBecho\fP,
+\fBnoecho\fP,
+\fBhalfdelay\fP,
+\fBintrflush\fP,
+\fBmeta\fP,
+\fBnl\fP,
+\fBnonl\fP,
+\fBnodelay\fP,
+\fBnotimeout\fP,
+\fBnoqiflush\fP,
+\fBqiflush\fP,
+\fBtimeout\fP, and
+\fBwtimeout\fP may be macros.
.PP
-The \fBnoraw\fR and \fBnocbreak\fR 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
+The \fBnoraw\fP and \fBnocbreak\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 SEE ALSO
-\fBcurses\fR(3X), \fBcurs_getch\fR(3X), \fBcurs_initscr\fR(3X), \fBtermio\fR(7)
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fBcurses\fP(3X),
+\fBcurs_getch\fP(3X),
+\fBcurs_initscr\fP(3X),
+\fBcurs_util\fP(3X),
+\fBdefine_key\fP(3X),
+\fBtermios\fP(3)
projects / ncurses.git / blobdiff