diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/inopts.3ncurses')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/inopts.3ncurses | 523 |
1 files changed, 523 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/inopts.3ncurses b/upstream/opensuse-tumbleweed/man3/inopts.3ncurses new file mode 100644 index 00000000..f4c5ac83 --- /dev/null +++ b/upstream/opensuse-tumbleweed/man3/inopts.3ncurses @@ -0,0 +1,523 @@ +'\" t +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_inopts.3x,v 1.60 2023/12/23 16:36:18 tom Exp $ +.TH inopts 3NCURSES 2023-12-23 "ncurses 6.4" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +.SH NAME +\fB\%cbreak\fP, +\fB\%echo\fP, +\fB\%halfdelay\fP, +\fB\%intrflush\fP, +\fB\%is_cbreak\fP, +\fB\%is_echo\fP, +\fB\%is_nl\fP, +\fB\%is_raw\fP, +\fB\%keypad\fP, +\fB\%meta\fP, +\fB\%nl\fP, +\fB\%nocbreak\fP, +\fB\%nodelay\fP, +\fB\%noecho\fP, +\fB\%nonl\fP, +\fB\%noqiflush\fP, +\fB\%noraw\fP, +\fB\%notimeout\fP, +\fB\%qiflush\fP, +\fB\%raw\fP, +\fB\%timeout\fP, +\fB\%wtimeout\fP, +\fB\%typeahead\fP \- +get and set \fIcurses\fR terminal input options +.SH SYNOPSIS +.nf +\fB#include <ncursesw/curses.h> +.PP +\fBint cbreak(void); +\fBint nocbreak(void); +.PP +\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); +.PP +\fBint nl(void); +\fBint nonl(void); +.PP +\fBint raw(void); +\fBint noraw(void); +.PP +\fBvoid qiflush(void); +\fBvoid noqiflush(void); +.PP +\fBint halfdelay(int \fItenths\fP); +\fBvoid timeout(int \fIdelay\fP); +\fBvoid wtimeout(WINDOW *\fIwin\fP, int \fIdelay\fP); +.PP +\fBint typeahead(int \fIfd\fP); +.PP +\fI/* extensions */ +\fBint is_cbreak(void); +\fBint is_echo(void); +\fBint is_nl(void); +\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. +.\" +.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 +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 +.I curses +set the \fB\%cbreak\fP mode. +Note that \fB\%cbreak\fP overrides \fBraw\fP. +[See \fB\%getch\fP(3NCURSES) 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(3NCURSES) 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. +[See \fB\%getch\fP(3NCURSES) 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. +.\" +.SS intrflush +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 +.RI ( bf +is +.BR TRUE ), +the user can press a function key +(such as an arrow key) +and \fB\%wgetch\fP(3NCURSES) returns a single value representing the function +key, +as in \fB\%KEY_LEFT\fP. +If disabled +(\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(3NCURSES) 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 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, +.I 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 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. +If disabled +.RI ( bf +is +.BR FALSE ), +\fB\%getch\fP waits until a key is pressed. +.SS notimeout +When interpreting an escape sequence, +\fB\%wgetch\fP(3NCURSES) 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 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 terminal +driver that are not set by +.I 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. +.\" +.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). +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). +.\" +.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(3NCURSES) or \fB\%doupdate\fP is called again. +This allows faster response to commands typed in advance. +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. +.\" +.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. +.PP +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 +initialized. +Also, +.RS 3 +.TP 5 +\fB\%halfdelay\fP +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 +.I \%ncurses +provides four \*(``is_\*('' functions that may be used to detect if the +corresponding flags were set or reset. +.PP +.TS +center; +Lb Lb Lb +L L L . +Query Set Reset +_ +is_cbreak cbreak nocbreak +is_echo echo noecho +is_nl nl nonl +is_raw raw noraw +.TE +.PP +In each case, +the function returns +.TP 4 \" "-1" + 2n +1 +if the flag is set, +.TP +0 +if the flag is reset, +or +.TP +\-1 +if the library is not initialized. +.PP +They were designed for +\fB\%ncurses\fP(3NCURSES), +and are not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous +.I curses +implementation. +.SH PORTABILITY +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. +.PP +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 +.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 +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, +.I \%ncurses +loads the key definitions for the current terminal description. +If the terminal description includes extended string capabilities, +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(3NCURSES) +function +(which will then return a name beginning with \*(``k\*('' denoting the +terminfo capability name rather than \*(``K\*('', +used for +.I curses +key names). +On the other hand, +an application can use \fB\%define_key\fP(3NCURSES) 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. +.PP +Low-level applications can use \fB\%tigetstr\fP to obtain the definition +of any particular string capability. +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 +.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 +.I \%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 SEE ALSO +\fB\%ncurses\fP(3NCURSES), +\fB\%getch\fP(3NCURSES), +\fB\%initscr\fP(3NCURSES), +\fB\%util\fP(3NCURSES), +\fB\%define_key\fP(3NCURSES), +\fB\%termios\fP(3) |