X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fhtml%2Fman%2Fcurs_inopts.3x.html;h=4bee87ac6af6a337478dc9904cb964962be50c9f;hb=HEAD;hp=d2d5b6b03f250e1dfd0cc6763301108f021c7ded;hpb=c6cfd97b8beaf0f6deafbf8aac7281cf6aa7f012;p=ncurses.git diff --git a/doc/html/man/curs_inopts.3x.html b/doc/html/man/curs_inopts.3x.html index d2d5b6b0..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 --
+
#include <curses.h> 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 raw(void); - int noraw(void); - void noqiflush(void); + + 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); - int notimeout(WINDOW *win, bool bf); - void timeout(int delay); - void wtimeout(WINDOW *win, int delay); - int typeahead(int fd); + void noqiflush(void); + int raw(void); + int noraw(void); --
- 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-process- - ing (interrupt and flow control characters are unaffect- - ed), 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 explicitly. Most interactive programs - using curses set the cbreak mode. Note that cbreak over- - rides 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 as they are typed. - Echoing by the tty driver is always disabled, but initial- - ly getch 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 noecho. - [See curs_getch(3x) for a discussion of how these routines - 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 available to the program. However, - after blocking for tenths tenths of seconds, ERR is re- - turned if nothing has been typed. The value of tenths - must be a number between 1 and 255. Use nocbreak to leave + 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); + + +
+ 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. + + +
+ 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), 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 in- - terrupt, but causing curses to have the wrong idea of what - is on the screen. Disabling (bf is FALSE), the option - prevents the flush. The default for the option is inher- - ited from the tty driver settings. The window argument is - ignored. - - The keypad option enables the keypad of the user's termi- - nal. If enabled (bf is TRUE), the user can press a func- - tion key (such as an arrow key) and wgetch returns a sin- - gle 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 - sequences itself. If the keypad in the terminal can be - turned on (made to transmit) and off (made to work local- - ly), turning on this option causes the terminal keypad to - be turned on when wgetch is called. The default value for - keypad is false. - - Initially, whether the terminal returns 7 or 8 significant - bits on input depends on the control mode of the tty driv- - er [see termio(7)]. To force 8 bits to be returned, in- - voke meta(win, TRUE); this is equivalent, 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 terminal when - meta(win, TRUE) is called and rmm is sent when meta(win, - FALSE) is called. - - 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 sets a - timer while waiting for the next character. If notime- - out(win, TRUE) is called, then wgetch does not set a - timer. The purpose of the timeout is to differentiate be- - tween 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 immediately passed through to the us- - er program. The differences are that in raw mode, the in- - terrupt, 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 in- - put). 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 rou- - tines provide the same functionality as nodelay, plus the - additional capability of being able to block for only de- - lay milliseconds (where delay is positive). - - The curses 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 refresh 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. +
+ intrflush calls qiflush (see below) if bf is TRUE, and noqiflush if bf + is FALSE. It ignores its win argument. + + +
+ 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-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. + + +
+ 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. --
- All routines that return an integer return ERR upon fail- - ure and OK (SVr4 specifies only "an integer value other - than ERR") upon successful completion, unless otherwise - noted in the preceding routine descriptions. - X/Open does not define any error conditions. In this im- - plementation, functions with a window parameter will re- - turn an error if it is null. Any function will also re- - turn an error if the terminal was not initialized. Also, +
+ 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. - halfdelay - returns an error if its parameter is outside - the range 1..255. +
+ 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. + + +
+ 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. + + +
+ timeout and wtimeout return no value. + + cbreak, nocbreak, echo, noecho, halfdelay, intrflush, keypad, meta, + nodelay, notimeout, nl, nonl, raw, noraw, and typeahead return OK on + success and ERR on failure. + + In ncurses, the functions in the previous paragraph return ERR if + + o the terminal is not initialized or + + 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. + + +
+ 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 + + 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. --
- These functions are described in the XSI Curses standard, - Issue 4. - - The ncurses library obeys the XPG4 standard and the his- - torical 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 portabili- - ty, set echo or noecho explicitly just after initializa- - tion, even if your program remains in cooked mode. - - When keypad is first enabled, ncurses loads the key-defi- - nitions for the current terminal description. If the ter- - minal description includes extended 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 (de- - pending on previous loads of terminal descriptions) may - differ from one execution of a program to the next. The - generated keycodes are recognized by the keyname 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 define_key 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 tigetstr, - and reassign the keycode to match its own needs. - - Low-level applications can use tigetstr to obtain the def- - inition of any particular string capability. Higher-level - applications which use the curses wgetch and similar func- - tions 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 deter- - mines the keycode which will be returned. In ncurses, you - may also have extended capabilities interpreted as key - definitions. These are loaded after the predefined keys, - and if a capability's value is the same as a previously- - loaded key definition, the later definition is the one - used. + 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. --
- Note that echo, noecho, halfdelay, intrflush, meta, node- - lay, notimeout, noqiflush, qiflush, timeout, and wtimeout - may be macros. + 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. - 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. +
+ 4BSD curses (1980) introduced echo, noecho, nl, nonl, raw, and noraw. --
- curses(3x), curs_getch(3x), curs_initscr(3x), - curs_util(3x), define_key(3x), termio(7) + 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. - curs_inopts(3x) + 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), + define_key(3x), termios(3), term_variables(3x). + + + +ncurses 6.5 2024-06-08 curs_inopts(3x)