X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_inopts.3x;h=d346017ba0ea09dba6a0e38648c06578bf23a186;hp=a2b366f317e47a2cd3d769eb795493e9443e8c61;hb=HEAD;hpb=894a177fd5228cdbe790bd1dc9435bd435c29681 diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x index a2b366f3..63db4967 100644 --- a/man/curs_inopts.3x +++ b/man/curs_inopts.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inopts.3x,v 1.55 2023/10/07 21:19:07 tom Exp $ -.TH curs_inopts 3X 2023-10-07 "ncurses 6.4" "Library calls" +.\" $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" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -103,183 +103,252 @@ get and set \fIcurses\fR terminal input options \fBint is_raw(void); .fi .SH DESCRIPTION -The \fIncurses\fP library provides several functions which let an application -change the way input from the terminal is handled. -Some are global, applying to all windows. +.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 needed. +An application must apply these to each window if the same behavior is +desired. .\" -.SS cbreak/nocbreak -Normally, the tty driver buffers typed characters until a newline or carriage +.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 +erase/kill character-processing +(interrupt and flow control characters are unaffected), +making characters typed by the user immediately available to the program. The \fB\%nocbreak\fP routine returns the terminal to normal (cooked) mode. .PP -Initially the terminal may or may not be in \fB\%cbreak\fP mode, as the mode is -inherited; therefore, a program should call \fB\%cbreak\fP or \fB\%nocbreak\fP -explicitly. -Most interactive programs using \fIcurses\fP set the \fB\%cbreak\fP -mode. +Initially the terminal may or may not be in \fB\%cbreak\fP mode, +as the mode is inherited; +therefore, +a program should call \fB\%cbreak\fP or \fB\%nocbreak\fP 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.] +[See \fB\%curs_getch\fP(3X) for a discussion of how these routines +interact with \fBecho\fP and \fB\%noecho\fP.] .\" -.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 tty -driver is always disabled, but initially \fB\%getch\fP is in echo mode, so -characters typed are echoed. +.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, or not to echo at all, so -they disable echoing by calling \fB\%noecho\fP. +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.] .\" .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. -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. +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. +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. .\" .SS intrflush -If the \fB\%intrflush\fP option is enabled (\fIbf\fP is \fBTRUE\fP), and an -interrupt key is pressed on the keyboard (interrupt, break, quit), all output in -the tty driver queue will be flushed, giving the effect of faster response to -the interrupt, but causing \fIcurses\fP to have the wrong idea of what is on -the screen. -Disabling the option (\fIbf\fP is \fBFALSE\fP) prevents the -flush. -The default for the option is inherited from the tty driver settings. -The window argument is ignored. +If the \fB\%intrflush\fP option is enabled +.RI ( 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 +is +.BR FALSE ), +prevents the flush. +The default for the option is inherited from the terminal driver +settings. +The +.I win +argument is ignored. .\" .SS keypad The \fB\%keypad\fP option enables the keypad of the user's terminal. If -enabled (\fIbf\fP is \fBTRUE\fP), 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. +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. If disabled -(\fIbf\fP is \fBFALSE\fP), \fIcurses\fP does not treat function keys -specially and the program has to interpret the escape sequences -itself. -If the keypad in the terminal can be turned on (made to -transmit) and off (made to work locally), turning on this option -causes the terminal keypad to be turned on when \fB\%wgetch\fP(3X) is -called. +(\fIbf\fP is \fBFALSE\fP), +.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. .\" .SS meta -Initially, whether the terminal returns 7 or 8 significant bits on -input depends on the control mode of the tty driver [see \fB\%termios\fP(3)]. -To force 8 bits to be returned, invoke \fBmeta\fP(\fIwin\fP, -\fBTRUE\fP); this is equivalent, under POSIX, to setting the CS8 flag -on the terminal. -To force 7 bits to be returned, invoke -\fBmeta\fP(\fIwin\fP, \fBFALSE\fP); this is equivalent, under POSIX, +Initially, +whether the terminal returns 7 or 8 significant bits on input depends on +the control mode of the terminal driver [see \fI\%termios\fP(3)]. +To force 8 bits to be returned, +invoke +\fBmeta\fP(\fIwin\fP, \fBTRUE\fP); +this is equivalent, +under POSIX, +to setting the CS8 flag on the terminal. +To force 7 bits to be returned, +invoke +\fBmeta\fP(\fIwin\fP, \fBFALSE\fP); +this is equivalent, +under POSIX, to setting the CS7 flag on the terminal. The window argument, -\fIwin\fP, is always ignored. -If the terminfo capabilities \fBsmm\fP -(meta_on) and \fBrmm\fP (meta_off) are defined for the terminal, -\fBsmm\fP is sent to the terminal when \fBmeta\fP(\fIwin\fP, -\fBTRUE\fP) is called and \fBrmm\fP is sent when \fBmeta\fP(\fIwin\fP, -\fBFALSE\fP) is called. +.IR win , +is always ignored. +If the 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. .\" -.SS nl/nonl -The \fBnl\fP and \fBnonl\fP routines control whether the underlying display -device translates the return key into newline on input. +.SS "nl, nonl" +The \fBnl\fP and \fBnonl\fP routines control whether the underlying +display device translates the return key into newline on input. .\" .SS nodelay -The \fB\%nodelay\fP option causes \fB\%getch\fP to be a non-blocking call. -If no input is ready, \fB\%getch\fP returns \fBERR\fP. +The \fB\%nodelay\fP option causes \fB\%getch\fP to be a non-blocking +call. +If no input is ready, +\fB\%getch\fP returns \fBERR\fP. If disabled -(\fIbf\fP is \fBFALSE\fP), \fB\%getch\fP waits until a key is pressed. +.RI ( bf +is +.BR FALSE ), +\fB\%getch\fP waits until a key is pressed. .SS notimeout -When interpreting an escape sequence, \fB\%wgetch\fP(3X) sets a timer +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. -The -purpose of the timeout is to differentiate between sequences received -from a function key and those typed by a user. +If +\fB\%notimeout(\fIwin\fR, \fBTRUE\fP) +is called, +then \fB\%wgetch\fP does not set a timer. +The purpose of the timeout is to distinguish sequences produced by a +function key from those typed by a user. .\" -.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, 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 -\fIcurses\fP. +.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, +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/noqiflush -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)]. +.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. +\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. .\" -.SS timeout/wtimeout +.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, -blocking read is used (i.e., waits indefinitely for -input). -If \fIdelay\fP is zero, then non-blocking read is used -(i.e., read returns \fBERR\fP if no input is waiting). +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). If -\fIdelay\fP is positive, then read blocks for \fIdelay\fP -milliseconds, and returns \fBERR\fP if there is still no input. -Hence, these routines provide the same functionality as \fB\%nodelay\fP, +\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). +\fIdelay\fP milliseconds +(where \fIdelay\fP is positive). .\" .SS typeahead -The \fIcurses\fP library does \*(``line-breakout optimization\*('' -by looking for typeahead periodically while updating the screen. -If input is found, and it is coming from a tty, +.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 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. +Normally, +the input +.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. +\-1, +then no typeahead checking is done. .\" .SH RETURN VALUE -All routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +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. .PP -X/Open does not define any error conditions. +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. +Any function will also return an error if the terminal was not +initialized. Also, .RS 3 .TP 5 @@ -287,13 +356,40 @@ Also, returns an error if its parameter is outside the range 1..255. .RE +.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, +and +\fB\%wtimeout\fP +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; +doing so is not recommended. .SH EXTENSIONS -This implementation provides four functions which may be used to detect -if the corresponding flags were set or reset: +.I \%ncurses +provides four \*(``is_\*('' functions that may be used to detect if the +corresponding flags were set or reset. .PP .TS -l l l. -\fBQuery\fP \fBSet\fP \fBReset\fP +center; +Lb Lb Lb +L L L . +Query Set Reset _ is_cbreak cbreak nocbreak is_echo echo noecho @@ -301,55 +397,95 @@ is_nl nl nonl is_raw raw noraw .TE .PP -In each case, the function returns -.TP 5 +In each case, +the function returns +.TP 4 \" "-1" + 2n 1 if the flag is set, -.TP 5 +.TP 0 -if the flag is reset, or -.TP 5 +if the flag is reset, +or +.TP \-1 -if the \fIcurses\fP library was not initialized. +if the library is not initialized. .PP -These routines are specific to \fIncurses\fP. -They were not supported on Version 7, BSD or System V implementations. -It is recommended that any code depending on \fIncurses\fP extensions -be conditioned using NCURSES_VERSION. +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. .SH PORTABILITY -Except as noted in the section on extensions, -these functions are described in the XSI Curses standard, Issue 4. +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. .PP -The \fIncurses\fP library obeys the XPG4 standard and the historical practice of the -AT&T \fIcurses\fP implementations, in that the echo bit is cleared when \fIcurses\fP +Except as noted in section \*(``EXTENSIONS\*('' above, +X/Open Curses, Issue 4, Version 2 describes these functions. +.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. -BSD \fIcurses\fP differed from this slightly; it -left the echo bit on at initialization, but the BSD \fBraw\fP call turned it -off as a side-effect. -For best portability, set \fBecho \fPor \fB\%noecho\fP explicitly -just after initialization, even if your program remains in cooked mode. +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. +For best portability, +set \fBecho\fP or \fB\%noecho\fP explicitly just after initialization, +even if your program remains in cooked mode. .PP -The XSI Curses standard is ambiguous on the question of whether \fBraw\fP -should disable the CRLF translations controlled by \fBnl\fP and \fBnonl\fP. -BSD \fIcurses\fP did turn off these translations; AT&T \fIcurses\fP (at least as late as -SVr1) did not. -We chose to do so, on the theory that a programmer requesting -raw input wants a clean (ideally 8-bit clean) connection that the operating -system will not alter. +X/Open Curses is ambiguous regarding whether \fBraw\fP should disable +the CR/LF translations controlled by \fBnl\fP and \fBnonl\fP. +BSD +.I curses +did turn off these translations; +AT&T +.I curses +(at least as late as SVr1) +did not. +.I \%ncurses +does so, +on the assumption that a programmer requesting raw input wants a clean +(ideally, +8-bit clean) +connection that the operating system will not alter. .PP When \fB\%keypad\fP is first enabled, -\fIncurses\fP loads the key-definitions for the current terminal description. +.I \%ncurses +loads the key definitions for the current terminal description. If the terminal description includes extended string capabilities, -e.g., from using the \fB\-x\fP option of \fB@TIC@\fP, -then \fIncurses\fP also defines keys for the capabilities whose names -begin with \*(``k\*(''. -The corresponding keycodes are generated and (depending on previous -loads of terminal descriptions) may differ from one execution of a -program to the next. -The generated keycodes are recognized by the \fB\%keyname\fP function +e.g., +from using the +.B \-x +option of \fB\%@TIC@\fP, +then +.I \%ncurses +also defines keys for the capabilities whose names begin with +\*(``k\*(''. +The corresponding keycodes are generated and +(depending on previous loads of terminal descriptions) +may differ from one execution of a program to the next. +The generated keycodes are recognized by the \fB\%keyname\fP(3X) +function (which will then return a name beginning with \*(``k\*('' denoting the -terminfo capability name rather than \*(``K\*('', used for \fIcurses\fP key-names). -On the other hand, an application can use \fB\%define_key\fP to establish +terminfo capability name rather than \*(``K\*('', +used for +.I curses +key names). +On the other hand, +an application can use \fB\%define_key\fP(3X) to 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, @@ -357,42 +493,58 @@ and reassign the keycode 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 \fIcurses\fP \fB\%wgetch\fP -and similar functions to return keycodes rely upon the order in which -the strings are loaded. +Higher-level applications which use the +.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. -Most \fIcurses\fP implementations (including \fIncurses\fP) +Most +.I curses +implementations +(including +.IR \%ncurses ) load key definitions in the order defined by the array of string capability names. The last key to be loaded determines the keycode which will be returned. -In \fIncurses\fP, you may also have extended capabilities interpreted as -key definitions. +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. -.SH NOTES -Note that -\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, and -\fB\%wtimeout\fP may be macros. -.PP -The \fB\%noraw\fP and \fB\%nocbreak\fP calls follow historical practice in that -they attempt to restore to normal (\*(``cooked\*('') mode -from raw and cbreak modes respectively. -Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver -control states that are hard to predict or understand; it is not recommended. +.SH HISTORY +Formerly, +.I \%ncurses +used +.B \%nl +and +.B \%nonl +to control the conversion of newlines to carriage return/line feed +on output as well as input. +X/Open Curses documents the use of these functions only for input. +This difference arose from converting the +.I \%pcurses +source (1986), +which used +\fI\%ioctl\fP(2) calls and the +.I \%sgttyb +structure, +to +.I \%termios +(the POSIX terminal API). +In the former, +both input and output were controlled via a single option +.BR \%CRMOD , +while the latter separates these features. +Because that conversion interferes with output optimization, +.I \%ncurses +6.2 (2020) amended +.B \%nl +and +.B \%nonl +to eliminate their effect on output. .SH SEE ALSO \fB\%curses\fP(3X), \fB\%curs_getch\fP(3X),