-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
-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 window argument is ignored.
-.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
-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\fR is
-called. The default value for keypad is false.
-.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
-purpose of the timeout is to differentiate between sequences received
-from a function key and those typed by a user.
-.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
-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\fR.
-.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
-handler if you want output to continue as though the interrupt
-had not occurred, after the handler exits.
-.PP
-The \fBtimeout\fR and \fBwtimeout\fR routines set blocking or
-non-blocking read for a given window. If \fIdelay\fR 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,
-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.
+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
+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
+.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
+.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 ),
+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
+.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
+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,
+.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"
+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
+.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 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 "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 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 "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
+.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 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.
+.\"
projects / ncurses.git / blobdiff