+'\" t
.\"***************************************************************************
-.\" Copyright 2018-2021,2022 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.36 2022/02/12 20:07:29 tom Exp $
-.TH curs_inopts 3X ""
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
-.na
-.hy 0
+.\" $Id: curs_inopts.3x,v 1.68 2024/05/25 20:41:48 tom Exp $
+.TH curs_inopts 3X 2024-05-25 "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
-\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
+\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
-\fB#include <curses.h>\fP
+.nf
+\fB#include <curses.h>
.PP
-\fBint cbreak(void);\fP
-.br
-\fBint nocbreak(void);\fP
-.sp
-\fBint echo(void);\fP
-.br
-\fBint noecho(void);\fP
-.sp
-\fBint intrflush(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.br
-\fBint keypad(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.br
-\fBint meta(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.br
-\fBint nodelay(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.br
-\fBint notimeout(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.sp
-\fBint nl(void);\fP
-.br
-\fBint nonl(void);\fP
-.sp
-\fBint raw(void);\fP
-.br
-\fBint noraw(void);\fP
-.sp
-\fBvoid qiflush(void);\fP
-.br
-\fBvoid noqiflush(void);\fP
-.sp
-\fBint halfdelay(int \fItenths\fB);\fR
-.br
-\fBvoid timeout(int \fIdelay\fB);\fR
-.br
-\fBvoid wtimeout(WINDOW *\fIwin\fB, int \fIdelay\fB);\fR
-.sp
-\fBint typeahead(int \fIfd\fB);\fR
-.br
+\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
-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.
+.I 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.
+.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 tty driver buffers typed characters until a newline or carriage
-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
+.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.
+.B \%cbreak
+configures the terminal in
+.IR "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.
-The \fBnocbreak\fP routine returns the terminal to normal (cooked)
-mode.
+.B \%nocbreak
+returns the terminal to normal (\*(``cooked\*('') mode.
.PP
-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
+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 \fBcurses\fP set the \fBcbreak\fP
+Most interactive programs using
+.I curses
+set \%cbreak
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.]
+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
-.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\fP.
-[See \fBcurs_getch\fP(3X) for a
-discussion of how these routines interact with \fBcbreak\fP and
-\fBnocbreak\fP.]
+.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
+window has its echo flag 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
-.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.
+.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
+tenths of 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
-.PP
-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\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.
+.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
-.PP
-The \fBkeypad\fP option enables the keypad of the user's terminal.
+.B keypad
+enables recognition of a terminal's function keys.
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.
+enabled
+.RI ( bf
+is
+.BR TRUE ),
+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 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
-transmit) and off (made to work locally), turning on this option
-causes the terminal keypad to be turned on when \fBwgetch\fP(3X) is
-called.
-The default value for keypad is \fBFALSE\fP.
+.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's keypad can be turned on
+(made to transmit)
+and off
+(made to work locally),
+.B \%keypad
+configures it consistently with the
+.I bf
+parameter.
+By default,
+a window's keypad mode is off.
.\"
.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 \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,
+Initially,
+whether the terminal returns 7- or 8-bit character codes on input
+depends on the configuration of the terminal driver;
+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.
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
+.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
+.B smm
+to the terminal and disabling it sends
+.B rmm
+to the terminal.
.\"
-.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 "nl, nonl"
+Initially,
+whether the terminal reports a carriage return
+using the character code for a line feed
+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.
.\"
.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.
+.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
-(\fIbf\fP is \fBFALSE\fP), \fBgetch\fP waits until a key is pressed.
+.RI ( bf
+is
+.BR FALSE ),
+the reading function does not return until it has input.
.SS notimeout
-.PP
-When interpreting an escape sequence, \fBwgetch\fP(3X) sets a timer
-while waiting for the next character.
-If \fBnotimeout(\fIwin\fR,
-\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.
+When the input character reading function reads an ESC character,
+it sets a timer while waiting for the next character.
+.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.
+To configure the timeout rather than disabling it,
+see
+.B \%wtimeout
+below.
.\"
-.SS raw/noraw
-.PP
-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
-the BREAK key depends on other bits in the tty driver that are not set by
-\fBcurses\fP.
+.SS "qiflush, noqiflush"
.\"
-.SS qiflush/noqiflush
-.PP
-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.
+.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 in
+.I \%cbreak
+and \*(``cooked\*('' modes;
+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 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
+.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 you want output to continue
+after the handler exits
+as though the interrupt had not occurred.
.\"
-.SS timeout/wtimeout
-.PP
-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\fP is zero, then non-blocking read is used
-(i.e., read returns \fBERR\fP if no input is waiting).
+.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
+exits raw mode.
+.\"
+.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,
+a blocking read is used,
+waiting indefinitely for input.
+If
+.I delay
+is zero,
+a non-blocking read is used;
+an input character reading function returns
+.B ERR
+if no input is pending.
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\fP milliseconds (where \fIdelay\fP is positive).
+.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
-.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.
+Normally,
+a
+.I curses
+library checks the terminal for input while updating the screen.
+If any is found,
+the update is postponed 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
-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.
+.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 terminal is not initialized or
+.bP
+.I win
+is
+.B NULL
+(except for
+.B \%intrflush
+and
+.BR meta ","
+which ignore its value).
.PP
-X/Open does not define 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.
-Also,
-.RS
-.TP 5
-\fBhalfdelay\fP
-returns an error
-if its parameter is outside the range 1..255.
-.RE
+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 normal
+(\*(``cooked\*('') mode from raw and cbreak modes,
+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.
+.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 flag is set,
+.TP
+.B 0
+if the flag is reset,
+or
+.TP
+.B \-1
+if the library is not initialized.
.SH PORTABILITY
-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
+Except as noted in section \*(``EXTENSIONS\*('' above,
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+SVr4
+.I curses
+describes a successful return value only as
+\*(``an integer value other than
+.BR ERR \*(''.
.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\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.
+.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
+.B echo
+or
+.B \%noecho
+explicitly just after initialization,
+even if your program remains in normal (\*(``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.
+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
+did turn 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 \fBkeypad\fP is first enabled,
-ncurses loads the key-definitions for the current terminal description.
+When
+.B \%keypad
+is first enabled,
+.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 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,
+for example,
+by using the
+.B \-x
+option of \fB\%@TIC@\fP(1),
+then
+.I \%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 keycodes are recognized by the \fB\%keyname\fP(3X)
+function
+(which then returns a name beginning with \*(``k\*('' denoting the
+.I \%term\%info
+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 bind
+a specific key to a string of the programmer's choice.
+This feature enables an application to check for an extended
+capability's presence with \fB\%tigetstr\fP(3X),
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)
+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
-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.
+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.
These are loaded after the predefined keys,
-and if a capability's value is the same as a previously-loaded
+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,
-\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.
+.SH HISTORY
+4BSD
+.I curses
+(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
-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.
+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 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
-\fBcurses\fP(3X),
-\fBcurs_getch\fP(3X),
-\fBcurs_initscr\fP(3X),
-\fBcurs_util\fP(3X),
-\fBdefine_key\fP(3X),
-\fBtermios\fP(3)
+\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\%term_variables\fP(3X),
+\fB\%termios\fP(3)
projects / ncurses.git / blobdiff