X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_inopts.3x.html;h=4bee87ac6af6a337478dc9904cb964962be50c9f;hb=HEAD;hp=cce3059a60ed1e44621373a3e2e36ad07db00b41;hpb=bca50d0d8592defee6c584fdedd25f4b1a31345b;p=ncurses.git diff --git a/doc/html/man/curs_inopts.3x.html b/doc/html/man/curs_inopts.3x.html index cce3059a..30829c59 100644 --- a/doc/html/man/curs_inopts.3x.html +++ b/doc/html/man/curs_inopts.3x.html @@ -1,6 +1,8 @@ -
--curs_inopts(3x) curs_inopts(3x) +curs_inopts(3x) Library calls curs_inopts(3x)
- cbreak, nocbreak, echo, noecho, halfdelay, intrflush, keypad, meta, - nodelay, notimeout, raw, noraw, noqiflush, qiflush, timeout, wtimeout, - typeahead - curses input options + cbreak, echo, halfdelay, intrflush, is_cbreak, is_echo, is_nl, is_raw, + keypad, meta, nl, nocbreak, nodelay, noecho, nonl, noqiflush, noraw, + notimeout, qiflush, raw, timeout, wtimeout, typeahead - get and set + curses terminal input options
@@ -56,229 +59,330 @@ int cbreak(void); int nocbreak(void); + int echo(void); int noecho(void); - int halfdelay(int tenths); - int intrflush(WINDOW *win, bool bf); - int keypad(WINDOW *win, bool bf); - int meta(WINDOW *win, bool bf); - int nodelay(WINDOW *win, bool bf); + + int intrflush(WINDOW * win /* ignored */, bool bf); + int keypad(WINDOW * win, bool bf); + int meta(WINDOW * win /* ignored */, bool bf); + int nodelay(WINDOW * win, bool bf); + int notimeout(WINDOW * win, bool bf); + + int nl(void); + int nonl(void); + + void qiflush(void); + void noqiflush(void); + int raw(void); int noraw(void); - void noqiflush(void); - void qiflush(void); - int notimeout(WINDOW *win, bool bf); - void timeout(int delay); - void wtimeout(WINDOW *win, int delay); - int typeahead(int fd); + + int halfdelay(int tenths); + void timeout(int delay); + void wtimeout(WINDOW * win, int delay); + + int typeahead(int fd); + + /* extensions */ + int is_cbreak(void); + int is_echo(void); + int is_nl(void); + int is_raw(void);
- The ncurses 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. Win- - dow-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. - - -
- Normally, the tty driver buffers typed characters until a newline or - carriage return is typed. The cbreak routine disables line buffering - and erase/kill character-processing (interrupt and flow control charac- - ters are unaffected), making characters typed by the user immediately - available to the program. The nocbreak routine returns the terminal to - normal (cooked) mode. - - Initially the terminal may or may not be in cbreak mode, as the mode is - inherited; therefore, a program should call cbreak or nocbreak explic- - itly. Most interactive programs using curses set the cbreak mode. - Note that cbreak overrides raw. [See curs_getch(3x) for a discussion - of how these routines interact with echo and noecho.] - - -
- The echo and noecho routines control whether characters typed by the - user are echoed by getch(3x) as they are typed. Echoing by the tty - driver is always disabled, but initially getch is in echo mode, so - characters typed are echoed. Authors of most interactive programs pre- - fer to do their own echoing in a controlled area of the screen, or not - to echo at all, so they disable echoing by calling noecho. [See - curs_getch(3x) for a discussion of how these routines interact with - cbreak and nocbreak.] + 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. + + Some descriptions below make reference to an input character reading + function: this is wgetch(3x) in the non-wide character curses API and + wget_wch(3x) in the wide character API. In addition to the variant + forms of these described in ncurses(3x), the curses functions + wgetstr(3x) and wget_wstr(3x) and their own variants call the + appropriate input character reading function. + + +
+ Normally, the terminal driver buffers typed characters, not delivering + them to an application until a line feed or carriage return is typed. + cbreak configures the terminal in 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. + nocbreak returns the terminal to normal ("cooked") mode. + + The state of the terminal is unknown to a curses application when it + starts; therefore, a program should call cbreak or nocbreak explicitly. + Most interactive programs using curses set cbreak mode. Calling cbreak + overrides raw. The man page for the input character reading function + discusses how cbreak and nocbreak interact with echo and noecho. + + +
+ echo and noecho determine whether characters typed by the user are + written to the curses window by the input character reading function as + they are typed. curses always disables the terminal driver's own + echoing. By default, a 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 call + noecho. The man page for the input character reading function + discusses how echo and noecho interact with cbreak and nocbreak.
- The halfdelay routine is used for half-delay mode, which is similar to - cbreak mode in that characters typed by the user are immediately avail- - able to the program. However, after blocking for tenths tenths of sec- - onds, ERR is returned if nothing has been typed. The value of tenths - must be a number between 1 and 255. Use nocbreak to leave half-delay - mode. + halfdelay configures 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 tenths tenths of seconds, an + input character reading function returns ERR if no input is pending. + The value of tenths must be between 1 and 255. Use nocbreak to leave + half-delay mode.
- If the intrflush option is enabled (bf is TRUE), 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 curses to have the wrong idea of what is - on the screen. Disabling the option (bf is FALSE) prevents the flush. - The default for the option is inherited from the tty driver settings. - The window argument is ignored. + intrflush calls qiflush (see below) if bf is TRUE, and noqiflush if bf + is FALSE. It ignores its win argument.
- The keypad option enables the keypad of the user's terminal. If en- - abled (bf is TRUE), the user can press a function key (such as an arrow - key) and wgetch(3x) returns a single value representing the function - key, as in KEY_LEFT. If disabled (bf is FALSE), curses does not treat - function keys specially and the program has to interpret the escape se- - quences 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 wgetch(3x) is called. - The default value for keypad is FALSE. + keypad enables recognition of a terminal's function keys. If enabled + (bf is TRUE), the input character reading function returns a value + representing the function key, such as KEY_LEFT. (Wide-character API + users: wget_wch(3x) returns KEY_CODE_YES to indicate the availability + of a function key code in its wch parameter.) If disabled (bf is + FALSE), 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), keypad + configures it consistently with the bf parameter. By default, a + window's keypad mode is off.
- Initially, whether the terminal returns 7 or 8 significant bits on in- - put depends on the control mode of the tty driver [see termio(7)]. To - force 8 bits to be returned, invoke meta(win, TRUE); this is equiva- - lent, under POSIX, to setting the CS8 flag on the terminal. To force 7 - bits to be returned, invoke meta(win, FALSE); this is equivalent, under - POSIX, to setting the CS7 flag on the terminal. The window argument, - win, is always ignored. If the terminfo capabilities smm (meta_on) and - rmm (meta_off) are defined for the terminal, smm is sent to the termi- - nal when meta(win, TRUE) is called and rmm is sent when meta(win, - FALSE) is called. + Initially, whether the terminal returns 7- or 8-bit character codes on + input depends on the configuration of the terminal driver; see + termios(3). To force 8 bits to be returned, call meta(..., TRUE); this + is equivalent, on POSIX systems, to setting the CS8 flag on the + terminal. To force 7 bits to be returned, call meta(..., FALSE); this + is equivalent, on POSIX systems, to setting the CS7 flag on the + terminal. The window argument, win, is always ignored. If the term- + info string capabilities meta_on (smm) and meta_off (rmm) are defined + for the terminal type, enabling meta mode sends smm to the terminal and + disabling it sends rmm to the terminal. + + +
+ 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 termios(3). nl configures + the terminal to perform this translation. nonl disables it. In normal + (or "cooked") mode, the terminal driver always translates carriage + returns to line feeds.
- The nodelay option causes getch to be a non-blocking call. If no input - is ready, getch returns ERR. If disabled (bf is FALSE), getch waits - until a key is pressed. - - While interpreting an input escape sequence, wgetch(3x) sets a timer - while waiting for the next character. If notimeout(win, TRUE) is - called, then wgetch 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. - - -
- The raw and noraw routines place the terminal into or out of raw mode. - Raw mode is similar to cbreak mode, in that characters typed are imme- - diately 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 curses. - - -
- When the noqiflush routine is used, normal flush of input and output - queues associated with the INTR, QUIT and SUSP characters will not be - done [see termio(7)]. When qiflush is called, the queues will be - flushed when these control characters are read. You may want to call - noqiflush in a signal handler if you want output to continue as though - the interrupt had not occurred, after the handler exits. - - -
- The timeout and wtimeout routines set blocking or non-blocking read for - a given window. If delay is negative, blocking read is used (i.e., - waits indefinitely for input). If delay is zero, then non-blocking - read is used (i.e., read returns ERR if no input is waiting). If delay - is positive, then read blocks for delay milliseconds, and returns ERR - if there is still no input. Hence, these routines provide the same - functionality as nodelay, plus the additional capability of being able - to block for only delay milliseconds (where delay is positive). + nodelay configures the input character reading function to be non- + blocking for window win. If no input is ready, the reading function + returns ERR. If disabled (bf is FALSE), the reading function does not + return until it has input. + + +
+ When the input character reading function reads an ESC character, it + sets a timer while waiting for the next character. notimeout(win, + 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 wtimeout + below. + + +
+ qiflush and noqiflush configure the terminal driver's treatment of its + input and output queues when it handles the interrupt, suspend, or quit + characters in cbreak and "cooked" modes; on POSIX systems, see + termios(3). The default behavior is inherited from the terminal driver + settings. Calling 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 noqiflush prevents such flushing, but + might frustrate impatient users on slow connections if a curses update + of the screen is in progress when the event occurs; see typeahead below + for a mitigation of this problem. You may want to call noqiflush in a + signal handler if you want output to continue after the handler exits + as though the interrupt had not occurred. + + +
+ raw configures the terminal to read input in raw mode, which is similar + to cbreak mode (see 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 curses does not handle. noraw returns + the terminal to normal ("cooked") mode. + + +
+ wtimeout configures whether a curses input character reading function + called on window win uses blocking or non-blocking reads. If delay is + negative, a blocking read is used, waiting indefinitely for input. If + delay is zero, a non-blocking read is used; an input character reading + function returns ERR if no input is pending. If delay is positive, an + input character reading function blocks for delay milliseconds, and + returns ERR if the delay elapses and there is still no input pending. + timeout calls wtimeout on stdscr.
- The curses library does "line-breakout optimization" by looking for ty- - peahead periodically while updating the screen. If input is found, and - it is coming from a tty, the current update is postponed until re- - fresh(3x) or doupdate is called again. This allows faster response to - commands typed in advance. Normally, the input FILE pointer passed to - newterm, or stdin in the case that initscr was used, will be used to do - this typeahead checking. The typeahead routine specifies that the file - descriptor fd is to be used to check for typeahead instead. If fd is - -1, then no typeahead checking is done. + Normally, a curses library checks the terminal for input while updating + the screen. If any is found, the update is postponed until the next + wrefresh(3x) or doupdate(3x) call, allowing faster response to user key + strokes. The library tests the file descriptor corresponding to the + FILE stream pointer passed to newterm(3x) (or stdin if initscr(3x) was + called), for pending input. typeahead instructs curses to test file + descriptor fd instead. An fd of -1 disables the check.
- All routines that return an integer return ERR upon failure and OK - (SVr4 specifies only "an integer value other than ERR") upon successful - completion, unless otherwise noted in the preceding routine descrip- - tions. + timeout and wtimeout return no value. - 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 initial- - ized. Also, + cbreak, nocbreak, echo, noecho, halfdelay, intrflush, keypad, meta, + nodelay, notimeout, nl, nonl, raw, noraw, and typeahead return OK on + success and ERR on failure. - halfdelay - returns an error if its parameter is outside the range - 1..255. + In ncurses, the functions in the previous paragraph return ERR if + o the terminal is not initialized or -
- These functions are described in the XSI Curses standard, Issue 4. - - 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 - raw call turned it off as a side-effect. For best portability, set - echo or noecho explicitly just after initialization, even if your pro- - gram remains in cooked mode. - - When keypad is first enabled, ncurses loads the key-definitions for the - current terminal description. If the terminal description includes ex- - tended string capabilities, e.g., from using the -x option of tic, then - ncurses also defines keys for the capabilities whose names begin with - "k". The corresponding keycodes are generated and (depending on previ- - ous loads of terminal descriptions) may differ from one execution of a - program to the next. The generated keycodes are recognized by the key- - name function (which will then return a name beginning with "k" denot- - ing the terminfo capability name rather than "K", used for curses key- - names). On the other hand, an application can use define_key to estab- - lish a specific keycode for a given string. This makes it possible for - an application to check for an extended capability's presence with - tigetstr, and reassign the keycode to match its own needs. - - Low-level applications can use tigetstr to obtain the definition of any - particular string capability. Higher-level applications which use the - curses wgetch 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 wgetch 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 ca- - pability's value is the same as a previously-loaded key definition, the - later definition is the one used. + o win is NULL (except for intrflush and meta, which ignore its + value). + + Further, halfdelay returns ERR if delay is outside the range 1..255. + + See section "EXTENSIONS" below for the return values of is_cbreak, + is_echo, is_nl, and is_raw.
- Note that echo, noecho, halfdelay, intrflush, meta, nodelay, notimeout, - noqiflush, qiflush, timeout, and wtimeout may be macros. + echo, noecho, halfdelay, intrflush, meta, nl, nonl, nodelay, notimeout, + noqiflush, qiflush, timeout, and wtimeout may be implemented as macros. + + noraw and nocbreak follow historical practice in that they attempt to + restore normal ("cooked") mode from raw and cbreak modes, respectively. + Mixing raw/noraw calls with cbreak/nocbreak calls leads to terminal + driver control states that are hard to predict or understand; doing so + is not recommended. + + +
+ ncurses provides four "is_" functions corresponding to cbreak, echo, + nl, and raw, permitting their states to be queried by the application. + + Query Set Reset + ------------------------------ + is_cbreak cbreak nocbreak + is_echo echo noecho + is_nl nl nonl + is_raw raw noraw + + In each case, the function returns - The noraw and nocbreak 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. + 1 if the option is set, + + 0 if the option is reset, or + + -1 if the library is not initialized. + + +
+ Applications employing ncurses extensions should condition their use on + the visibility of the NCURSES_VERSION preprocessor macro. + + Except as noted in section "EXTENSIONS" above, X/Open Curses, Issue 4 + describes these functions. It specifies no error conditions for them. + + SVr4 curses describes a successful return value only as "an integer + value other than ERR". + + ncurses follows X/Open Curses and the historical practice of System V + curses, clearing the terminal driver's "echo" flag when initializing + the screen. BSD curses did not, but its raw function turned it off as + a side effect. For best portability, call echo or noecho explicitly + just after initialization, even if your program remains in normal + ("cooked") mode. + + X/Open Curses is ambiguous regarding whether raw should disable the + carriage return and line feed translation feature controlled by nl and + nonl. BSD curses did turn off these translations; System V curses did + not. 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. + + When keypad is first enabled, ncurses loads the key definitions for the + current terminal description. If the terminal description includes + extended string capabilities, for example, by using the -x option of + tic(1), then 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 key codes are + recognized by keyname(3x), which then returns 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 define_key(3x) to + bind a specific key to a string of the programmer's choice. This + feature enables an application to check for its presence with + tigetstr(3x), and reassign the key code to match its own needs. + + Low-level applications can use tigetstr(3x) to obtain the definition of + any string capability. 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 curses implementations + (including ncurses) load key definitions in the order they appear in + the strfnames array of string capability names; see term_variables(3x). + The last capability read using a particular definition determines the + key code to be reported. In 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 + key definition, the later definition is the one used. + + +
+ 4BSD curses (1980) introduced echo, noecho, nl, nonl, raw, and noraw. + + SVr2 (1984) featured a new terminal driver, extending the curses API to + support it with cbreak, nocbreak, intrflush, keypad, meta, nodelay, and + typeahead. + + SVr3 (1987) added halfdelay, notimeout, and wtimeout. qiflush and + noqiflush appeared in SVr3.1 (1987), at which point intrflush became a + wrapper for either of these functions, depending on the value of its + Boolean argument. SVr3.1 also added timeout. + + ncurses 6.5 (2024) introduced is_cbreak, is_echo, is_nl, and is_raw. + + Formerly, ncurses used nl and 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 pcurses source (1986), which + used ioctl(2) calls and the sgttyb structure, to 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, ncurses + 6.2 (2020) amended nl and nonl to eliminate their effect on output.
- curses(3x), curs_getch(3x), curs_initscr(3x), curs_util(3x), de- - fine_key(3x), termio(7) + curses(3x), curs_getch(3x), curs_initscr(3x), curs_util(3x), + define_key(3x), termios(3), term_variables(3x). - curs_inopts(3x) +ncurses 6.5 2024-06-08 curs_inopts(3x)