diff options
Diffstat (limited to 'man/curs_inopts.3x')
| -rw-r--r-- | man/curs_inopts.3x | 939 |
1 files changed, 641 insertions, 298 deletions
diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x index 63db4967eebc..c0db26d6fd1c 100644 --- a/man/curs_inopts.3x +++ b/man/curs_inopts.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" 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 * @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $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" +.\" $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 @@ -40,6 +40,11 @@ .ie t .ds '' '' .el .ds '' "" .\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .SH NAME \fB\%cbreak\fP, \fB\%echo\fP, @@ -75,24 +80,24 @@ get and set \fIcurses\fR terminal input options \fBint echo(void); \fBint noecho(void); .PP -\fBint intrflush(WINDOW *\fIwin\fP, bool \fIbf\fP); -\fBint keypad(WINDOW *\fIwin\fP, bool \fIbf\fP); -\fBint meta(WINDOW *\fIwin\fP, bool \fIbf\fP); -\fBint nodelay(WINDOW *\fIwin\fP, bool \fIbf\fP); -\fBint notimeout(WINDOW *\fIwin\fP, bool \fIbf\fP); +\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 -\fBint raw(void); -\fBint noraw(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); +\fBvoid wtimeout(WINDOW * \fIwin\fP, int \fIdelay\fP); .PP \fBint typeahead(int \fIfd\fP); .PP @@ -103,287 +108,552 @@ get and set \fIcurses\fR terminal input options \fBint is_raw(void); .fi .SH DESCRIPTION -.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 -desired. +.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 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 +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. -The \fB\%nocbreak\fP routine returns the terminal to normal (cooked) -mode. +.B \%nocbreak +restores canonical (\*(``cooked\*('') mode. .PP -Initially the terminal may or may not be in \fB\%cbreak\fP mode, -as the mode is inherited; +The state of the terminal is unknown to a +.I curses +application when it starts; therefore, -a program should call \fB\%cbreak\fP or \fB\%nocbreak\fP explicitly. +a program should call +.B \%cbreak +or +.B \%nocbreak +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.] +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" -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, +.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 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.] +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 -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. +.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 \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. +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 -If the \fB\%intrflush\fP option is enabled -.RI ( bf +.B \%intrflush +calls +.B \%qiflush +(see below) +if +.I 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 +.BR TRUE "," +and +.B \%noqiflush +if +.I bf is -.BR FALSE ), -prevents the flush. -The default for the option is inherited from the terminal driver -settings. -The +.BR FALSE "." +It ignores its .I win -argument is ignored. +argument. .\" .SS keypad -The \fB\%keypad\fP option enables the keypad of the user's terminal. +.B keypad +enables recognition of a terminal's function keys. If 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. +.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 -(\fIbf\fP is \fBFALSE\fP), +.RI ( bf +is +.BR FALSE ), .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. +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 significant bits on input depends on -the control mode of the terminal driver [see \fI\%termios\fP(3)]. +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, -invoke -\fBmeta\fP(\fIwin\fP, \fBTRUE\fP); +call +.BR meta( .\|.\|. , +.BR TRUE) ; this is equivalent, -under POSIX, +on POSIX systems, to setting the CS8 flag on the terminal. To force 7 bits to be returned, -invoke -\fBmeta\fP(\fIwin\fP, \fBFALSE\fP); +call +.BR meta( .\|.\|. , +.BR FALSE) ; this is equivalent, -under POSIX, +on POSIX systems, to setting the CS7 flag on the terminal. -The window argument, -.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. +.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" -The \fBnl\fP and \fBnonl\fP routines control whether the underlying -display device translates the return key into newline on input. +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 -The \fB\%nodelay\fP option causes \fB\%getch\fP to be a non-blocking -call. +.B \%nodelay +configures the input character reading function to be non-blocking for +window +.IR "win" . If no input is ready, -\fB\%getch\fP returns \fBERR\fP. +the reading function returns +.BR ERR "." If disabled .RI ( bf is .BR FALSE ), -\fB\%getch\fP waits until a key is pressed. +the reading function does not return until it has input. .SS notimeout -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. +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" -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, +.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 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, 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. +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" -The \fB\%timeout\fP and \fB\%wtimeout\fP routines set blocking or -non-blocking read for a given window. -If \fIdelay\fP is negative, -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). +.B \%wtimeout +configures whether a +.I curses +input character reading function called on window +.I win +uses blocking or non-blocking reads. If -\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). +.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 -.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 +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 -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. +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 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 -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. -Also, -.RS 3 -.TP 5 -\fB\%halfdelay\fP -returns an error -if its parameter is outside the range 1..255. -.RE +See section \*(``EXTENSIONS\*('' below for the +return values of +.BR is_cbreak "," +.BR is_echo "," +.BR is_nl "," +and +.BR is_raw "." .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, +.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 -\fB\%wtimeout\fP +.B \%wtimeout 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; +.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 that may be used to detect if the -corresponding flags were set or reset. +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; @@ -399,26 +669,18 @@ is_raw raw noraw .PP In each case, the function returns -.TP 4 \" "-1" + 2n -1 -if the flag is set, +.TP 5 \" "-1" + 2n tag separation + 1n fudge for typesetters like grops +.B 1 +if the option is set, .TP -0 -if the flag is reset, +.B 0 +if the option is unset, or .TP -\-1 -if the library is not initialized. -.PP -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. +.B \-1 +if the library's +.I \%TERMINAL +structure for the device has not been initialized. .SH PORTABILITY Applications employing .I \%ncurses @@ -427,33 +689,54 @@ extensions should condition their use on the visibility of the preprocessor macro. .PP Except as noted in section \*(``EXTENSIONS\*('' above, -X/Open Curses, Issue 4, Version 2 describes these functions. +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 AT&T -.I curses -implementations, -in that the echo bit is cleared when -.I curses -initializes the terminal state. +and the historical practice of System\ V +.IR curses "," +clearing the terminal driver's \*(``echo\*('' flag when initializing the +screen. 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. +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, -set \fBecho\fP or \fB\%noecho\fP explicitly just after initialization, -even if your program remains in cooked mode. +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 \fBraw\fP should disable -the CR/LF translations controlled by \fBnl\fP and \fBnonl\fP. +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; -AT&T +turned off these translations; +System\ V .I curses -(at least as late as SVr1) did not. .I \%ncurses does so, @@ -462,65 +745,124 @@ on the assumption that a programmer requesting raw input wants a clean 8-bit clean) connection that the operating system will not alter. .PP -When \fB\%keypad\fP is first enabled, +When +.B \%keypad +is first enabled for a window, .I \%ncurses -loads the key definitions for the current terminal description. -If the terminal description includes extended string capabilities, -e.g., -from using the +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, +option of \fB\%@TIC@\fP(1), +for example, then .I \%ncurses -also defines keys for the capabilities whose names begin with +also defines keys for the capabilities whose codes 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\*('', +.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). +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, -and reassign the keycode to match its own needs. +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 to obtain the definition -of any particular string capability. -Higher-level applications which use the +Low-level applications can use \fB\%tigetstr\fP(3X) to obtain the +definition of any string capability. .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. +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. +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 , -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. +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 -.B \%nl +.I \%nl and -.B \%nonl +.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. @@ -535,15 +877,15 @@ to .I \%termios (the POSIX terminal API). In the former, -both input and output were controlled via a single option -.BR \%CRMOD , +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 -.B \%nl +.I \%nl and -.B \%nonl +.I \%nonl to eliminate their effect on output. .SH SEE ALSO \fB\%curses\fP(3X), @@ -551,4 +893,5 @@ to eliminate their effect on output. \fB\%curs_initscr\fP(3X), \fB\%curs_util\fP(3X), \fB\%define_key\fP(3X), -\fB\%termios\fP(3) +\fB\%termios\fP(3), +\fB\%term_variables\fP(3X) |