captoinfo 1m 2023-12-16 ncurses 6.4 User commands

SYNOPSIS
DESCRIPTION
-
Translations from nonstandard capabilities
+
Translations from Nonstandard Capabilities

FILES
diff --git a/doc/html/man/curs_add_wch.3x.html b/doc/html/man/curs_add_wch.3x.html index e92b695a..e9ed953d 100644 --- a/doc/html/man/curs_add_wch.3x.html +++ b/doc/html/man/curs_add_wch.3x.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_add_wch.3x,v 1.49 2023/12/16 21:19:37 tom Exp @ + * @Id: curs_add_wch.3x,v 1.50 2023/12/23 16:08:25 tom Exp @ --> -curs_add_wch 3x 2023-12-16 ncurses 6.4 Library calls +curs_add_wch 3x 2023-12-23 ncurses 6.4 Library calls -
curs_add_wch 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_add_wch 3x 2023-12-23 ncurses 6.4 Library calls

curs_add_wch(3x) Library calls curs_add_wch(3x) @@ -320,7 +320,7 @@ -ncurses 6.4 2023-12-16 curs_add_wch(3x) +ncurses 6.4 2023-12-23 curs_add_wch(3x)

diff --git a/doc/html/man/curs_addch.3x.html b/doc/html/man/curs_addch.3x.html index 976fc3e4..0eeb8b94 100644 --- a/doc/html/man/curs_addch.3x.html +++ b/doc/html/man/curs_addch.3x.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_addch.3x,v 1.75 2023/12/16 21:19:37 tom Exp @ + * @Id: curs_addch.3x,v 1.76 2023/12/23 16:27:51 tom Exp @ --> -curs_addch 3x 2023-12-16 ncurses 6.4 Library calls +curs_addch 3x 2023-12-23 ncurses 6.4 Library calls -
curs_addch 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_addch 3x 2023-12-23 ncurses 6.4 Library calls

curs_addch(3x) Library calls curs_addch(3x) @@ -66,11 +66,11 @@
DESCRIPTION
-
Adding characters
+
Adding Characters
The addch, waddch, mvaddch and mvwaddch routines put the character ch into the given window at its current window position, which is then - advanced. They are analogous to putchar(3) in stdio(3). If the - advance is at the right margin: + advanced. They are analogous to the standard C library's putchar(3). + If the advance is at the right margin: o The cursor automatically wraps to the beginning of the next line. @@ -119,7 +119,7 @@ OR'ed into characters. -
Echoing characters
+
Echoing Characters
The echochar and wechochar routines are equivalent to a call to addch followed by a call to refresh(3x), or a call to waddch followed by a call to wrefresh. The knowledge that only a single character is being @@ -308,7 +308,7 @@ -ncurses 6.4 2023-12-16 curs_addch(3x) +ncurses 6.4 2023-12-23 curs_addch(3x)

@@ -316,8 +316,8 @@ ncurses 6.4 2023-12-16 SYNOPSIS
DESCRIPTION
-
Adding characters
-
Echoing characters
+
Adding Characters
+
Echoing Characters

Line Graphics

diff --git a/doc/html/man/curs_attr.3x.html b/doc/html/man/curs_attr.3x.html index 56fdf667..e813235c 100644 --- a/doc/html/man/curs_attr.3x.html +++ b/doc/html/man/curs_attr.3x.html @@ -28,7 +28,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_attr.3x,v 1.92 2023/12/16 21:07:24 tom Exp @ + * @Id: curs_attr.3x,v 1.93 2023/12/23 16:08:25 tom Exp @ * --------------------------------------------------------------------------- * --------------------------------------------------------------------------- * --------------------------------------------------------------------------- @@ -50,12 +50,12 @@ -curs_attr 3x 2023-12-16 ncurses 6.4 Library calls +curs_attr 3x 2023-12-23 ncurses 6.4 Library calls -
curs_attr 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_attr 3x 2023-12-23 ncurses 6.4 Library calls

curs_attr(3x) Library calls curs_attr(3x) @@ -121,7 +121,7 @@ attributes used for erasing and clearing. -
Window attributes
+
Window Attributes
There are two sets of functions: o functions for manipulating the window attributes and color: @@ -141,7 +141,7 @@ together in attr, without affecting other attributes. -
Legacy window attributes
+
Legacy Window Attributes
The X/Open window attribute routines which set or get, turn on or off are extensions of older routines which assume that color pairs are OR'd into the attribute parameter. These newer routines use similar names, @@ -182,7 +182,7 @@ although ncurses provides getattrs (see curs_legacy(3x)). -
Change character rendition
+
Change Character Rendition
The routine chgat changes the attributes of a given number of characters starting at the current cursor location of stdscr. It does not update the cursor and does not perform wrapping. A character count @@ -195,7 +195,7 @@ in the first argument of init_pair, see curs_color(3x)). -
Change window color
+
Change Window Color
The routine color_set sets the current color of the given window to the foreground/background combination described by the color pair parameter. @@ -511,7 +511,7 @@ -ncurses 6.4 2023-12-16 curs_attr(3x) +ncurses 6.4 2023-12-23 curs_attr(3x)

@@ -519,10 +519,10 @@ ncurses 6.4 2023-12-16 SYNOPSIS
DESCRIPTION
-
Window attributes
-
Legacy window attributes
-
Change character rendition
-
Change window color
+
Window Attributes
+
Legacy Window Attributes
+
Change Character Rendition
+
Change Window Color

Standout

Video Attributes

diff --git a/doc/html/man/curs_bkgd.3x.html b/doc/html/man/curs_bkgd.3x.html index 7642671f..078fd793 100644 --- a/doc/html/man/curs_bkgd.3x.html +++ b/doc/html/man/curs_bkgd.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_bkgd.3x,v 1.54 2023/12/17 23:31:28 tom Exp @ + * @Id: curs_bkgd.3x,v 1.55 2023/12/23 16:35:10 tom Exp @ --> -curs_bkgd 3x 2023-12-17 ncurses 6.4 Library calls +curs_bkgd 3x 2023-12-23 ncurses 6.4 Library calls -
curs_bkgd 3x 2023-12-17 ncurses 6.4 Library calls
+
curs_bkgd 3x 2023-12-23 ncurses 6.4 Library calls

curs_bkgd(3x) Library calls curs_bkgd(3x) @@ -155,7 +155,7 @@ Unusually, there is no wgetbkgd function; getbkgd behaves as one would expect wgetbkgd to, accepting a WINDOW pointer argument. - bkgd and bkgdset may be available as macros. + bkgd and bkgdset may be implemented as macros. X/Open Curses mentions that the character part of the background must be a single-byte value. ncurses, like SVr4 curses, checks to ensure @@ -189,7 +189,7 @@ -ncurses 6.4 2023-12-17 curs_bkgd(3x) +ncurses 6.4 2023-12-23 curs_bkgd(3x)

diff --git a/doc/html/man/curs_bkgrnd.3x.html b/doc/html/man/curs_bkgrnd.3x.html index 604fe92d..8dcd4c41 100644 --- a/doc/html/man/curs_bkgrnd.3x.html +++ b/doc/html/man/curs_bkgrnd.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_bkgrnd.3x,v 1.35 2023/12/16 23:00:21 tom Exp @ + * @Id: curs_bkgrnd.3x,v 1.36 2023/12/23 16:35:10 tom Exp @ --> -curs_bkgrnd 3x 2023-12-16 ncurses 6.4 Library calls +curs_bkgrnd 3x 2023-12-23 ncurses 6.4 Library calls -
curs_bkgrnd 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_bkgrnd 3x 2023-12-23 ncurses 6.4 Library calls

curs_bkgrnd(3x) Library calls curs_bkgrnd(3x) @@ -154,7 +154,7 @@
NOTES
- bkgrnd, bkgrndset, and getbkgrnd may be available as macros. + bkgrnd, bkgrndset, and getbkgrnd may be implemented as macros. Unlike their counterparts in the non-"wide" configuration of ncurses, getbkgrnd and wgetbkgrnd supply the background character and attribute @@ -177,7 +177,7 @@ -ncurses 6.4 2023-12-16 curs_bkgrnd(3x) +ncurses 6.4 2023-12-23 curs_bkgrnd(3x)

diff --git a/doc/html/man/curs_color.3x.html b/doc/html/man/curs_color.3x.html index df4b22c7..964ef4e0 100644 --- a/doc/html/man/curs_color.3x.html +++ b/doc/html/man/curs_color.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_color.3x,v 1.93 2023/12/16 21:07:24 tom Exp @ + * @Id: curs_color.3x,v 1.95 2023/12/23 20:18:13 tom Exp @ --> -curs_color 3x 2023-12-16 ncurses 6.4 Library calls +curs_color 3x 2023-12-23 ncurses 6.4 Library calls -
curs_color 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_color 3x 2023-12-23 ncurses 6.4 Library calls

curs_color(3x) Library calls curs_color(3x) @@ -58,6 +58,10 @@
SYNOPSIS
#include <curses.h> + /* variables */ + int COLOR_PAIRS; + int COLORS; + int start_color(void); bool has_colors(void); @@ -85,44 +89,43 @@
DESCRIPTION

Overview
- curses supports color attributes on terminals with that capability. To - use these routines start_color must be called, usually right after - initscr. Colors are always used in pairs (referred to as color pairs). - A color pair consists of a foreground color (for characters) and a - background color (for the blank field on which the characters are - displayed). A programmer initializes a color pair with the routine - init_pair. After it has been initialized, COLOR_PAIR(n) can be used to - convert the pair to a video attribute. - - If a terminal is capable of redefining colors, the programmer can use - the routine init_color to change the definition of a color. The - routines has_colors and can_change_color return TRUE or FALSE, - depending on whether the terminal has color capabilities and whether - the programmer can change the colors. The routine color_content allows - a programmer to extract the amounts of red, green, and blue components - in an initialized color. The routine pair_content allows a programmer - to find out how a given color pair is currently defined. + curses supports color attributes on terminals with that capability. + Call start_color (typically right after initscr(3x)) to enable this + feature. Colors are always used in pairs. A color pair couples a + foreground color for characters with a background color for the blank + field on which characters are rendered. init_pair initializes a color + pair. The macro COLOR_PAIR(n) can then convert the pair to a video + attribute. + + If a terminal has the relevant capability, init_color permits + (re)definition of a color. has_colors and can_change_color return TRUE + or FALSE, depending on whether the terminal has color capability and + whether the programmer can change the colors. color_content permits + extraction of the red, green, and blue components of an initialized + color. pair_content permits discovery of a color pair's current + definition. -
Color Rendering
- The curses library combines these inputs to produce the actual - foreground and background colors shown on the screen: +
Rendering
+ curses combines the following data to render a character cell. Any of + them can include color information. - o per-character video attributes (e.g., via waddch), + o curses character attributes, as from waddch(3x) or wadd_wch(3x) - o the window attribute (e.g., by wattrset), and + o window attributes, as from wattrset(3x) or wattr_set(3x) - o the background character (e.g., wbkgdset). + o window background character atttributes, as from wbkgdset(3x) or + wbkgrndset(3x) - Per-character and window attributes are usually set by a parameter - containing video attributes including a color pair value. Some - functions such as wattr_set use a separate parameter which is the color - pair number. + Per-character and window attributes are usually set through a function + parameter containing attributes including a color pair value. Some + functions, such as wattr_set, use a separate color pair number + parameter. - The background character is a special case: it includes a character - value, just as if it were passed to waddch. + The background character is a special case: it includes a character + code, just as if it were passed to waddch. - The curses library does the actual work of combining these color pairs + The curses library does the actual work of combining these color pairs in an internal function called from waddch: o If the parameter passed to waddch is blank, and it uses the special @@ -130,18 +133,18 @@ o curses next checks the window attribute. - o If the window attribute does not use color pair 0, curses uses + o If the window attribute does not use color pair 0, curses uses the color pair from the window attribute. o Otherwise, curses uses the background character. - o If the parameter passed to waddch is not blank, or it does not use - the special color pair 0, curses prefers the color pair from the - parameter, if it is nonzero. Otherwise, it tries the window + o If the parameter passed to waddch is not blank, or it does not use + the special color pair 0, curses prefers the color pair from the + parameter, if it is nonzero. Otherwise, it tries the window attribute next, and finally the background character. - Some curses functions such as wprintw call waddch. Those do not - combine its parameter with a color pair. Consequently those calls use + Some curses functions such as wprintw call waddch. Those do not + combine its parameter with a color pair. Consequently those calls use only the window attribute or the background character. @@ -159,20 +162,27 @@ COLOR_CYAN COLOR_WHITE - Some terminals support more than the eight (8) "ANSI" colors. There + Some terminals support more than the eight (8) "ANSI" colors. There are no standard names for those additional colors.
VARIABLES

COLORS
- is initialized by start_color to the maximum number of colors the + is initialized by start_color to the maximum number of colors the terminal can support.
COLOR_PAIRS
- is initialized by start_color to the maximum number of color pairs the - terminal can support. + is initialized by start_color to the maximum number of color pairs the + terminal can support. Often, its value is the product COLORS x COLORS, + but this is not always true. + + o A few terminals use the HLS color space (see start_color below), + ignoring this rule; and + + o terminals supporting a large number of colors are limited to the + number of color pairs that a signed short value can represent.
FUNCTIONS
@@ -445,32 +455,35 @@
EXTENSIONS
The functions marked as extensions were designed for ncurses(3x), and - are not found in SVr4 curses, 4.4BSD curses, or any other previous - version of curses. + are not found in SVr4 curses, 4.4BSD curses, or any other previous + curses implementation.
PORTABILITY
- This implementation satisfies XSI Curses's minimum maximums for COLORS + Applications employing ncurses extensions should condition their use on + the visibility of the NCURSES_VERSION preprocessor macro. + + This implementation satisfies XSI Curses's minimum maximums for COLORS and COLOR_PAIRS. The init_pair routine accepts negative values of foreground and - background color to support the use_default_colors(3x) extension, but + background color to support the use_default_colors(3x) extension, but only if that routine has been first invoked. The assumption that COLOR_BLACK is the default background color for all - terminals can be modified using the assume_default_colors(3x) + terminals can be modified using the assume_default_colors(3x) extension. - This implementation checks the pointers, e.g., for the values returned - by color_content and pair_content, and will treat those as optional + This implementation checks the pointers, e.g., for the values returned + by color_content and pair_content, and will treat those as optional parameters when null. - X/Open Curses does not specify a limit for the number of colors and + X/Open Curses does not specify a limit for the number of colors and color pairs which a terminal can support. However, in its use of short - for the parameters, it carries over SVr4's implementation detail for + for the parameters, it carries over SVr4's implementation detail for the compiled terminfo database, which uses signed 16-bit numbers. This - implementation provides extended versions of those functions which use - short parameters, allowing applications to use larger color- and pair- + implementation provides extended versions of those functions which use + short parameters, allowing applications to use larger color- and pair- numbers. The reset_color_pairs function is an extension of ncurses. @@ -479,13 +492,13 @@
HISTORY
SVr3.2 introduced color support to curses in 1987. - SVr4 made internal changes, e.g., moving the storage for the color - state from SP (the SCREEN structure) to cur_term (the TERMINAL + SVr4 made internal changes, e.g., moving the storage for the color + state from SP (the SCREEN structure) to cur_term (the TERMINAL structure), but provided the same set of library functions. - SVr4 curses limits the number of color pairs to 64, reserving color - pair zero (0) as the terminal's initial uncolored state. This limit - arises because the color pair information is a bitfield in the chtype + SVr4 curses limits the number of color pairs to 64, reserving color + pair zero (0) as the terminal's initial uncolored state. This limit + arises because the color pair information is a bitfield in the chtype data type (denoted by A_COLOR). Other implementations of curses had different limits: @@ -498,35 +511,35 @@ o X/Open Curses (1992-present) added a new structure cchar_t to store the character, attributes and color pair values, allowing increased - range of color pairs. Both color pairs and color-values used a + range of color pairs. Both color pairs and color-values used a signed short, limiting values to 15 bits. - o ncurses (1992-present) uses eight bits for A_COLOR in chtype + o ncurses (1992-present) uses eight bits for A_COLOR in chtype values. - Version 5.3 provided a wide-character interface (2002), but left + Version 5.3 provided a wide-character interface (2002), but left color pairs as part of the attributes-field. Since version 6 (2015), ncurses uses a separate int for color pairs in the cchar_t values. When those color pair values fit in 8 bits, - ncurses allows color pairs to be manipulated via the functions + ncurses allows color pairs to be manipulated via the functions using chtype values. - o NetBSD curses used 6 bits from 2000 (when colors were first - supported) until 2004. At that point, NetBSD changed to use 10 - bits. As of 2021, that size is unchanged. Like ncurses before - version 6, the NetBSD color pair information is stored in the - attributes field of cchar_t, limiting the number of color pairs by + o NetBSD curses used 6 bits from 2000 (when colors were first + supported) until 2004. At that point, NetBSD changed to use 10 + bits. As of 2021, that size is unchanged. Like ncurses before + version 6, the NetBSD color pair information is stored in the + attributes field of cchar_t, limiting the number of color pairs by the size of the bitfield.
SEE ALSO
- curses(3x), curs_attr(3x), curs_initscr(3x), curs_variables(3x), + curses(3x), curs_attr(3x), curs_initscr(3x), curs_variables(3x), default_colors(3x) -ncurses 6.4 2023-12-16 curs_color(3x) +ncurses 6.4 2023-12-23 curs_color(3x)

@@ -535,7 +548,7 @@ ncurses 6.4 2023-12-16 DESCRIPTION

Overview
-
Color Rendering
+
Rendering

CONSTANTS
diff --git a/doc/html/man/curs_extend.3x.html b/doc/html/man/curs_extend.3x.html index 8dc4cf75..32b507a3 100644 --- a/doc/html/man/curs_extend.3x.html +++ b/doc/html/man/curs_extend.3x.html @@ -28,19 +28,19 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey 1999-on - * @Id: curs_extend.3x,v 1.43 2023/12/16 20:32:22 tom Exp @ + * @Id: curs_extend.3x,v 1.44 2023/12/23 16:36:18 tom Exp @ --> -curs_extend 3x 2023-12-16 ncurses 6.4 Library calls +curs_extend 3x 2023-12-23 ncurses 6.4 Library calls -
curs_extend 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_extend 3x 2023-12-23 ncurses 6.4 Library calls

curs_extend(3x) Library calls curs_extend(3x) @@ -88,10 +88,14 @@ this and restore it. +
EXTENSIONS
+ These functions are ncurses(3x) extensions, and are not found in SVr4 + curses, 4.4BSD curses, or any other previous curses implementation. + +
PORTABILITY
- These routines are specific to ncurses. They were not supported on - Version 7, BSD or System V implementations. It is recommended that any - code depending on them be conditioned using NCURSES_VERSION. + Applications employing ncurses extensions should condition their use on + the visibility of the NCURSES_VERSION preprocessor macro.
AUTHORS
@@ -105,7 +109,7 @@ -ncurses 6.4 2023-12-16 curs_extend(3x) +ncurses 6.4 2023-12-23 curs_extend(3x)

@@ -118,6 +122,7 @@ ncurses 6.4 2023-12-16 RETURN VALUE +
EXTENSIONS

PORTABILITY

AUTHORS

SEE ALSO
diff --git a/doc/html/man/curs_get_wch.3x.html b/doc/html/man/curs_get_wch.3x.html index 38e0e209..c639d28a 100644 --- a/doc/html/man/curs_get_wch.3x.html +++ b/doc/html/man/curs_get_wch.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_get_wch.3x,v 1.30 2023/11/25 13:58:47 tom Exp @ + * @Id: curs_get_wch.3x,v 1.31 2023/12/23 16:35:10 tom Exp @ --> -curs_get_wch 3x 2023-11-25 ncurses 6.4 Library calls +curs_get_wch 3x 2023-12-23 ncurses 6.4 Library calls -
curs_get_wch 3x 2023-11-25 ncurses 6.4 Library calls
+
curs_get_wch 3x 2023-12-23 ncurses 6.4 Library calls

curs_get_wch(3x) Library calls curs_get_wch(3x) @@ -141,8 +141,8 @@ on the state of the tty driver when each character is typed, the program may produce undesirable results. - All of these symbols except wget_wch and unget_wch may be available as - macros. + All of these functions except wget_wch and unget_wch may be implemented + as macros.
PORTABILITY
@@ -155,7 +155,7 @@ -ncurses 6.4 2023-11-25 curs_get_wch(3x) +ncurses 6.4 2023-12-23 curs_get_wch(3x)

diff --git a/doc/html/man/curs_getch.3x.html b/doc/html/man/curs_getch.3x.html index 7246a2bd..a005043c 100644 --- a/doc/html/man/curs_getch.3x.html +++ b/doc/html/man/curs_getch.3x.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_getch.3x,v 1.76 2023/12/16 21:01:28 tom Exp @ + * @Id: curs_getch.3x,v 1.77 2023/12/23 16:36:18 tom Exp @ --> -curs_getch 3x 2023-12-16 ncurses 6.4 Library calls +curs_getch 3x 2023-12-23 ncurses 6.4 Library calls -
curs_getch 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_getch 3x 2023-12-23 ncurses 6.4 Library calls

curs_getch(3x) Library calls curs_getch(3x) @@ -68,7 +68,7 @@
DESCRIPTION
-
Reading characters
+
Reading Characters
The getch, wgetch, mvgetch and mvwgetch, routines read a character from the window. In no-delay mode, if no input is waiting, the value ERR is returned. In delay mode, the program waits until the system passes @@ -98,7 +98,7 @@ is read. -
Keypad mode
+
Keypad Mode
If keypad is TRUE, and a function key is pressed, the token for that function key is returned instead of the raw characters: @@ -129,13 +129,13 @@ pressed. -
Ungetting characters
+
Ungetting Characters
The ungetch routine places ch back onto the input queue to be returned by the next call to wgetch. There is just one input queue for all windows. -
Predefined key-codes
+
Predefined Key Codes
The following special keys are defined in <curses.h>. o Except for the special case KEY_RESIZE, it is necessary to enable @@ -267,7 +267,7 @@ escape sequences, just like a function key. -
Testing key-codes
+
Testing Key Codes
The has_key routine takes a key-code value from the above list, and returns TRUE or FALSE according to whether the current terminal type recognizes a key with that value. @@ -342,35 +342,44 @@ mapped to KEY_IC. +
EXTENSIONS
+ has_key was designed for ncurses(3x), and is not found in SVr4 curses, + 4.4BSD curses, or any other previous curses implementation. + +
PORTABILITY
- The *get* functions are described in the XSI Curses standard, Issue 4. - They read single-byte characters only. The standard specifies that - they return ERR on failure, but specifies no error conditions. - - The echo behavior of these functions on input of KEY_ or backspace - characters was not specified in the SVr4 documentation. This - description is adopted from the XSI Curses standard. - - The behavior of getch and friends in the presence of handled signals is - unspecified in the SVr4 and XSI Curses documentation. Under historical - curses implementations, it varied depending on whether the operating - system's implementation of handled signal receipt interrupts a read(2) - call in progress or not, and also (in some implementations) depending - on whether an input timeout or non-blocking mode has been set. - - KEY_MOUSE is mentioned in XSI Curses, along with a few related terminfo - capabilities, but no higher-level functions use the feature. The + Applications employing ncurses extensions should condition their use on + the visibility of the NCURSES_VERSION preprocessor macro. + + X/Open Curses, Issue 4, Version 2, describes getch, wgetch, mvgetch, + mvwgetch, and ungetch. They read single-byte characters only. The + standard specifies that they return ERR on failure, but describes no + failure conditions. + + The echo behavior of these functions on input of KEY_ or backspace + characters was not specified in the SVr4 documentation. This + description is adapted from X/Open Curses. + + The behavior of getch and friends in the presence of signal handlers is + unspecified in the SVr4 documentation and X/Open Curses. Under + historical curses implementations, it varied depending on whether the + operating system's dispatch of a signal to a handler interrupts a + read(2) call in progress or not, and also (in some implementations) + whether an input timeout or non-blocking mode has been set. + + KEY_MOUSE is mentioned in X/Open Curses, along with a few related term- + info capabilities, but no higher-level functions use the feature. The implementation in ncurses is an extension. - KEY_RESIZE is an extension first implemented for ncurses. NetBSD - curses later added this extension. + KEY_RESIZE is an extension first implemented for ncurses. NetBSD + curses later added this extension. - Programmers concerned about portability should be prepared for either - of two cases: (a) signal receipt does not interrupt getch; (b) signal - receipt interrupts getch and causes it to return ERR with errno set to + Programmers concerned about portability should be prepared for either + of two cases: (a) signal receipt does not interrupt getch; (b) signal + receipt interrupts getch and causes it to return ERR with errno set to EINTR. - The has_key function is unique to ncurses. We recommend that any code + The has_key function is unique to ncurses. We recommend that any code using it be conditionalized on the NCURSES_VERSION feature macro. @@ -378,12 +387,12 @@ curses(3x), curs_inopts(3x), curs_mouse(3x), curs_move(3x), curs_outopts(3x), curs_refresh(3x), curs_variables(3x), resizeterm(3x) - Comparable functions in the wide-character (ncursesw) library are + Comparable functions in the wide-character (ncursesw) library are described in curs_get_wch(3x). -ncurses 6.4 2023-12-16 curs_getch(3x) +ncurses 6.4 2023-12-23 curs_getch(3x)

@@ -391,15 +400,16 @@ ncurses 6.4 2023-12-16 SYNOPSIS
DESCRIPTION
-
Reading characters
-
Keypad mode
-
Ungetting characters
-
Predefined key-codes
-
Testing key-codes
+
Reading Characters
+
Keypad Mode
+
Ungetting Characters
+
Predefined Key Codes
+
Testing Key Codes

RETURN VALUE

NOTES
+
EXTENSIONS

PORTABILITY

SEE ALSO

diff --git a/doc/html/man/curs_initscr.3x.html b/doc/html/man/curs_initscr.3x.html index 995f186d..8179e408 100644 --- a/doc/html/man/curs_initscr.3x.html +++ b/doc/html/man/curs_initscr.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_initscr.3x,v 1.59 2023/12/17 23:56:04 tom Exp @ + * @Id: curs_initscr.3x,v 1.60 2023/12/23 16:27:25 tom Exp @ --> -curs_initscr 3x 2023-12-17 ncurses 6.4 Library calls +curs_initscr 3x 2023-12-23 ncurses 6.4 Library calls -
curs_initscr 3x 2023-12-17 ncurses 6.4 Library calls
+
curs_initscr 3x 2023-12-23 ncurses 6.4 Library calls

curs_initscr(3x) Library calls curs_initscr(3x) @@ -87,7 +87,7 @@ use newterm. The routine newterm should be called once for each terminal. It - returns a variable of type SCREEN * which should be saved as a + returns a variable of type SCREEN * which should be saved as a reference to that terminal. newterm's arguments are o the type of the terminal to be used in place of $TERM, @@ -99,8 +99,8 @@ If the type parameter is NULL, $TERM will be used. The file descriptor of the output stream is passed to setupterm(3x), - which returns a pointer to a TERMINAL structure. newterm's return - value holds a pointer to the TERMINAL structure. + which returns a pointer to a TERMINAL structure. newterm's return + value holds a pointer to the TERMINAL structure.
endwin
@@ -139,14 +139,14 @@ The set_term routine is used to switch between different terminals. The screen reference new becomes the new current terminal. The previous terminal is returned by the routine. This is the only routine - which manipulates SCREEN pointers; all other routines affect only the + which manipulates SCREEN pointers; all other routines affect only the current terminal.
delscreen
- The delscreen routine frees storage associated with the SCREEN data + The delscreen routine frees storage associated with the SCREEN data structure. The endwin routine does not do this, so delscreen should be - called after endwin if a particular SCREEN is no longer needed. + called after endwin if a particular SCREEN is no longer needed.
RETURN VALUE
@@ -191,17 +191,17 @@ redundant to check the return value of initscr in XSI Curses. Calling endwin does not dispose of the memory allocated in initscr or - newterm. Deleting a SCREEN provides a way to do this: + newterm. Deleting a SCREEN provides a way to do this: - o X/Open Curses does not say what happens to WINDOWs when delscreen - "frees storage associated with the SCREEN" nor does the SVr4 + o X/Open Curses does not say what happens to WINDOWs when delscreen + "frees storage associated with the SCREEN" nor does the SVr4 documentation help, adding that it should be called after endwin if - a SCREEN is no longer needed. + a SCREEN is no longer needed. - o However, WINDOWs are implicitly associated with a SCREEN. so that + o However, WINDOWs are implicitly associated with a SCREEN. so that it is reasonable to expect delscreen to deal with these. - o SVr4 curses deletes the standard WINDOW structures stdscr and + o SVr4 curses deletes the standard WINDOW structures stdscr and curscr as well as a work area newscr. SVr4 curses ignores other windows. @@ -210,12 +210,12 @@ windows when delscreen is called. o NetBSD copied this feature of ncurses in 2001. PDCurses follows - the SVr4 model, deleting only the standard WINDOW structures. + the SVr4 model, deleting only the standard WINDOW structures.
High-level versus Low-level
Different implementations may disagree regarding the level of some - functions. For example, SCREEN (returned by newterm) and TERMINAL + functions. For example, SCREEN (returned by newterm) and TERMINAL (returned by setupterm(3x)) hold file descriptors for the output stream. If an application switches screens using set_term, or switches terminals using set_curterm(3x), applications which use the output file @@ -224,12 +224,12 @@ For example - o NetBSD's baudrate(3x) function uses the descriptor in TERMINAL. - ncurses and SVr4 use the descriptor in SCREEN. + o NetBSD's baudrate(3x) function uses the descriptor in TERMINAL. + ncurses and SVr4 use the descriptor in SCREEN. - o NetBSD and ncurses use the descriptor in TERMINAL for terminal I/O + o NetBSD and ncurses use the descriptor in TERMINAL for terminal I/O modes, e.g., def_shell_mode(3x), def_prog_mode(3x). SVr4 curses - uses the descriptor in SCREEN. + uses the descriptor in SCREEN. Unset TERM Variable If the TERM variable is missing or empty, initscr uses the value @@ -262,14 +262,14 @@ The handler attempts to cleanup the screen on exit. Although it usually works as expected, there are limitations: - o Walking the SCREEN list is unsafe, since all list management + o Walking the SCREEN list is unsafe, since all list management is done without any signal blocking. o On systems which have REENTRANT turned on, set_term uses functions which could deadlock or misbehave in other ways. - o endwin calls other functions, many of which use stdio or other - library functions which are clearly unsafe. + o endwin calls other functions, many of which use stdio(3) or + other library functions which are clearly unsafe. SIGTERM This uses the same handler as SIGINT, with the same limitations. @@ -299,7 +299,7 @@ -ncurses 6.4 2023-12-17 curs_initscr(3x) +ncurses 6.4 2023-12-23 curs_initscr(3x)

diff --git a/doc/html/man/curs_inopts.3x.html b/doc/html/man/curs_inopts.3x.html index d9a8d55e..76f43fbd 100644 --- a/doc/html/man/curs_inopts.3x.html +++ b/doc/html/man/curs_inopts.3x.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_inopts.3x,v 1.59 2023/12/16 20:32:22 tom Exp @ + * @Id: curs_inopts.3x,v 1.60 2023/12/23 16:36:18 tom Exp @ --> -curs_inopts 3x 2023-12-16 ncurses 6.4 Library calls +curs_inopts 3x 2023-12-23 ncurses 6.4 Library calls -
curs_inopts 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_inopts 3x 2023-12-23 ncurses 6.4 Library calls

curs_inopts(3x) Library calls curs_inopts(3x) @@ -92,19 +92,19 @@
DESCRIPTION
- 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. - 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. - - -
cbreak/nocbreak
- 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 - characters are unaffected), making characters typed by the user + 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. + + +
cbreak, nocbreak
+ Normally, the terminal 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 characters are unaffected), making characters typed by the user immediately available to the program. The nocbreak routine returns the terminal to normal (cooked) mode. @@ -115,15 +115,15 @@ discussion of how these routines interact with echo and noecho.] -
echo/noecho
+
echo, 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 - 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.] + user are echoed by getch(3x) as they are typed. Echoing by the + terminal driver is always disabled, but initially 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.]
halfdelay
@@ -138,11 +138,11 @@
intrflush
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 + terminal driver queue is 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. + on the screen. Disabling the option (bf is FALSE), prevents the flush. + The default for the option is inherited from the terminal driver + settings. The win argument is ignored.
keypad
@@ -159,18 +159,18 @@
meta
Initially, whether the terminal returns 7 or 8 significant bits on - input depends on the control mode of the tty driver [see termios(3)]. - To force 8 bits to be returned, invoke 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. - - -
nl/nonl
+ input depends on the control mode of the terminal driver [see + termios(3)]. To force 8 bits to be returned, invoke 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. + + +
nl, nonl
The nl and nonl routines control whether the underlying display device translates the return key into newline on input. @@ -185,21 +185,21 @@ When interpreting an 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. + distinguish sequences produced by a function key from those typed by a + user. -
raw/noraw
+
raw, noraw
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 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. + terminal driver that are not set by curses. -
qiflush/noqiflush
+
qiflush, nqiflush
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 termios(3)]. When qiflush is called, the queues will be @@ -208,23 +208,23 @@ the interrupt had not occurred, after the handler exits. -
timeout/wtimeout
+
timeout, wtimeout
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 + a given window. If delay is negative, a blocking read is used (i.e., + waits indefinitely for input). If delay is zero, then a 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).
typeahead
- 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 + 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 refresh(3x) or doupdate is called again. This allows faster response - to commands typed in advance. Normally, the input FILE pointer passed + 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 @@ -247,96 +247,97 @@
NOTES
- Note that echo, noecho, halfdelay, intrflush, meta, nl, nonl, 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. - 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 + noraw and nocbreak follow historical practice in that they attempt to + restore normal ("cooked") mode from raw and cbreak modes respectively. + Mixing raw/noraw and cbreak/nocbreak calls leads to terminal driver + control states that are hard to predict or understand; doing so is not recommended.
EXTENSIONS
- This implementation provides four functions which may be used to detect - if the corresponding flags were set or reset: + ncurses provides four "is_" functions that may be used to detect if the + corresponding flags were set or reset. - Query Set Reset - ------------------------------ - is_cbreak cbreak nocbreak - is_echo echo noecho - is_nl nl nonl - is_raw raw noraw + 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 flag is set, + 1 if the flag is set, - 0 if the flag is reset, or + 0 if the flag is reset, or - -1 if the curses library was not initialized. + -1 if the library is not initialized. - These routines are specific to ncurses. They were not supported on - Version 7, BSD or System V implementations. It is recommended that any - code depending on ncurses extensions be conditioned using - NCURSES_VERSION. + They were designed for ncurses(3x), and are not found in SVr4 curses, + 4.4BSD curses, or any other previous curses implementation.
PORTABILITY
- Except as noted in the section on extensions, 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 - program remains in cooked mode. - - The XSI Curses standard is ambiguous on the question of whether raw - should disable the CRLF translations controlled by nl and nonl. BSD - curses did turn off these translations; AT&T curses (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. - - When keypad is first enabled, ncurses loads the key-definitions for the - current terminal description. If the terminal 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 (depending on - previous loads of terminal descriptions) may differ from one execution + 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, + Version 2 describes these functions. + + ncurses follows X/Open Curses and the historical practice of 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 program + remains in cooked mode. + + X/Open Curses is ambiguous regarding whether raw should disable the + CR/LF translations controlled by nl and nonl. BSD curses did turn off + these translations; AT&T curses (at least as late as SVr1) 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, 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 + 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 + keyname(3x) 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(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 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 + 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. + 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 - capability's value is the same as a previously-loaded key definition, + 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 + capability's value is the same as a previously-loaded key definition, the later definition is the one used.
SEE ALSO
- curses(3x), curs_getch(3x), curs_initscr(3x), curs_util(3x), + curses(3x), curs_getch(3x), curs_initscr(3x), curs_util(3x), define_key(3x), termios(3) -ncurses 6.4 2023-12-16 curs_inopts(3x) +ncurses 6.4 2023-12-23 curs_inopts(3x)

@@ -344,18 +345,18 @@ ncurses 6.4 2023-12-16 SYNOPSIS
DESCRIPTION
-
cbreak/nocbreak
-
echo/noecho
+
cbreak, nocbreak
+
echo, noecho

halfdelay

intrflush

keypad

meta
-
nl/nonl
+
nl, nonl

nodelay

notimeout
-
raw/noraw
-
qiflush/noqiflush
-
timeout/wtimeout
+
raw, noraw
+
qiflush, nqiflush
+
timeout, wtimeout

typeahead

diff --git a/doc/html/man/curs_ins_wch.3x.html b/doc/html/man/curs_ins_wch.3x.html index 1fbbd02d..12967302 100644 --- a/doc/html/man/curs_ins_wch.3x.html +++ b/doc/html/man/curs_ins_wch.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_ins_wch.3x,v 1.24 2023/11/25 11:32:28 tom Exp @ + * @Id: curs_ins_wch.3x,v 1.26 2023/12/23 16:03:24 tom Exp @ --> -curs_ins_wch 3x 2023-11-25 ncurses 6.4 Library calls +curs_ins_wch 3x 2023-12-23 ncurses 6.4 Library calls -
curs_ins_wch 3x 2023-11-25 ncurses 6.4 Library calls
+
curs_ins_wch 3x 2023-12-23 ncurses 6.4 Library calls

curs_ins_wch(3x) Library calls curs_ins_wch(3x) @@ -48,45 +48,63 @@
NAME
ins_wch, mvins_wch, mvwins_wch, wins_wch - insert a curses complex - character string in a window + character in a window
SYNOPSIS
- #include <curses.h> + #include <curses.h> int ins_wch(const cchar_t *wch); int wins_wch(WINDOW *win, const cchar_t *wch); - int mvins_wch(int y, int x, const cchar_t *wch); int mvwins_wch(WINDOW *win, int y, int x, const cchar_t *wch);
DESCRIPTION
- These routines, insert the complex character wch with rendition before - the character under the cursor. All characters to the right of the - cursor are moved one space to the right, with the possibility of the - rightmost character on the line being lost. The insertion operation - does not change the cursor position. + These functions insert the curses complex character wch at the cursor + in the specified window win (or stdscr). The character previously at + the cursor and any to its right move one cell to the right; the + rightmost character on the line is discarded. The cursor does not + advance.
RETURN VALUE
- If successful, these functions return OK. If not, they return ERR. + These functions return OK on success and ERR on failure. + + Functions taking a WINDOW pointer argument fail if the pointer is NULL. + + Functions prefixed with "mv" first perform cursor movement using wmove + and fail if the position (y, x) is outside the window. + + +
NOTES
+ A terminal's insert_character (ich1) capability is not necessarily + employed. - Functions with a "mv" prefix first perform a cursor movement using - wmove, and return an error if the position is outside the window, or if - the window pointer is null. + ins_wch, mvins_wch, and mvwins_wch may be implemented as macros.
PORTABILITY
- These functions are described in the XSI Curses standard, Issue 4. + X/Open Curses, Issue 4, describes these functions. + + SVr4 describes successful return values only as "an integer value other + than ERR". + + +
HISTORY
+ SVr4 (1989) implemented these functions under the names inswch, + winswch, mvinswch, and mvwinswch.
SEE ALSO
- curses(3x), curs_insch(3x) + curs_insch(3x) describes comparable functions in the non-wide-character + curses configuration. + + curses(3x), terminfo(5) -ncurses 6.4 2023-11-25 curs_ins_wch(3x) +ncurses 6.4 2023-12-23 curs_ins_wch(3x)

@@ -94,7 +112,9 @@ ncurses 6.4 2023-11-25 SYNOPSIS
DESCRIPTION

RETURN VALUE
+
NOTES

PORTABILITY
+
HISTORY

SEE ALSO

diff --git a/doc/html/man/curs_insch.3x.html b/doc/html/man/curs_insch.3x.html index f0a1be0d..0e3683c2 100644 --- a/doc/html/man/curs_insch.3x.html +++ b/doc/html/man/curs_insch.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_insch.3x,v 1.34 2023/12/16 21:09:11 tom Exp @ + * @Id: curs_insch.3x,v 1.36 2023/12/23 16:03:24 tom Exp @ --> -curs_insch 3x 2023-12-16 ncurses 6.4 Library calls +curs_insch 3x 2023-12-23 ncurses 6.4 Library calls -
curs_insch 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_insch 3x 2023-12-23 ncurses 6.4 Library calls

curs_insch(3x) Library calls curs_insch(3x) @@ -56,49 +56,49 @@ int insch(chtype ch); int winsch(WINDOW *win, chtype ch); - int mvinsch(int y, int x, chtype ch); int mvwinsch(WINDOW *win, int y, int x, chtype ch);
DESCRIPTION
- These routines insert the character ch before the character under the - cursor. All characters to the right of the cursor are moved one space - to the right, with the possibility of the rightmost character on the - line being lost. The insertion operation does not change the cursor - position. + These functions insert the curses character ch at the cursor in the + specified window win (or stdscr). The character previously at the + cursor and any to its right move one cell to the right; the rightmost + character on the line is discarded. The cursor does not advance.
RETURN VALUE
- These routines return the integer ERR upon failure and an OK (SVr4 - specifies only "an integer value other than ERR") upon successful - completion. + These functions return OK on success and ERR on failure. + + Functions taking a WINDOW pointer argument fail if the pointer is NULL. - Functions with a "mv" prefix first perform a cursor movement using - wmove, and return an error if the position is outside the window, or if - the window pointer is null. + Functions prefixed with "mv" first perform cursor movement using wmove + and fail if the position (y, x) is outside the window.
NOTES
- These routines do not necessarily imply use of a hardware insert - character feature. + A terminal's insert_character (ich1) capability is not necessarily + employed. - Note that insch, mvinsch, and mvwinsch may be macros. + insch, mvinsch, and mvwinsch may be implemented as macros.
PORTABILITY
- These functions are described in the XSI Curses standard, Issue 4. + X/Open Curses, Issue 4, describes these functions. + + SVr4 describes successful return values only as "an integer value other + than ERR".
SEE ALSO
- curses(3x) + curs_ins_wch(3x) describes comparable functions in the wide-character + curses configuration. - Comparable functions in the wide-character (ncursesw) library are - described in curs_ins_wch(3x). + curses(3x), terminfo(5) -ncurses 6.4 2023-12-16 curs_insch(3x) +ncurses 6.4 2023-12-23 curs_insch(3x)

diff --git a/doc/html/man/curs_legacy.3x.html b/doc/html/man/curs_legacy.3x.html index b4bf5283..0996d5f7 100644 --- a/doc/html/man/curs_legacy.3x.html +++ b/doc/html/man/curs_legacy.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_legacy.3x,v 1.29 2023/10/21 10:28:36 tom Exp @ + * @Id: curs_legacy.3x,v 1.30 2023/12/23 16:40:10 tom Exp @ --> -curs_legacy 3x 2023-10-21 ncurses 6.4 Library calls +curs_legacy 3x 2023-12-23 ncurses 6.4 Library calls -
curs_legacy 3x 2023-10-21 ncurses 6.4 Library calls
+
curs_legacy 3x 2023-12-23 ncurses 6.4 Library calls

curs_legacy(3x) Library calls curs_legacy(3x) @@ -102,12 +102,14 @@
NOTES
- All of these interfaces are provided as macros and functions. The - macros are suppressed (and only the functions provided) when - NCURSES_OPAQUE is defined. The standard forms such as getyx must be - implemented as macros, and (in this implementation) are defined in - terms of the functions described here, to avoid reliance on internal - details of the WINDOW structure. + All of these interfaces are implemented as macros and functions. The + macros are suppressed (and only the functions provided) in an "opaque" + ncurses build, which defines the preprocessor symbol NCURSES_OPAQUE. + See section "ALTERNATE CONFIGURATIONS" in ncurses(3x). + + The standard forms such as getyx must be implemented as macros, and (in + this implementation) are defined in terms of the functions described + here, to avoid reliance on internal details of the WINDOW structure.
PORTABILITY
@@ -125,7 +127,7 @@ -ncurses 6.4 2023-10-21 curs_legacy(3x) +ncurses 6.4 2023-12-23 curs_legacy(3x)

diff --git a/doc/html/man/curs_memleaks.3x.html b/doc/html/man/curs_memleaks.3x.html index 0572643c..4c1876f7 100644 --- a/doc/html/man/curs_memleaks.3x.html +++ b/doc/html/man/curs_memleaks.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_memleaks.3x,v 1.32 2023/12/16 20:32:22 tom Exp @ + * @Id: curs_memleaks.3x,v 1.33 2023/12/23 16:22:08 tom Exp @ --> -curs_memleaks 3x 2023-12-16 ncurses 6.4 Library calls +curs_memleaks 3x 2023-12-23 ncurses 6.4 Library calls -
curs_memleaks 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_memleaks 3x 2023-12-23 ncurses 6.4 Library calls

curs_memleaks(3x) Library calls curs_memleaks(3x) @@ -116,7 +116,7 @@ the memory allocated by curses: o The portable part of exit_curses can be freed using delscreen, - passing the SCREEN* pointer returned by newterm. + passing the SCREEN pointer returned by newterm. In some implementations, there is a global variable sp which could be used, e.g., if the screen were only initialized using initscr. @@ -132,7 +132,7 @@ -ncurses 6.4 2023-12-16 curs_memleaks(3x) +ncurses 6.4 2023-12-23 curs_memleaks(3x)

diff --git a/doc/html/man/curs_mouse.3x.html b/doc/html/man/curs_mouse.3x.html index 8067e30e..a608a350 100644 --- a/doc/html/man/curs_mouse.3x.html +++ b/doc/html/man/curs_mouse.3x.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_mouse.3x,v 1.82 2023/12/16 21:08:16 tom Exp @ + * @Id: curs_mouse.3x,v 1.83 2023/12/23 20:37:56 tom Exp @ --> -curs_mouse 3x 2023-12-16 ncurses 6.4 Library calls +curs_mouse 3x 2023-12-23 ncurses 6.4 Library calls -
curs_mouse 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_mouse 3x 2023-12-23 ncurses 6.4 Library calls

curs_mouse(3x) Library calls curs_mouse(3x) @@ -104,7 +104,7 @@ is device-dependent. -
Mouse events
+
Mouse Events
Here are the mouse event type masks which may be defined: Name Description @@ -253,21 +253,10 @@
NOTES
- The feature macro NCURSES_MOUSE_VERSION is provided so the preprocessor - can be used to test whether these features are present. If the - interface is changed, the value of NCURSES_MOUSE_VERSION will be - incremented. These values for NCURSES_MOUSE_VERSION may be specified - when configuring ncurses: - - 1 has definitions for reserved events. The mask uses 28 bits. - - 2 adds definitions for button 5, removes the definitions for - reserved events. The mask uses 29 bits. - - The order of the MEVENT structure members is not guaranteed. + The order of the MEVENT structure members is not guaranteed. Additional fields may be added to the structure in the future. - Under ncurses, these calls are implemented using either xterm's built- + Under ncurses, these calls are implemented using either xterm's built- in mouse-tracking API or platform-specific drivers including o Alessandro Rubini's gpm server @@ -279,36 +268,52 @@ If you are using an unsupported configuration, mouse events will not be visible to ncurses (and the mousemask function will always return 0). - If the terminfo entry contains a XM string, this is used in the xterm - mouse driver to control the way the terminal is initialized for mouse - operation. The default, if XM is not found, corresponds to private - mode 1000 of xterm: + If the terminfo entry contains a XM string, this is used in the xterm + mouse driver to control the way the terminal is initialized for mouse + operation. The default, if XM is not found, corresponds to private + mode 1000 of xterm: \E[?1000%?%p1%{1}%=%th%el%; - The mouse driver also recognizes a newer xterm private mode 1006, e.g., + The mouse driver also recognizes a newer xterm private mode 1006, e.g., \E[?1006;1000%?%p1%{1}%=%th%el%; - The z member in the event structure is not presently used. It is - intended for use with touch screens (which may be pressure-sensitive) + The z member in the event structure is not presently used. It is + intended for use with touch screens (which may be pressure-sensitive) or with 3D-mice/trackballs/power gloves. - The ALL_MOUSE_EVENTS class does not include REPORT_MOUSE_POSITION. - They are distinct. For example, in xterm, wheel/scrolling mice send - position reports as a sequence of presses of buttons 4 or 5 without + The ALL_MOUSE_EVENTS class does not include REPORT_MOUSE_POSITION. + They are distinct. For example, in xterm, wheel/scrolling mice send + position reports as a sequence of presses of buttons 4 or 5 without matching button-releases. +
EXTENSIONS
+ These functions were designed for ncurses(3x), and are not found in + SVr4 curses, 4.4BSD curses, or any other previous curses + implementation. (SVr4 curses did have a getmouse function, which took + no argument and returned a different type.) + +
PORTABILITY
- These calls were designed for ncurses, and are not found in SVr4 - curses, 4.4BSD curses, or any other previous version of curses. + Applications employing the ncurses mouse extension should condition its + use on the visibility of the NCURSES_MOUSE_VERSION preprocessor macro. + When the interface changes, the macro's value increments. Multiple + versions are available when ncurses is configured; see section + "ALTERNATE CONFIGURATIONS" of ncurses(3x). The following values may be + specified. + + 1 has definitions for reserved events. The mask uses 28 bits. + + 2 adds definitions for button 5, removes the definitions for + reserved events. The mask uses 29 bits. - SVr4 curses had support for the mouse in a variant of xterm(1). It is - mentioned in a few places, but with no supporting documentation: + SVr4 curses had support for the mouse in a variant of xterm(1). It is + mentioned in a few places, with little supporting documentation. - o the "libcurses" manual page lists functions for this feature which - are prototyped in curses.h: + o Its "libcurses" manual page lists functions for this feature + prototyped in curses.h. extern int mouse_set(long int); extern int mouse_on(long int); @@ -318,7 +323,7 @@ extern void wmouse_position(WINDOW *, int *, int *); extern unsigned long getmouse(void), getbmap(void); - o the "terminfo" manual page lists capabilities for the feature + o Its "terminfo" manual page lists capabilities for the feature. buttons btns BT Number of buttons on the mouse get_mouse getm Gm Curses should get button events @@ -326,22 +331,23 @@ mouse_info minfo Mi Mouse status information req_mouse_pos reqmp RQ Request mouse position report - o the interface made assumptions (as does ncurses) about the escape + o The interface made assumptions (as does ncurses) about the escape sequences sent to and received from the terminal. - For instance the SVr4 curses library used the get_mouse capability - to tell the terminal which mouse button events it should send, - passing the mouse-button bit mask to the terminal. Also, it could - ask the terminal where the mouse was using the req_mouse_pos + For instance, the SVr4 curses library used the get_mouse capability + to tell the terminal which mouse button events it should send, + passing the mouse-button bit mask to the terminal. Also, it could + ask the terminal where the mouse was using the req_mouse_pos capability. - Those features required a terminal which had been modified to work - with curses. They were not part of the X Consortium's xterm. + Those features required a terminal program that had been modified + to work with SVr4 curses. They were not part of the X Consortium's + xterm. - When developing the xterm mouse support for ncurses in September 1995, + When developing the xterm mouse support for ncurses in September 1995, Eric Raymond was uninterested in using the same interface due to its lack of documentation. Later, in 1998, Mark Hesseling provided support - in PDCurses 2.3 using the SVr4 interface. PDCurses, however, does not + in PDCurses 2.3 using the SVr4 interface. PDCurses, however, does not use video terminals, making it unnecessary to be concerned about compatibility with the escape sequences. @@ -353,17 +359,17 @@ Mouse event reports from xterm are not detected correctly in a window with keypad application mode disabled, since they are interpreted as a - variety of function key. Set the the terminal's terminfo capability - kmous to "\E[M" (the beginning of the response from xterm for mouse - clicks). Other values of kmous are permitted under the same - assumption, that is, the report begins with that sequence. + variety of function key. Set the terminal's terminfo capability kmous + to "\E[M" (the beginning of the response from xterm for mouse clicks). + Other values of kmous are permitted under the same assumption, that is, + the report begins with that sequence. Because there are no standard response sequences that serve to identify terminals supporting the xterm mouse protocol, ncurses assumes that if kmous is defined in the terminal description, or if the terminal type's primary name or aliases contain the string "xterm", then the terminal may send mouse events. The kmous capability is checked first, allowing - use of newer xterm mouse protocols such as its private mode 1006. + use of newer xterm mouse protocols, such as its private mode 1006.
SEE ALSO
@@ -372,7 +378,7 @@ -ncurses 6.4 2023-12-16 curs_mouse(3x) +ncurses 6.4 2023-12-23 curs_mouse(3x)

@@ -381,7 +387,7 @@ ncurses 6.4 2023-12-16 DESCRIPTION

mousemask
-
Mouse events
+
Mouse Events

getmouse

ungetmouse

wenclose
@@ -393,6 +399,7 @@ ncurses 6.4 2023-12-16
RETURN VALUE

NOTES
+
EXTENSIONS

PORTABILITY

BUGS

SEE ALSO
diff --git a/doc/html/man/curs_print.3x.html b/doc/html/man/curs_print.3x.html index 97e81782..3fde9295 100644 --- a/doc/html/man/curs_print.3x.html +++ b/doc/html/man/curs_print.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_print.3x,v 1.35 2023/12/16 20:32:22 tom Exp @ + * @Id: curs_print.3x,v 1.36 2023/12/23 16:36:18 tom Exp @ --> -curs_print 3x 2023-12-16 ncurses 6.4 Library calls +curs_print 3x 2023-12-23 ncurses 6.4 Library calls -
curs_print 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_print 3x 2023-12-23 ncurses 6.4 Library calls

curs_print(3x) Library calls curs_print(3x) @@ -84,11 +84,14 @@ sent to the printer. +
EXTENSIONS
+ mcprint was designed for ncurses(3x), and was not found in SVr4 curses, + 4.4BSD curses, or any other previous curses implementation. + +
PORTABILITY
- The mcprint call was designed for ncurses, and is not found in SVr4 - curses, 4.4BSD curses, or any other previous version of curses. It is - recommended that any code depending on ncurses extensions be - conditioned using NCURSES_VERSION. + Applications employing this ncurses extension should condition its use + on the visibility of the NCURSES_VERSION preprocessor macro.
BUGS
@@ -100,7 +103,7 @@ -ncurses 6.4 2023-12-16 curs_print(3x) +ncurses 6.4 2023-12-23 curs_print(3x)

@@ -108,6 +111,7 @@ ncurses 6.4 2023-12-16 SYNOPSIS
DESCRIPTION

RETURN VALUE
+
EXTENSIONS

PORTABILITY

BUGS

SEE ALSO
diff --git a/doc/html/man/curs_printw.3x.html b/doc/html/man/curs_printw.3x.html index 47ac8e5e..9a312a05 100644 --- a/doc/html/man/curs_printw.3x.html +++ b/doc/html/man/curs_printw.3x.html @@ -27,7 +27,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_printw.3x,v 1.45 2023/12/18 00:03:28 tom Exp @ + * @Id: curs_printw.3x,v 1.47 2023/12/23 14:41:07 tom Exp @ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\ * libcurses/printw.c * https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\ @@ -39,12 +39,12 @@ -curs_printw 3x 2023-12-17 ncurses 6.4 Library calls +curs_printw 3x 2023-12-23 ncurses 6.4 Library calls -
curs_printw 3x 2023-12-17 ncurses 6.4 Library calls
+
curs_printw 3x 2023-12-23 ncurses 6.4 Library calls

curs_printw(3x) Library calls curs_printw(3x) @@ -111,7 +111,7 @@ using the stdarg.h interface. o X/Open Curses, Issue 5, Draft 2 (December 2007) marked vwprintw - (along with vwscanw and the termcap interface) as withdrawn. After + (along with vwscanw and the termcap interface) as withdrawn. After incorporating review comments, this became X/Open Curses, Issue 7 (2009). @@ -152,7 +152,7 @@ -ncurses 6.4 2023-12-17 curs_printw(3x) +ncurses 6.4 2023-12-23 curs_printw(3x)

diff --git a/doc/html/man/curs_scanw.3x.html b/doc/html/man/curs_scanw.3x.html index a0b8d7cc..2c549ce4 100644 --- a/doc/html/man/curs_scanw.3x.html +++ b/doc/html/man/curs_scanw.3x.html @@ -27,7 +27,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_scanw.3x,v 1.44 2023/12/17 22:50:40 tom Exp @ + * @Id: curs_scanw.3x,v 1.47 2023/12/23 14:41:50 tom Exp @ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\ * libcurses/scanw.c * https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\ @@ -39,12 +39,12 @@ -curs_scanw 3x 2023-12-17 ncurses 6.4 Library calls +curs_scanw 3x 2023-12-23 ncurses 6.4 Library calls -
curs_scanw 3x 2023-12-17 ncurses 6.4 Library calls
+
curs_scanw 3x 2023-12-23 ncurses 6.4 Library calls

curs_scanw(3x) Library calls curs_scanw(3x) @@ -116,7 +116,7 @@ using the stdarg.h interface. o X/Open Curses, Issue 5, Draft 2 (December 2007) marked vwscanw - (along with vwscanw and the termcap interface) as withdrawn. After + (along with vwscanw and the termcap interface) as withdrawn. After incorporating review comments, this became X/Open Curses, Issue 7 (2009). @@ -162,9 +162,9 @@ SVr3 (1987) added mvscanw, and mvwscanw, stating - These routines correspond to scanf(3S), as do their arguments + "[t]hese routines correspond to scanf(3S), as do their arguments and return values. wgetstr() is called on the window, and the - resulting line is used as input for the scan. + resulting line is used as input for the scan." SVr3 also implemented vwscanw, describing its third parameter as a va_list, defined in varargs.h, and referred the reader to the manual @@ -184,7 +184,7 @@ -ncurses 6.4 2023-12-17 curs_scanw(3x) +ncurses 6.4 2023-12-23 curs_scanw(3x)

diff --git a/doc/html/man/curs_sp_funcs.3x.html b/doc/html/man/curs_sp_funcs.3x.html index 73869535..e943b6c5 100644 --- a/doc/html/man/curs_sp_funcs.3x.html +++ b/doc/html/man/curs_sp_funcs.3x.html @@ -27,7 +27,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_sp_funcs.3x,v 1.45 2023/12/16 20:32:22 tom Exp @ + * @Id: curs_sp_funcs.3x,v 1.46 2023/12/23 16:26:05 tom Exp @ * *************************************************************************** * *************************************************************************** * *************************************************************************** @@ -37,12 +37,12 @@ -curs_sp_funcs 3x 2023-12-16 ncurses 6.4 Library calls +curs_sp_funcs 3x 2023-12-23 ncurses 6.4 Library calls -
curs_sp_funcs 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_sp_funcs 3x 2023-12-23 ncurses 6.4 Library calls

curs_sp_funcs(3x) Library calls curs_sp_funcs(3x) @@ -225,12 +225,12 @@ This implementation can be configured to provide a set of functions which improve the ability to manage multiple screens. This feature can be added to any of the configurations supported by ncurses; it adds new - entrypoints without changing the meaning of any of the existing ones. + symbols without changing the meaning of any of the existing ones. -
IMPROVED FUNCTIONS
+
Improved Functions
Most of the functions are new versions of existing functions. A - parameter is added at the front of the parameter list. It is a SCREEN + parameter is added at the front of the parameter list. It is a SCREEN pointer. The existing functions all use the current screen, which is a static @@ -239,7 +239,7 @@ multiple screens. -
NEW FUNCTIONS
+
New Functions
Here are the new functions: ceiling_panel @@ -254,8 +254,8 @@ With the screen-pointer extension, there are situations where it must create a current screen before the unextended library does. The new_prescr function is used internally to handle these cases. - It is also provided as an entrypoint to allow applications to - customize the library initialization. + It is also provided to allow applications to customize library + initialization.
NOTES
@@ -297,7 +297,7 @@ -ncurses 6.4 2023-12-16 curs_sp_funcs(3x) +ncurses 6.4 2023-12-23 curs_sp_funcs(3x)

@@ -305,8 +305,8 @@ ncurses 6.4 2023-12-16 SYNOPSIS
DESCRIPTION
-
IMPROVED FUNCTIONS
-
NEW FUNCTIONS
+
Improved Functions
+
New Functions

NOTES
diff --git a/doc/html/man/curs_termcap.3x.html b/doc/html/man/curs_termcap.3x.html index 85c31554..fff45be4 100644 --- a/doc/html/man/curs_termcap.3x.html +++ b/doc/html/man/curs_termcap.3x.html @@ -27,7 +27,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_termcap.3x,v 1.76 2023/12/18 00:22:30 tom Exp @ + * @Id: curs_termcap.3x,v 1.80 2023/12/23 20:19:05 tom Exp @ * See <https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/\ * termlib/termcap.c>. * See https://www.oreilly.com/openbook/opensources/book/kirkmck.html @@ -46,7 +46,7 @@ * Observe the `tncktc()`, `tnamatch()`, `tskip()`, and `tdecode()` * entry points disappearing from termcap.c. * 2BSD became a branch retaining support for non-virtual memory - * systems (like the PDP-11) whereas most BSD development focused on + * systems (such as the PDP-11) whereas most BSD development focused on * the VAX and other VM-enabled systems starting with 3BSD. * This man page previously located a termcap.h in 2BSD, but that may * be confusion arising from its backport to 2.9BSD (and still present @@ -62,12 +62,12 @@ -curs_termcap 3x 2023-12-17 ncurses 6.4 Library calls +curs_termcap 3x 2023-12-23 ncurses 6.4 Library calls -
curs_termcap 3x 2023-12-17 ncurses 6.4 Library calls
+
curs_termcap 3x 2023-12-23 ncurses 6.4 Library calls

curs_termcap(3x) Library calls curs_termcap(3x) @@ -106,15 +106,15 @@
Initialization
tgetent loads the terminal database entry for name; see term(7). This - must be done before calling any of the other functions. It returns: + must be done before calling any of the other functions. It returns - 1 on success, + 1 on success, - 0 if there is no such entry (or if the matching entry describes a - generic terminal, having too little information for curses - applications to run), and + 0 if there is no such entry (or if the matching entry describes a + generic terminal, having too little information for curses + applications to run), and - -1 if the terminfo database could not be found. + -1 if the terminfo database could not be found. This implementation differs from those of historical termcap libraries. @@ -126,10 +126,10 @@ form, which is not the same thing. o The meanings of the return values differ. The BSD termcap - library does not check whether the terminal type description is - marked with the gn (generic) capability, nor whether the - terminal type description supports an addressable cursor, a - property essential for any curses implementation to operate. + library does not check whether the terminal type description + includes the generic (gn) capability, nor whether the terminal + type description supports an addressable cursor, a property + essential for any curses implementation to operate.
Retrieving Capability Values
@@ -175,9 +175,9 @@ Doing so reveals a quirk in tgoto: most hardware terminals use cursor addressing with row first, but the original developers of the termcap interface chose to put the col (column) parameter - first. The tgoto function swaps the order of parameters. It does - this even for calls requiring only a single parameter. In that - case, the first parameter is merely a placeholder. + first. The tgoto function swaps the order of its parameters. It + does this even for calls requiring only a single parameter. In + that case, the first parameter is merely a placeholder. o Normally the ncurses library is compiled without full termcap support. In that case, tgoto uses an internal version of tparm(3x) @@ -191,7 +191,7 @@ applications should not rely upon its availability. tputs is described in curs_terminfo(3x). It can retrieve capabilities - by either termcap or terminfo name. + by either termcap or terminfo code.
Global Variables
@@ -214,8 +214,8 @@ del_curterm(cur_term); to free this memory, but there is an additional complication with ncurses. It uses a fixed-size pool of storage locations, one per value - of the TERM environment variable when tgetent is called. The screen(1) - program relies upon this arrangement to improve its performance. + of the terminal name parameter given to tgetent. The screen(1) program + relies upon this arrangement to improve its performance. An application that uses only the termcap functions, not the higher level curses API, could release the memory using del_curterm(3x), @@ -255,18 +255,18 @@
Standards
o X/Open Curses, Issue 4, Version 2 (1996), describes these - functions. However, they are marked "TO BE WITHDRAWN". + functions, marking them as "TO BE WITHDRAWN". - o X/Open Curses, Issue 7 (2009) marked the termcap interface (along + o X/Open Curses, Issue 7 (2009) marks the termcap interface (along with vwprintw and vwscanw) as withdrawn. Neither X/Open Curses nor the SVr4 man pages documented the return - values of tgetent correctly, though all three were in fact returned - ever since SVr1. In particular, an omission in the X/Open Curses - specification has been misinterpreted to mean that tgetent returns OK - or ERR. Because the purpose of these functions is to provide - compatibility with the termcap library, that is a defect in X/Open - Curses, Issue 4, Version 2 rather than in ncurses. + values of tgetent correctly, though all three shown here were in fact + returned ever since SVr1. In particular, an omission in the X/Open + Curses specification has been misinterpreted to mean that tgetent + returns OK or ERR. Because the purpose of these functions is to + provide compatibility with the termcap library, that is a defect in + X/Open Curses, Issue 4, Version 2 rather than in ncurses. Compatibility with BSD termcap Externally visible variables are provided for support of certain @@ -313,36 +313,35 @@ 4BSD (November 1980) renamed termlib to termcap and added another test program. The library remained much the same though 4.3BSD (June 1986). - 4.4BSD-Lite (June 1994) refactored it but left the API unchanged. + 4.4BSD-Lite (June 1994) refactored it, leaving the API unchanged. - Function prototypes were a feature of the forthcoming ANSI C (1989). - Thus the library provided no header file declaring them. Nevertheless, - the BSD sources included two different termcap.h header files over - time. + Function prototypes were a feature of ANSI C (1989). Thus the library + itself provided no header file declaring them. Nevertheless, the BSD + sources included two different termcap.h header files over time. o One was used internally by jove(1) from 4.3BSD onward. It delcared global symbols for the termcap variables that it used. - o The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part of - libedit (also known as the editline library). CSRG source history + o The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part of + libedit (also known as the editline library). CSRG source history shows that this was added in mid-1992. The libedit header file was used internally as a convenience for compiling the editline library. It declared function prototypes, but no global variables. This header file was added to NetBSD's termcap library in mid-1994. - Meanwhile, GNU termcap began development in 1990. Its first release - (1.0) in 1991 included a termcap.h header. Its second (1.1) in - September 1992 modified the header to use const for the function - prototypes in the header where one would expect the parameters to be + Meanwhile, GNU termcap began development in 1990. Its first release + (1.0) in 1991 included a termcap.h header. Its second (1.1) in + September 1992 modified the header to use const for the function + prototypes in the header where one would expect the parameters to be read-only. BSD termcap did not. The prototype for tputs also - differed, but in that instance, it was libedit that differed from BSD + differed, but in that instance, it was libedit that differed from BSD termcap. - GNU termcap 1.3 was bundled with bash in mid-1993 to support the + GNU termcap 1.3 was bundled with bash(1) in mid-1993 to support the readline(3) library. - ncurses 1.8.1 (November 1993) provided a termcap.h file. It reflected - influence from GNU termcap and emacs(1) (rather than jove(1)), + ncurses 1.8.1 (November 1993) provided a termcap.h file. It reflected + influence from GNU termcap and emacs(1) (rather than jove(1)), providing the following interface: o global symbols used by emacs, @@ -351,43 +350,43 @@ o a prototype for tparam, a GNU termcap feature. - Later (in mid-1996) the tparam function was removed from ncurses. Any - two of the four implementations thus differ, and programs that intend + Later (in mid-1996) the tparam function was removed from ncurses. Any + two of the four implementations thus differ, and programs that intend to work with all termcap library interfaces must account for that fact.
BUGS
- If you call tgetstr to fetch ca or any other parameterized string - capability, be aware that it is returned in terminfo notation, not the - older and not-quite-compatible termcap notation. This does not cause - problems if all you do with it is call tgoto or tparm, which both - expand terminfo-style strings as terminfo does. (If ncurses is - configured to support termcap, tgoto checks whether the string is term- - info-style by looking for "%p" parameters or "<...>" delays, and - invokes a termcap-style parser if the string appears not to use term- - info syntax.) - - Because terminfo's syntax for padding in string capabilities differs + If you call tgetstr to fetch column_address (ch) or any other + parameterized string capability, be aware that it is returned in term- + info notation, not the older and not-quite-compatible termcap notation. + This does not cause problems if all you do with it is call tgoto or + tparm, which both expand terminfo-style strings as terminfo does. (If + ncurses is configured to support termcap, tgoto checks whether the + string is terminfo-style by looking for "%p" parameters or "<...>" + delays, and invokes a termcap-style parser if the string appears not to + use terminfo syntax.) + + Because terminfo's syntax for padding in string capabilities differs from termcap's, users can be surprised. - o tputs("50") in a terminfo system transmits "50" rather than busy- + o tputs("50") in a terminfo system transmits "50" rather than busy- waiting for 50 milliseconds. - o However, if ncurses is configured to support termcap, it may also + o However, if ncurses is configured to support termcap, it may also have been configured to support BSD-style padding. - In that case, tputs inspects strings passed to it, looking for + In that case, tputs inspects strings passed to it, looking for digits at the beginning of the string. - tputs("50") in a termcap system may busy-wait for 50 milliseconds + tputs("50") in a termcap system may busy-wait for 50 milliseconds rather than transmitting "50". - termcap has nothing analogous to terminfo's sgr string. One - consequence is that termcap applications assume that "me" (equivalent - to terminfo's sgr0 capability) does not reset the alternate character - set. ncurses checks for, and modifies the data shared with, the - termcap interface to accommodate the latter's limitation in this - respect. + termcap has nothing analogous to terminfo's set_attributes (sgr) + capability. One consequence is that termcap applications assume that + "me" (equivalent to terminfo's exit_attribute_mode (sgr0) capability) + does not reset the alternate character set. ncurses checks for, and + modifies the data shared with, the termcap interface to accommodate the + latter's limitation in this respect.
SEE ALSO
@@ -397,7 +396,7 @@ -ncurses 6.4 2023-12-17 curs_termcap(3x) +ncurses 6.4 2023-12-23 curs_termcap(3x)

diff --git a/doc/html/man/curs_terminfo.3x.html b/doc/html/man/curs_terminfo.3x.html index eb8b33e4..a800bfbe 100644 --- a/doc/html/man/curs_terminfo.3x.html +++ b/doc/html/man/curs_terminfo.3x.html @@ -28,7 +28,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_terminfo.3x,v 1.123 2023/12/16 21:11:53 tom Exp @ + * @Id: curs_terminfo.3x,v 1.124 2023/12/23 17:34:39 tom Exp @ * *************************************************************************** * *************************************************************************** * *************************************************************************** @@ -37,6 +37,8 @@ * *************************************************************************** * *************************************************************************** * *************************************************************************** + * See X/Open Curses Issue 4, Version 2, pp. 227-234. + * See X/Open Curses Issue 7, pp. 311-318. * *************************************************************************** * *************************************************************************** * *************************************************************************** @@ -46,12 +48,12 @@ -curs_terminfo 3x 2023-12-16 ncurses 6.4 Library calls +curs_terminfo 3x 2023-12-23 ncurses 6.4 Library calls -
curs_terminfo 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_terminfo 3x 2023-12-23 ncurses 6.4 Library calls

curs_terminfo(3x) Library calls curs_terminfo(3x) @@ -110,6 +112,9 @@ char *tiparm_s(int expected, int mask, const char *str, ...); int tiscan_s(int *expected, int *mask, const char *str); + /* deprecated */ + int setterm(const char *term); +
DESCRIPTION
These low-level routines must be called by programs that have to deal @@ -220,7 +225,7 @@
The Terminal State
The setupterm routine stores its information about the terminal in a - TERMINAL structure pointed to by the global variable cur_term. If it + TERMINAL structure pointed to by the global variable cur_term. If it detects an error, or decides that the terminal is unsuitable (hardcopy or generic), it discards this information, making it not available to applications. @@ -306,7 +311,7 @@ o affcnt is the number of lines affected, or 1 if not applicable. - o putc is a putchar-like routine to which the characters are passed, + o putc is a putchar-like function to which the characters are passed, one at a time. If tputs processes a time-delay, it uses the delay_output(3x) @@ -318,11 +323,11 @@ The vidputs routine displays the string on the terminal in the video attribute mode attrs, which is any combination of the attributes listed - in curses(3x). The characters are passed to the putchar-like routine + in curses(3x). The characters are passed to the putchar-like function putc. The vidattr routine is like the vidputs routine, except that it outputs - through putchar. + through putchar. The vid_attr and vid_puts routines correspond to vidattr and vidputs, respectively. They use a set of arguments for representing the video @@ -413,7 +418,7 @@ o to improve performance, ncurses 6.3 caches the result of analyzing terminfo strings for their parameter types. That is stored as a - binary tree referenced from the TERMINAL structure. + binary tree referenced from the TERMINAL structure. The higher-level initscr and newterm functions use setupterm. Normally they do not free this memory, but it is possible to do that using the @@ -456,35 +461,51 @@
NOTES
- X/Open notes that vidattr and vidputs may be macros. + According to X/Open Curses, any of the enhanced curses functions may be + implemented as macros. The term "enhanced" refers to features not + found in SVr4 curses. + + ncurses uses macros + + o for functions which return values via their parameters, + + o to support obsolete features, + + o to reuse functions, e.g., those that move the cursor before another + operation, and + + o a few special cases. + + The vid_puts function in ncurses is a special case. It was originally + implemented based on a draft of X/Open Curses, as a macro, before other + parts of the ncurses wide-character API were developed.
EXTENSIONS
- The functions marked as extensions were designed for ncurses(3x), and - are not found in SVr4 curses, 4.4BSD curses, or any other previous - version of curses. + The functions marked as extensions were designed for ncurses(3x), and + are not found in SVr4 curses, 4.4BSD curses, or any other previous + curses implementation.
PORTABILITY
- The function setterm is not described by X/Open and must be considered - non-portable. All other functions are as described by X/Open. + setterm is not described by X/Open and must be considered non-portable. + All other functions are as described by X/Open.
Compatibility Macros
- This implementation provides a few macros for compatibility with - systems before SVr4 (see HISTORY). Those include crmode, fixterm, - gettmode, nocrmode, resetterm, saveterm, and setterm. + This implementation provides a few macros for compatibility with + systems before SVr4 (see section "HISTORY" below). They include + Bcrmode, Bfixterm, Bgettmode, Bnocrmode, Bresetterm, Bsaveterm, and + Bsetterm. - In SVr4, those are found in <curses.h>, but except for setterm, are + In SVr4, these are found in curses.h, but except for setterm, are likewise macros. The one function, setterm, is mentioned in the manual - page. The manual page notes that the setterm routine was replaced by - setupterm, stating that the call - - setupterm(term, 1, (int *)0) - - provides the same functionality as setterm(term), and is not - recommended for new programs. This implementation provides each of - those symbols as macros for BSD compatibility. + page. It further notes that setterm was replaced by setupterm, stating + that the call + setupterm(term, 1, (int *)0) + provides the same functionality as setterm(term), discouraging the + latter for new programs. ncurses implements each of these symbols as + macros for BSD curses compatibility.
Legacy Data
@@ -599,7 +620,7 @@ X/Open notes that after calling mvcur, the curses state may not match the actual terminal state, and that an application should touch and refresh the window before resuming normal curses calls. Both ncurses - and System V Release 4 curses implement mvcur using the SCREEN data + and System V Release 4 curses implement mvcur using the SCREEN data allocated in either initscr or newterm. So though it is documented as a terminfo function, mvcur is really a curses function which is not well specified. @@ -618,9 +639,8 @@ fixterm restore tty to "in curses" state gettmode establish current tty modes mvcur low level cursor motion - putp utility function that uses tputs to send characters via - putchar. + putchar. resetterm set tty modes to "out of curses" state resetty reset tty flags to stored value saveterm save current modes as "in curses" state @@ -629,7 +649,7 @@ setupterm establish terminal with given type tparm instantiate a string expression with parameters tputs apply padding information to a string - vidattr like vidputs, but outputs through putchar + vidattr like vidputs, but outputs through putchar vidputs output a string to put terminal in a specified video attribute mode @@ -646,7 +666,7 @@ tputs apply padding to capability, calling a function to put characters - Early terminfo programs obtained capability values from the TERMINAL + Early terminfo programs obtained capability values from the TERMINAL structure initialized by setupterm. SVr3 extended terminfo by adding functions to retrieve capability @@ -654,6 +674,7 @@ Function Description ------------------------------------------------------------------------ + tigetflag get boolean entry for given id tigetnum get numeric entry for given id tigetstr get string entry for given id @@ -680,7 +701,7 @@ descriptions, e.g., set_curterm. Some of that was incremental improvements to the SVr2 library: - o The TERMINAL type definition was introduced in SVr3.01, for the + o The TERMINAL type definition was introduced in SVr3.01, for the term structure provided in SVr2. o The various global variables such as boolnames were mentioned in @@ -701,7 +722,7 @@ -ncurses 6.4 2023-12-16 curs_terminfo(3x) +ncurses 6.4 2023-12-23 curs_terminfo(3x)

diff --git a/doc/html/man/curs_threads.3x.html b/doc/html/man/curs_threads.3x.html index b7e6078e..7dad4fea 100644 --- a/doc/html/man/curs_threads.3x.html +++ b/doc/html/man/curs_threads.3x.html @@ -28,7 +28,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_threads.3x,v 1.50 2023/12/16 20:32:22 tom Exp @ + * @Id: curs_threads.3x,v 1.51 2023/12/23 16:22:25 tom Exp @ * *************************************************************************** * *************************************************************************** --> @@ -37,12 +37,12 @@ -curs_threads 3x 2023-12-16 ncurses 6.4 Library calls +curs_threads 3x 2023-12-23 ncurses 6.4 Library calls -
curs_threads 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_threads 3x 2023-12-23 ncurses 6.4 Library calls

curs_threads(3x) Library calls curs_threads(3x) @@ -619,7 +619,7 @@ -ncurses 6.4 2023-12-16 curs_threads(3x) +ncurses 6.4 2023-12-23 curs_threads(3x)

diff --git a/doc/html/man/curs_trace.3x.html b/doc/html/man/curs_trace.3x.html index 295fa521..5654fbe9 100644 --- a/doc/html/man/curs_trace.3x.html +++ b/doc/html/man/curs_trace.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_trace.3x,v 1.41 2023/12/16 20:50:14 tom Exp @ + * @Id: curs_trace.3x,v 1.42 2023/12/23 16:08:25 tom Exp @ --> -curs_trace 3x 2023-12-16 ncurses 6.4 Library calls +curs_trace 3x 2023-12-23 ncurses 6.4 Library calls -
curs_trace 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_trace 3x 2023-12-23 ncurses 6.4 Library calls

curs_trace(3x) Library calls curs_trace(3x) @@ -259,7 +259,7 @@ -ncurses 6.4 2023-12-16 curs_trace(3x) +ncurses 6.4 2023-12-23 curs_trace(3x)

diff --git a/doc/html/man/curs_util.3x.html b/doc/html/man/curs_util.3x.html index ce1aec47..af4eeda3 100644 --- a/doc/html/man/curs_util.3x.html +++ b/doc/html/man/curs_util.3x.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_util.3x,v 1.91 2023/12/16 20:32:22 tom Exp @ + * @Id: curs_util.3x,v 1.92 2023/12/23 16:24:15 tom Exp @ --> -curs_util 3x 2023-12-16 ncurses 6.4 Library calls +curs_util 3x 2023-12-23 ncurses 6.4 Library calls -
curs_util 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_util 3x 2023-12-23 ncurses 6.4 Library calls

curs_util(3x) Library calls curs_util(3x) @@ -212,7 +212,7 @@ that data. It returns a pointer to the new window. There are a few caveats: - o the data written is a copy of the WINDOW structure, and its + o the data written is a copy of the WINDOW structure, and its associated character cells. The format differs between the wide- character (ncursesw) and non-wide (ncurses) libraries. You can transfer data between the two, however. @@ -317,7 +317,7 @@ 1988) incorporated into SVr4. Oddly, there are no such functions in the 4.3BSD curses sources. - o Most implementations simply dump the binary WINDOW structure to the + o Most implementations simply dump the binary WINDOW structure to the file. These include SVr4 curses, NetBSD and PDCurses, as well as older ncurses versions. This implementation (as well as the X/Open variant of Solaris curses, dated 1995) uses textual dumps. @@ -391,7 +391,7 @@ -ncurses 6.4 2023-12-16 curs_util(3x) +ncurses 6.4 2023-12-23 curs_util(3x)

diff --git a/doc/html/man/curs_variables.3x.html b/doc/html/man/curs_variables.3x.html index ed617925..616d96e0 100644 --- a/doc/html/man/curs_variables.3x.html +++ b/doc/html/man/curs_variables.3x.html @@ -27,19 +27,20 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_variables.3x,v 1.35 2023/12/16 21:05:52 tom Exp @ + * @Id: curs_variables.3x,v 1.40 2023/12/23 23:10:13 tom Exp @ + * SVID 4, Volume 3, p. 408 --> -curs_variables 3x 2023-12-16 ncurses 6.4 Library calls +curs_variables 3x 2023-12-23 ncurses 6.4 Library calls -
curs_variables 3x 2023-12-16 ncurses 6.4 Library calls
+
curs_variables 3x 2023-12-23 ncurses 6.4 Library calls

curs_variables(3x) Library calls curs_variables(3x) @@ -47,9 +48,9 @@
NAME
- bool, chtype, cchar_t, attr_t, WINDOW, TRUE, FALSE, ERR, OK, COLORS, - COLOR_PAIRS, COLS, ESCDELAY, LINES, TABSIZE, curscr, newscr, stdscr - - curses data types, constants, and global variables + bool, chtype, cchar_t, attr_t, SCREEN, WINDOW, TRUE, FALSE, ERR, OK, + curscr, newscr, stdscr, COLORS, COLOR_PAIRS, COLS, LINES, ESCDELAY, + TABSIZE - curses data types, constants, and global variables
SYNOPSIS
@@ -60,6 +61,7 @@ typedef /* ... */ chtype; typedef /* ... */ cchar_t; typedef /* ... */ attr_t; + typedef /* ... */ SCREEN; typedef /* ... */ WINDOW; /* constants */ @@ -70,12 +72,13 @@ const /* ... */ OK; /* variables */ - int COLOR_PAIRS; int COLORS; + int COLOR_PAIRS; int COLS; int LINES; WINDOW * curscr; WINDOW * stdscr; + /* extensions */ int ESCDELAY; int TABSIZE; @@ -93,11 +96,11 @@ library. -
bool, TRUE, FALSE
- X/Open Issue 4 curses (1996) preceded the ISO C99 and ISO C++98 - standards, each of which also defined a Boolean data type. The curses - library requires an integral type bool and constants TRUE and FALSE to - store its two possible values. +
CONSTANTS
+ +
TRUE, FALSE
+ The curses library defines TRUE and FALSE to represent the values of + the Boolean data type.
ERR, OK
@@ -105,109 +108,113 @@ values indicating failure and success, respectively. +
PREDEFINED TYPES
+ +
bool
+ X/Open Issue 4 curses (1996) preceded the ISO C99 and ISO C++98 + standards, each of which also defined a Boolean data type. The curses + library requires an integral type bool. + + ncurses' configure script attempts to discover the data type used by + the system's C and C++ compilers, to reuse for the curses bool. + +
chtype
- The chtype integral type combines a ("narrow", 8-bit) character with - attributes encoding the character's rendition, such as the styling of + The chtype integral type combines a ("narrow", 8-bit) character with + attributes encoding the character's rendition, such as the styling of its typeface and/or foreground and background colors. See, for example, addch(3x), attron(3x), and inch(3x).
cchar_t, attr_t
- chtype is too small for the standard C library's wide-character type, - wchar_t. cchar_t is a type that can accommodate an attr_t and enough - wide characters to store what Unicode terms a grapheme cluster (a - "user-perceived character" [UAX #29], which may nevertheless require - several character encoding units to represent). attr_t is an integral - type storing "wide" attributes that apply to cchar_ts. See, for + chtype is too small for the standard C library's wide-character type, + wchar_t. cchar_t is a type that can accommodate an attr_t and enough + wide characters to store what Unicode terms a grapheme cluster (a + "user-perceived character" [UAX #29], which may nevertheless require + several character encoding units to represent). attr_t is an integral + type storing "wide" attributes that apply to cchar_ts. See, for example, add_wch(3x), attr_on(3x), and in_wch(3x). -
COLOR_PAIRS
- Once curses is initialized, COLOR_PAIRS contains the number of color - pairs supported by the terminal. Often, its value is the product - COLORS x COLORS, but this is not always true. +
SCREEN
+ curses manages a terminal device with this structure type; see + initscr(3x). + - o A few terminals use HLS colors, ignoring this rule; and +
WINDOW
+ curses represents rectangular portions of the terminal screen with the + WINDOW structure type; see subsection "Overview" of ncurses(3x). - o terminals supporting a large number of colors are limited by the - number of color pairs that a signed short value can represent. + +
VARIABLES
+ +
curscr, stdscr, newscr
+ The library records updates to the terminal screen in a window named + curscr. This object is referred to as the "physical screen" in + curs_refresh(3x) and curs_outopts(3x). + + ncurses collects pending updates to the terminal screen in a window + named newscr. This object is referred to as the "virtual screen" in + the curs_kernel(3x), curs_refresh(3x), and curs_outopts(3x). When the + screen is refreshed, curses determines a minimal set of updates using + the terminal's capabilities to make curscr look like newscr. + + Once curses is initialized, it creates a window named stdscr. It is + the same size as the terminal screen and is the default window used by + routines that do not take a parameter identifying one. Many curses + functions use this window.
COLORS
- Once curses is initialized, COLORS contains the number of colors - supported by the terminal. + Once curses is initialized, COLORS contains the number of colors + supported by the terminal; see curs_color(3x). -
COLS
- Once curses is initialized, COLS contains the screen's width in - character cells; that is, the number of columns. +
COLOR_PAIRS
+ Once curses is initialized, COLOR_PAIRS contains the number of color + pairs supported by the terminal; see curs_color(3x). + + +
COLS, LINES
+ Once curses is initialized, COLS and LINES contain the screen's width + and height in character cells, respectively; that is, the number of + columns and lines.
ESCDELAY
For curses to distinguish an escape character corresponding to a user's - press of an "Escape" key on the input device from one included in a + press of an "Escape" key on the input device from one included in a control sequence used by a cursor movement or function key, the library - waits to see if another key event occurs after the escape character. + waits to see if another key event occurs after the escape character. ESCDELAY stores this interval in milliseconds. -
LINES
- Once curses is initialized, LINES contains the screen's height in - character cells; that is, the number of lines. - -
TABSIZE
The curses library converts a tab character to this number of spaces as it adds a tab to a window; see curs_addch(3x). -
curscr
- curses records updates to the terminal screen in a WINDOW structure - named curscr. - - This object is referred to as the "physical screen" in curs_refresh(3x) - and curs_outopts(3x). - - -
newscr
- ncurses collects pending updates to the terminal screen in a WINDOW - structure named newscr. - - This object is referred to as the "virtual screen" in the - curs_kernel(3x), curs_refresh(3x), and curs_outopts(3x). When the - screen is refreshed, curses determines a minimal set of updates using - the terminal's capabilities to make curscr look like newscr. - - -
stdscr
- Once curses is initialized, it creates a WINDOW structure named stdscr. - It is the same size as the terminal screen and is the default window - used by routines that do not take a parameter identifying one. Many - curses functions use this window. - -
NOTES
Either initscr(3x) or newterm(3x) initializes curses. - If ncurses is configured to provide separate curses and terminfo + If ncurses is configured to provide separate curses and terminfo libraries, most of these variables reside in the curses library.
PORTABILITY
- The X/Open Curses standard documents all of the foregoing types and + The X/Open Curses standard documents all of the foregoing types and symbols except for newscr, TABSIZE, and ESCDELAY. - X/Open Curses describes curscr only as "an internal data structure"; - SVID gave more details, noting its use "for certain low-level - operations like clearing and redrawing a screen containing garbage". + X/Open Curses describes curscr only as "an internal data structure"; + SVr4 gave more details, noting its use "for certain low-level + operations like clearing and redrawing a screen containing garbage". Neither specified its interaction with the rest of the interface beyond use as an argument to clearok(3x) and wrefresh(3x). - newscr is a feature of SVr4 curses. When refreshing the screen, this - window is used as a working area for combining the standard screen - stdscr with any other windows which the application may have created - with newwin(3x). When the updated newscr is complete, curses updates - curscr to match newscr. + newscr is a feature of SVr4 curses. When refreshing the screen, it is + used as a working area for combining the standard window stdscr with + any others the application may have created with newwin(3x). When the + update of newscr is complete, curses modifies curscr to match newscr. TABSIZE is a feature of SVr4 curses. @@ -248,35 +255,44 @@
SEE ALSO
- curses(3x), curs_opaque(3x), curs_terminfo(3x), curs_threads(3x), - term_variables(3x), terminfo(5) + curses(3x), curs_color(3x), curs_opaque(3x), curs_terminfo(3x), + curs_threads(3x), term_variables(3x), terminfo(5) [UAX #29] "Unicode Standard Annex #29: Unicode Text Segmentation"; <https://unicode.org/reports/tr29/> -ncurses 6.4 2023-12-16 curs_variables(3x) +ncurses 6.4 2023-12-23 curs_variables(3x)

NAME

SYNOPSIS
-
DESCRIPTION +
DESCRIPTION
+
CONSTANTS
-
bool, TRUE, FALSE
+
TRUE, FALSE

ERR, OK
+
+
+
PREDEFINED TYPES +
+
bool

chtype

cchar_t, attr_t
-
COLOR_PAIRS
+
SCREEN
+
WINDOW
+
+
+
VARIABLES +
+
curscr, stdscr, newscr

COLORS
-
COLS
+
COLOR_PAIRS
+
COLS, LINES

ESCDELAY
-
LINES

TABSIZE
-
curscr
-
newscr
-
stdscr

NOTES
diff --git a/doc/html/man/form.3x.html b/doc/html/man/form.3x.html index 5b2722ce..c24979f1 100644 --- a/doc/html/man/form.3x.html +++ b/doc/html/man/form.3x.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form.3x,v 1.51 2023/12/16 20:32:22 tom Exp @ + * @Id: form.3x,v 1.52 2023/12/23 16:08:25 tom Exp @ --> -form 3x 2023-12-16 ncurses 6.4 Library calls +form 3x 2023-12-23 ncurses 6.4 Library calls -
form 3x 2023-12-16 ncurses 6.4 Library calls
+
form 3x 2023-12-23 ncurses 6.4 Library calls

form(3x) Library calls form(3x) @@ -245,7 +245,7 @@ -ncurses 6.4 2023-12-16 form(3x) +ncurses 6.4 2023-12-23 form(3x)

diff --git a/doc/html/man/form_driver.3x.html b/doc/html/man/form_driver.3x.html index 1a59c12c..fa6d88ac 100644 --- a/doc/html/man/form_driver.3x.html +++ b/doc/html/man/form_driver.3x.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_driver.3x,v 1.53 2023/11/25 13:58:47 tom Exp @ + * @Id: form_driver.3x,v 1.54 2023/12/23 16:08:25 tom Exp @ --> -form_driver 3x 2023-11-25 ncurses 6.4 Library calls +form_driver 3x 2023-12-23 ncurses 6.4 Library calls -
form_driver 3x 2023-11-25 ncurses 6.4 Library calls
+
form_driver 3x 2023-12-23 ncurses 6.4 Library calls

form_driver(3x) Library calls form_driver(3x) @@ -84,7 +84,7 @@ character or a request. -
Form-driver requests
+
Form Driver Requests
The form driver requests are as follows: Name Description @@ -154,7 +154,7 @@ forms requests listed above, that request is executed. -
Field validation
+
Field Validation
The form library makes updates to the window associated with form fields rather than directly to the field buffers. @@ -181,7 +181,7 @@ data from the window associated with the field to the field buffer. -
Mouse handling
+
Mouse Handling
If the second argument is the KEY_MOUSE special key, the associated mouse event is translated into one of the above pre-defined requests. Currently only clicks in the user window (e.g., inside the form display @@ -221,7 +221,7 @@ translated into a form request an E_REQUEST_DENIED is returned. -
Application-defined commands
+
Application-defined Commands
If the second argument is neither printable nor one of the above pre- defined form requests, the driver assumes it is an application-specific command and returns E_UNKNOWN_COMMAND. Application-defined commands @@ -275,7 +275,7 @@ -ncurses 6.4 2023-11-25 form_driver(3x) +ncurses 6.4 2023-12-23 form_driver(3x)

@@ -285,10 +285,10 @@ ncurses 6.4 2023-11-25 form_driver
form_driver_w
-
Form-driver requests
-
Field validation
-
Mouse handling
-
Application-defined commands
+
Form Driver Requests
+
Field Validation
+
Mouse Handling
+
Application-defined Commands

RETURN VALUE
diff --git a/doc/html/man/infocmp.1m.html b/doc/html/man/infocmp.1m.html index b3ba683a..8919c674 100644 --- a/doc/html/man/infocmp.1m.html +++ b/doc/html/man/infocmp.1m.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: infocmp.1m,v 1.102 2023/12/16 20:32:22 tom Exp @ + * @Id: infocmp.1m,v 1.103 2023/12/23 16:08:25 tom Exp @ --> -infocmp 1m 2023-12-16 ncurses 6.4 User commands +infocmp 1m 2023-12-23 ncurses 6.4 User commands -
infocmp 1m 2023-12-16 ncurses 6.4 User commands
+
infocmp 1m 2023-12-23 ncurses 6.4 User commands

infocmp(1m) User commands infocmp(1m) @@ -531,7 +531,7 @@ -ncurses 6.4 2023-12-16 infocmp(1m) +ncurses 6.4 2023-12-23 infocmp(1m)

diff --git a/doc/html/man/menu.3x.html b/doc/html/man/menu.3x.html index b3f14cee..798d4c71 100644 --- a/doc/html/man/menu.3x.html +++ b/doc/html/man/menu.3x.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu.3x,v 1.42 2023/12/16 20:32:22 tom Exp @ + * @Id: menu.3x,v 1.43 2023/12/23 16:08:25 tom Exp @ --> -menu 3x 2023-12-16 ncurses 6.4 Library calls +menu 3x 2023-12-23 ncurses 6.4 Library calls -
menu 3x 2023-12-16 ncurses 6.4 Library calls
+
menu 3x 2023-12-23 ncurses 6.4 Library calls

menu(3x) Library calls menu(3x) @@ -220,7 +220,7 @@ -ncurses 6.4 2023-12-16 menu(3x) +ncurses 6.4 2023-12-23 menu(3x)

diff --git a/doc/html/man/menu_driver.3x.html b/doc/html/man/menu_driver.3x.html index 57e11543..3a23b6a0 100644 --- a/doc/html/man/menu_driver.3x.html +++ b/doc/html/man/menu_driver.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_driver.3x,v 1.44 2023/12/16 20:32:22 tom Exp @ + * @Id: menu_driver.3x,v 1.45 2023/12/23 16:08:25 tom Exp @ --> -menu_driver 3x 2023-12-16 ncurses 6.4 Library calls +menu_driver 3x 2023-12-23 ncurses 6.4 Library calls -
menu_driver 3x 2023-12-16 ncurses 6.4 Library calls
+
menu_driver 3x 2023-12-23 ncurses 6.4 Library calls

menu_driver(3x) Library calls menu_driver(3x) @@ -133,7 +133,7 @@ corresponding action is performed. -
MOUSE HANDLING
+
Mouse Handling
If the second argument is the KEY_MOUSE special key, the associated mouse event is translated into one of the above pre-defined requests. Currently only clicks in the user window (e.g., inside the menu display @@ -172,7 +172,7 @@ translated into a menu request an E_REQUEST_DENIED is returned. -
APPLICATION-DEFINED COMMANDS
+
Application-defined Commands
If the second argument is neither printable nor one of the above pre- defined menu requests or KEY_MOUSE, the drive assumes it is an application-specific command and returns E_UNKNOWN_COMMAND. @@ -223,7 +223,7 @@ -ncurses 6.4 2023-12-16 menu_driver(3x) +ncurses 6.4 2023-12-23 menu_driver(3x)

@@ -231,8 +231,8 @@ ncurses 6.4 2023-12-16 SYNOPSIS
DESCRIPTION
-
MOUSE HANDLING
-
APPLICATION-DEFINED COMMANDS
+
Mouse Handling
+
Application-defined Commands

RETURN VALUE
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html index 5054afdc..714e302c 100644 --- a/doc/html/man/ncurses.3x.html +++ b/doc/html/man/ncurses.3x.html @@ -28,7 +28,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: ncurses.3x,v 1.187 2023/12/17 23:44:14 tom Exp @ + * @Id: ncurses.3x,v 1.189 2023/12/23 16:32:37 tom Exp @ * X/Open Curses Issue 7 assumes some optimization will be done, but * does not mandate it in any way. --> @@ -37,12 +37,12 @@ -ncurses 3x 2023-12-17 ncurses 6.4 Library calls +ncurses 3x 2023-12-23 ncurses 6.4 Library calls -
ncurses 3x 2023-12-17 ncurses 6.4 Library calls
+
ncurses 3x 2023-12-23 ncurses 6.4 Library calls

ncurses(3x) Library calls ncurses(3x) @@ -62,7 +62,7 @@ method of updating character screens with reasonable optimization. This implementation is "new curses" (ncurses) and is the approved replacement for 4.4BSD classic curses, which has been discontinued. - This describes ncurses version 6.4 (patch 20231217). + This describes ncurses version 6.4 (patch 20231223). The ncurses library emulates the curses library of System V Release 4 Unix ("SVr4"), and XPG4 (X/Open Portability Guide) curses (also known @@ -99,8 +99,8 @@ -lncurses_g. (Your system integrator may also have installed these libraries under the names -lcurses and -lcurses_g.) The ncurses_g library generates trace logs (in a file called "trace" in the current - directory) that describe curses actions. See also the section on - ALTERNATE CONFIGURATIONS. + directory) that describe curses actions. See section "ALTERNATE + CONFIGURATIONS" below. The ncurses package supports: overall screen, window and pad manipulation; output to windows and pads; reading terminal input; @@ -192,12 +192,12 @@ modes as underlined, in reverse video, or in color on terminals that support such display enhancements. See curs_attr(3x). - curses predefines symbols for a small set of line graphics characters, - corresponding to the VT100 line drawing set. See waddch(3x) and - wadd_wch(3x). + curses predefines constants for a small set of line-drawing and other + graphics corresponding to the DEC Alternate Character Set (ACS), a + feature of VT100 and other terminals. See waddch(3x) and wadd_wch(3x). curses is implemented using the operating system's terminal driver; - keystroke events are not received as scan codes but as byte sequences. + keystroke events are received not as scan codes but as byte sequences. Graphical keycaps (alphanumeric and punctuation keys, and the space) appear as-is. Everything else, including the tab, enter/return, keypad, arrow, and function keys, appears as a control character or a @@ -292,7 +292,7 @@ wint_t can store a wchar_t or the constant WEOF, analogously to the int-sized character manipulation - functions of ISO C and their constant EOF. + functions of ISO C and its constant EOF. The wide library provides additional functions that complement those in the non-wide library where the size of @@ -1002,7 +1002,7 @@ The reason for the change was to make the behavior for interrupts and other signals more robust. One drawback is that certain - nonconventional programs would mix ordinary stdio calls with ncurses + nonconventional programs would mix ordinary stdio(3) calls with ncurses calls and (usually) work. This is no longer possible since ncurses is not using the buffered standard output but its own output (to the same file descriptor). As a special case, the low-level calls such as putp @@ -1178,10 +1178,10 @@
ALTERNATE CONFIGURATIONS
- Several different configurations are possible, depending on the - configure script options used when building ncurses. There are a few - main options whose effects are visible to the applications developer - using ncurses: + Many different ncurses configurations are possible, determined by the + options given to the configure script when building the library. Run + the script with the --help option to peruse them all. A few are of + particular significance to the application developer employing ncurses. --disable-overwrite The standard include for ncurses is as noted in SYNOPSIS: @@ -1356,12 +1356,12 @@ sections of the library man pages. -
Error checking
+
Error Checking
In many cases, X/Open Curses is vague about error conditions, omitting some of the SVr4 documentation. Unlike other implementations, this one checks parameters such as - pointers to WINDOW structures to ensure they are not null. The main + pointers to WINDOW structures to ensure they are not null. The main reason for providing this behavior is to guard against programmer error. The standard interface does not provide a way for the library to tell an application which of several possible errors were detected. @@ -1369,7 +1369,7 @@ portability of curses applications. -
Extensions versus portability
+
Extensions Versus Portability
Most of the extensions provided by ncurses have not been standardized. Some have been incorporated into other implementations, such as PDCurses or NetBSD curses. Here are a few to consider: @@ -1391,7 +1391,7 @@ o The routine wresize is not part of XPG4, nor is it present in SVr4. See the wresize(3x) manual page for details. - o The WINDOW structure's internal details can be hidden from + o The WINDOW structure's internal details can be hidden from application programs. See curs_opaque(3x) for the discussion of is_scrollok, etc. @@ -1404,7 +1404,7 @@ See curs_sp_funcs(3x) for details. -
Padding differences
+
Padding Differences
In historic curses versions, delays embedded in the capabilities cr, ind, cub1, ff and tab activated corresponding delay bits in the Unix tty driver. In this implementation, all padding is done by sending NUL @@ -1413,7 +1413,7 @@ portability correspondingly. -
Header files
+
Header Files
The header file curses.h itself includes the header files stdio.h and unctrl.h. @@ -1514,7 +1514,7 @@ -ncurses 6.4 2023-12-17 ncurses(3x) +ncurses 6.4 2023-12-23 ncurses(3x)

@@ -1562,10 +1562,10 @@ ncurses 6.4 2023-12-17 EXTENSIONS
PORTABILITY
-
Error checking
-
Extensions versus portability
-
Padding differences
-
Header files
+
Error Checking
+
Extensions Versus Portability
+
Padding Differences
+
Header Files

AUTHORS
diff --git a/doc/html/man/ncursesw6-config.1.html b/doc/html/man/ncursesw6-config.1.html index 101b95ac..f0be1977 100644 --- a/doc/html/man/ncursesw6-config.1.html +++ b/doc/html/man/ncursesw6-config.1.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: MKncu_config.in,v 1.20 2023/12/16 21:43:05 tom Exp @ + * @Id: MKncu_config.in,v 1.22 2023/12/23 23:44:26 tom Exp @ --> -ncursesw6-config 1 2023-12-16 ncurses 6.4 User commands +ncursesw6-config 1 2023-12-23 ncurses 6.4 User commands -
ncursesw6-config 1 2023-12-16 ncurses 6.4 User commands
+
ncursesw6-config 1 2023-12-23 ncurses 6.4 User commands

ncursesw6-config(1) User commands ncursesw6-config(1) @@ -73,9 +73,6 @@ --libs reports the libraries needed to link with ncurses. - --version reports the release and patch date information of - ncurses and exits successfully. - --abi-version reports the ABI version of ncurses. --mouse-version reports the mouse-interface version of ncurses. @@ -84,25 +81,30 @@ --datadir reports the directory containing ncurses data. - --includedir reports the directory containing ncurses header + --includedir reports the directory containing ncurses header files. --libdir reports the directory containing ncurses libraries. --mandir reports the directory containing ncurses man pages. - --terminfo reports the TERMINFO terminfo database path, for + --terminfo reports the TERMINFO terminfo database path, for example /usr/share/terminfo. - --terminfo-dirs reports the TERMINFO_DIRS supplemental search path + --terminfo-dirs reports the TERMINFO_DIRS supplemental search path for the terminfo database, for example /usr/share/terminfo. --termpath reports the TERMPATH supplemental search path for the - termcap database, if support for termcap is + termcap database, if support for termcap is configured. - --help issues a usage message and exits successfully. + The following options cause all others to be ignored. + + --help issues a usage message and exits successfully. + + --version issues the release and patch date information of ncurses and + exits successfully.
SEE ALSO
@@ -110,7 +112,7 @@ -ncurses 6.4 2023-12-16 ncursesw6-config(1) +ncurses 6.4 2023-12-23 ncursesw6-config(1)

diff --git a/doc/html/man/panel.3x.html b/doc/html/man/panel.3x.html index 751fe6b8..a6720a40 100644 --- a/doc/html/man/panel.3x.html +++ b/doc/html/man/panel.3x.html @@ -27,7 +27,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: panel.3x,v 1.60 2023/12/16 21:24:43 tom Exp @ + * @Id: panel.3x,v 1.61 2023/12/23 16:22:25 tom Exp @ * --------- * --------- * --------- @@ -51,12 +51,12 @@ -panel 3x 2023-12-16 ncurses 6.4 Library calls +panel 3x 2023-12-23 ncurses 6.4 Library calls -
panel 3x 2023-12-16 ncurses 6.4 Library calls
+
panel 3x 2023-12-23 ncurses 6.4 Library calls

panel(3x) Library calls panel(3x) @@ -283,7 +283,7 @@ -ncurses 6.4 2023-12-16 panel(3x) +ncurses 6.4 2023-12-23 panel(3x)

diff --git a/doc/html/man/scr_dump.5.html b/doc/html/man/scr_dump.5.html index ce5e2b25..53b9508a 100644 --- a/doc/html/man/scr_dump.5.html +++ b/doc/html/man/scr_dump.5.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: scr_dump.5,v 1.40 2023/12/16 21:07:24 tom Exp @ + * @Id: scr_dump.5,v 1.41 2023/12/23 16:27:25 tom Exp @ --> -scr_dump 5 2023-12-16 ncurses 6.4 File formats +scr_dump 5 2023-12-23 ncurses 6.4 File formats -
scr_dump 5 2023-12-16 ncurses 6.4 File formats
+
scr_dump 5 2023-12-23 ncurses 6.4 File formats

scr_dump(5) File formats scr_dump(5) @@ -110,18 +110,18 @@ o The ncurses6 getwin reads the legacy screen dumps from ncurses5. -
ncurses5 (legacy)
+
ncurses5 (Legacy)
The screen-dump feature was added to ncurses in June 1995. While there were fixes and improvements in succeeding years, the basic scheme was unchanged: - o The WINDOW structure was written in binary form. + o The WINDOW structure was written in binary form. - o The WINDOW structure refers to lines of data, which were written as - an array of binary data following the WINDOW. + o The WINDOW structure refers to lines of data, which were written as + an array of binary data following the WINDOW. o When getwin restored the window, it would keep track of offsets - into the array of line-data and adjust the WINDOW structure which + into the array of line-data and adjust the WINDOW structure which was read back into memory. This is similar to Unix System V, but does not write a "magic number" @@ -167,7 +167,7 @@
Unix System V
Unix System V curses identified the file format by writing a "magic - number" at the beginning of the dump. The WINDOW data and the lines of + number" at the beginning of the dump. The WINDOW data and the lines of text follow, all in binary form. The Solaris curses source has these definitions: @@ -193,7 +193,7 @@ \001\035 - After the magic number, the WINDOW structure and line-data are written + After the magic number, the WINDOW structure and line-data are written in binary format. While the magic number used by the Unix systems can be seen using od(1), none of the Unix systems documents the format used for screen-dumps. @@ -233,7 +233,7 @@
PDCurses
PDCurses added support for screen dumps in version 2.7 (2005). Like - Unix System V and ncurses5, it writes the WINDOW structure in binary, + Unix System V and ncurses5, it writes the WINDOW structure in binary, but begins the file with its three-byte identifier "PDC", followed by a one-byte version, e.g., @@ -250,9 +250,9 @@ o the curses shared library major and minor versions as the first two bytes (e.g., 7 and 1), - o followed by a binary dump of the WINDOW, + o followed by a binary dump of the WINDOW, - o some data for wide-characters referenced by the WINDOW structure, + o some data for wide-characters referenced by the WINDOW structure, and o finally, lines as done by other implementations. @@ -407,7 +407,7 @@ -ncurses 6.4 2023-12-16 scr_dump(5) +ncurses 6.4 2023-12-23 scr_dump(5)

@@ -416,7 +416,7 @@ ncurses 6.4 2023-12-16 DESCRIPTION

ncurses6
-
ncurses5 (legacy)
+
ncurses5 (Legacy)

PORTABILITY diff --git a/doc/html/man/tabs.1.html b/doc/html/man/tabs.1.html index 5d8039a4..e97dbb15 100644 --- a/doc/html/man/tabs.1.html +++ b/doc/html/man/tabs.1.html @@ -27,7 +27,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: tabs.1,v 1.51 2023/12/17 00:13:57 tom Exp @ + * @Id: tabs.1,v 1.52 2023/12/23 16:08:25 tom Exp @ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=PWB1/sys/source/s2/\ * tabs.c * https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/src/cmd/tabs.c @@ -41,12 +41,12 @@ -tabs 1 2023-12-16 ncurses 6.4 User commands +tabs 1 2023-12-23 ncurses 6.4 User commands -
tabs 1 2023-12-16 ncurses 6.4 User commands
+
tabs 1 2023-12-23 ncurses 6.4 User commands

tabs(1) User commands tabs(1) @@ -139,7 +139,7 @@ which is equivalent to the 1,6,11,16,21 example. -
Predefined Tab-Stops
+
Predefined Tab Stops
POSIX defines several predefined lists of tab stops. -a Assembler, IBM S/370, first format @@ -267,7 +267,7 @@ -ncurses 6.4 2023-12-16 tabs(1) +ncurses 6.4 2023-12-23 tabs(1)

@@ -279,7 +279,7 @@ ncurses 6.4 2023-12-16 <
General Options

Implicit Lists

Explicit Lists
-
Predefined Tab-Stops
+
Predefined Tab Stops

Margins

diff --git a/doc/html/man/term.5.html b/doc/html/man/term.5.html index 1f70937c..4509b95a 100644 --- a/doc/html/man/term.5.html +++ b/doc/html/man/term.5.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: term.5,v 1.68 2023/12/16 20:32:22 tom Exp @ + * @Id: term.5,v 1.69 2023/12/23 16:08:25 tom Exp @ --> -term 5 2023-12-16 ncurses 6.4 File formats +term 5 2023-12-23 ncurses 6.4 File formats -
term 5 2023-12-16 ncurses 6.4 File formats
+
term 5 2023-12-23 ncurses 6.4 File formats

term(5) File formats term(5) @@ -57,7 +57,7 @@
DESCRIPTION
-
STORAGE LOCATION
+
Storage Location
Compiled terminfo descriptions are placed under the directory /usr/share/terminfo. Two configurations are supported (when building the ncurses libraries): @@ -87,7 +87,7 @@ database otherwise. -
LEGACY STORAGE FORMAT
+
Legacy Storage Format
The format has been chosen so that it will be the same on all hardware. An 8 or more bit byte is assumed, but no assumptions about byte ordering or sign extension are made. @@ -186,7 +186,7 @@ uninterpreted form. -
EXTENDED STORAGE FORMAT
+
Extended Storage Format
The previous section describes the conventional terminfo binary format. With some minor variations of the offsets (see PORTABILITY), the same binary format is used in all modern Unix systems. Each system uses a @@ -234,7 +234,7 @@ names with members of a TERMTYPE structure. -
EXTENDED NUMBER FORMAT
+
Extended Number Format
On occasion, 16-bit signed integers are not large enough. With ncurses 6.1, a new format was introduced by making a few changes to the legacy format: @@ -270,7 +270,7 @@ the lists of boolean, number, and string capabilities. -
Binary format
+
Binary Format
X/Open Curses does not specify a format for the terminfo database. System V curses used a directory-tree of binary files, one per terminal description. @@ -292,7 +292,7 @@ different configuration options. -
Magic codes
+
Magic Codes
The magic number in a binary terminfo file is the first 16-bits (two bytes). Besides making it more reliable for the library to check that a file is terminfo, utilities such as file(1) also use that to tell @@ -301,15 +301,14 @@ uses 01036 as a continuation of that sequence, but with a different high-order byte to avoid confusion. - -
The TERMTYPE structure
+ The TERMTYPE Structure Direct access to the TERMTYPE structure is provided for legacy applications. Portable applications should use the tigetflag and related functions described in curs_terminfo(3x) for reading terminal capabilities. -
Mixed-case terminal names
+
Mixed-case Terminal Names
A small number of terminal descriptions use uppercase characters in their names. If the underlying filesystem ignores the difference between uppercase and lowercase, ncurses represents the "first @@ -400,7 +399,7 @@ -ncurses 6.4 2023-12-16 term(5) +ncurses 6.4 2023-12-23 term(5)

@@ -408,20 +407,19 @@ ncurses 6.4 2023-12-16 <
SYNOPSIS

DESCRIPTION
-
STORAGE LOCATION
-
LEGACY STORAGE FORMAT
-
EXTENDED STORAGE FORMAT
-
EXTENDED NUMBER FORMAT
+
Storage Location
+
Legacy Storage Format
+
Extended Storage Format
+
Extended Number Format

FILES

PORTABILITY

setupterm
-
Binary format
-
Magic codes
-
The TERMTYPE structure
-
Mixed-case terminal names
+
Binary Format
+
Magic Codes
+
Mixed-case Terminal Names

Limits

diff --git a/doc/html/man/term_variables.3x.html b/doc/html/man/term_variables.3x.html index 4373615f..e703ea38 100644 --- a/doc/html/man/term_variables.3x.html +++ b/doc/html/man/term_variables.3x.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: term_variables.3x,v 1.33 2023/11/25 14:32:36 tom Exp @ + * @Id: term_variables.3x,v 1.34 2023/12/23 16:08:25 tom Exp @ --> -term_variables 3x 2023-11-25 ncurses 6.4 Library calls +term_variables 3x 2023-12-23 ncurses 6.4 Library calls -
term_variables 3x 2023-11-25 ncurses 6.4 Library calls
+
term_variables 3x 2023-12-23 ncurses 6.4 Library calls

term_variables(3x) Library calls term_variables(3x) @@ -112,7 +112,7 @@ set_term. -
Terminfo Lookup Tables
+
terminfo Lookup Tables
The tic(1) and infocmp(1) programs use lookup tables for the long and short names of terminfo capabilities, as well as the corresponding names for termcap capabilities. These are available to other @@ -136,7 +136,7 @@ ttytype. -
Terminfo Names
+
terminfo Names
In addition to the variables, <term.h> also defines a symbol for each terminfo capability long name. These are in terms of the symbol CUR, which is defined @@ -176,7 +176,7 @@ -ncurses 6.4 2023-11-25 term_variables(3x) +ncurses 6.4 2023-12-23 term_variables(3x)

@@ -186,9 +186,9 @@ ncurses 6.4 2023-11-25 Alternate Character Set Mapping
Current Terminal Data
-
Terminfo Lookup Tables
+
terminfo Lookup Tables

Terminal Type
-
Terminfo Names
+
terminfo Names

NOTES
diff --git a/doc/html/man/terminfo.5.html b/doc/html/man/terminfo.5.html index 6d55396d..813b96f9 100644 --- a/doc/html/man/terminfo.5.html +++ b/doc/html/man/terminfo.5.html @@ -32,7 +32,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: terminfo.head,v 1.57 2023/12/18 01:15:58 tom Exp @ + * @Id: terminfo.head,v 1.59 2023/12/23 23:44:58 tom Exp @ * Head of terminfo man page ends here **************************************************************************** * Copyright 2018-2022,2023 Thomas E. Dickey * @@ -62,7 +62,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: terminfo.tail,v 1.139 2023/12/17 22:56:21 tom Exp @ + * @Id: terminfo.tail,v 1.140 2023/12/23 16:23:35 tom Exp @ *.in -2 *.in +2 *.in -2 @@ -73,12 +73,12 @@ -terminfo 5 2023-12-17 ncurses 6.4 File formats +terminfo 5 2023-12-23 ncurses 6.4 File formats -
terminfo 5 2023-12-17 ncurses 6.4 File formats
+
terminfo 5 2023-12-23 ncurses 6.4 File formats

terminfo(5) File formats terminfo(5) @@ -105,10 +105,10 @@ have, by specifying how to perform screen operations, and by specifying padding requirements and initialization sequences. - This manual describes ncurses version 6.4 (patch 20231217). + This manual describes ncurses version 6.4 (patch 20231223). -
Terminfo Entry Syntax
+
terminfo Entry Syntax
Entries in terminfo consist of a sequence of fields: o Each field ends with a comma "," (embedded commas may be escaped @@ -178,7 +178,7 @@ For more on terminal naming conventions, see the term(7) manual page. -
Terminfo Capabilities Syntax
+
terminfo Capabilities Syntax
The terminfo entry consists of several capabilities, i.e., features that the terminal has, or methods for exercising the terminal's features. @@ -1505,7 +1505,7 @@ stack in the tparm function. o SVr3.2 curses supported static variables. Those are an array - in the TERMINAL structure (declared in term.h), and are zeroed + in the TERMINAL structure (declared in term.h), and are zeroed automatically when the setupterm function allocates the data. o SVr4 curses made no further improvements to the dynamic/static @@ -2694,7 +2694,7 @@ -ncurses 6.4 2023-12-17 terminfo(5) +ncurses 6.4 2023-12-23 terminfo(5)

@@ -2702,8 +2702,8 @@ ncurses 6.4 2023-12-17 SYNOPSIS
DESCRIPTION
-
Terminfo Entry Syntax
-
Terminfo Capabilities Syntax
+
terminfo Entry Syntax
+
terminfo Capabilities Syntax

Similar Terminals

Predefined Capabilities

User-Defined Capabilities
diff --git a/doc/html/man/tic.1m.html b/doc/html/man/tic.1m.html index db6e2ff5..50fc7fb0 100644 --- a/doc/html/man/tic.1m.html +++ b/doc/html/man/tic.1m.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: tic.1m,v 1.104 2023/12/16 20:33:11 tom Exp @ + * @Id: tic.1m,v 1.105 2023/12/23 16:08:25 tom Exp @ --> -tic 1m 2023-12-16 ncurses 6.4 User commands +tic 1m 2023-12-23 ncurses 6.4 User commands -
tic 1m 2023-12-16 ncurses 6.4 User commands
+
tic 1m 2023-12-23 ncurses 6.4 User commands

tic(1m) User commands tic(1m) @@ -109,7 +109,7 @@ goes into further detail. -
ALIASES
+
Aliases
This is the same program as infotocap and captoinfo; usually those are linked to, or copied from this program: @@ -315,7 +315,7 @@ as function keys. -
PARAMETERS
+
Parameters
file contains one or more terminfo terminal descriptions in source format [see terminfo(5)]. Each description in the file describes the capabilities of a particular terminal. @@ -324,7 +324,7 @@ The file parameter may also be the path of a character-device. -
PROCESSING
+
Processing
All but one of the capabilities recognized by tic are documented in terminfo(5). The exception is the use capability. @@ -482,7 +482,7 @@ -ncurses 6.4 2023-12-16 tic(1m) +ncurses 6.4 2023-12-23 tic(1m)

@@ -490,13 +490,13 @@ ncurses 6.4 2023-12-16 <
SYNOPSIS

DESCRIPTION
-
ALIASES
+
Aliases

OPTIONS
-
PARAMETERS
-
PROCESSING
+
Parameters
+
Processing

FILES
diff --git a/doc/html/man/tput.1.html b/doc/html/man/tput.1.html index 40940896..c313b5af 100644 --- a/doc/html/man/tput.1.html +++ b/doc/html/man/tput.1.html @@ -28,19 +28,20 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: tput.1,v 1.92 2023/12/16 20:32:22 tom Exp @ + * @Id: tput.1,v 1.96 2023/12/23 20:55:36 tom Exp @ + * longname was added in October 1989. --> -tput 1 2023-12-16 ncurses 6.4 User commands +tput 1 2023-12-23 ncurses 6.4 User commands -
tput 1 2023-12-16 ncurses 6.4 User commands
+
tput 1 2023-12-23 ncurses 6.4 User commands

tput(1) User commands tput(1) @@ -52,60 +53,62 @@
SYNOPSIS
- tput [-T terminal-type] capname [parameters] + tput [-T terminal-type] cap-code [parameter ...] + tput [-T terminal-type] [-x] clear + tput [-T terminal-type] init + tput [-T terminal-type] reset + tput [-T terminal-type] longname - tput -S << + + tput -S + tput -V
DESCRIPTION
- The tput utility uses the terminfo database to make the values of - terminal-dependent capabilities and information available to the shell - (see sh(1)), to initialize or reset the terminal, or return the long - name of the requested terminal type. The result depends upon the - capability's type: + tput uses the terminfo library and database to make the values of + terminal-specific capabilities and information available to the shell, + to initialize or reset the terminal, or report the long name of the + current (or specified) terminal type. When retrieving capability + values, the result depends upon the capability's type. - string - tput writes the string to the standard output. No trailing - newline is supplied. + Boolean tput sets its exit status to 0 if the terminal possesses cap- + code, and 1 if it does not. - integer - tput writes the decimal value to the standard output, with a - trailing newline. + integer tput writes cap-code's decimal value to the standard output + stream if defined (-1 if it is not) followed by a newline. - boolean - tput simply sets the exit code (0 for TRUE if the terminal has - the capability, 1 for FALSE if it does not), and writes nothing - to the standard output. + string tput writes cap-code's value to the standard output stream if + defined, without a trailing newline. - Before using a value returned on the standard output, the application - should test the exit code (e.g., $?, see sh(1)) to be sure it is 0. - (See the EXIT STATUS and DIAGNOSTICS sections.) For a complete list of - capabilities and the capname associated with each, see terminfo(5). + Before using a value returned on the standard output, the application + should test tput's exit status (for example, using $? in sh(1)) to be + sure it is 0; see sections "EXIT STATUS" and "DIAGNOSTICS" below. For + a complete list of cap-codes, see terminfo(5).
Options
- -S allows more than one capability per invocation of tput. The - capabilities must be passed to tput from the standard input - instead of from the command line (see example). Only one - capname is allowed per line. The -S option changes the meaning - of the 0 and 1 boolean and string exit codes (see the EXIT - STATUS section). - - Because some capabilities may use string parameters rather than + -S allows more than one capability per invocation of tput. The + capabilities must be passed to tput from the standard input + instead of from the command line (see example). Only one cap- + code is allowed per line. The -S option changes the meaning of + the 0 and 1 Boolean and string exit statuses (see section "EXIT + STATUS" below). + + Because some capabilities may use string parameters rather than numbers, tput uses a table and the presence of parameters in its - input to decide whether to use tparm(3x), and how to interpret + input to decide whether to use tparm(3x), and how to interpret the parameters. -Ttype indicates the type of terminal. Normally this option is - unnecessary, because the default is taken from the environment - variable TERM. If -T is specified, then the shell variables + unnecessary, because the default is taken from the environment + variable TERM. If -T is specified, then the shell variables LINES and COLUMNS will also be ignored. - -V reports the version of ncurses which was used in this program, + -V reports the version of ncurses which was used in this program, and exits. -x prevents tput from attempting to clear the scrollback buffer. @@ -114,27 +117,27 @@
Commands
A few commands (init, reset and longname) are special; they are defined by the tput program. The others are the names of capabilities from the - terminal database (see terminfo(5) for a list). Although init and - reset resemble capability names, tput uses several capabilities to + terminal database (see terminfo(5) for a list). Although init and + reset resemble capability names, tput uses several capabilities to perform these special functions. - capname + cap-code indicates the capability from the terminal database. - If the capability is a string that takes parameters, the - arguments following the capability will be used as parameters + If the capability is a string that takes parameters, the + arguments following the capability will be used as parameters for the string. - Most parameters are numbers. Only a few terminal capabilities - require string parameters; tput uses a table to decide which to - pass as strings. Normally tput uses tparm(3x) to perform the - substitution. If no parameters are given for the capability, + Most parameters are numbers. Only a few terminal capabilities + require string parameters; tput uses a table to decide which to + pass as strings. Normally tput uses tparm(3x) to perform the + substitution. If no parameters are given for the capability, tput writes the string without performing the substitution. - init If the terminal database is present and an entry for the user's + init If the terminal database is present and an entry for the user's terminal exists (see -Ttype, above), the following will occur: - (1) first, tput retrieves the current terminal mode settings + (1) first, tput retrieves the current terminal mode settings for your terminal. It does this by successively testing o the standard error, @@ -145,33 +148,33 @@ o ultimately "/dev/tty" - to obtain terminal settings. Having retrieved these - settings, tput remembers which file descriptor to use when + to obtain terminal settings. Having retrieved these + settings, tput remembers which file descriptor to use when updating settings. - (2) if the window size cannot be obtained from the operating + (2) if the window size cannot be obtained from the operating system, but the terminal description (or environment, e.g., - LINES and COLUMNS variables specify this), update the + LINES and COLUMNS variables specify this), update the operating system's notion of the window size. (3) the terminal modes will be updated: - o any delays (e.g., newline) specified in the entry will + o any delays (e.g., newline) specified in the entry will be set in the tty driver, - o tabs expansion will be turned on or off according to + o tabs expansion will be turned on or off according to the specification in the entry, and - o if tabs are not expanded, standard tabs will be set + o if tabs are not expanded, standard tabs will be set (every 8 spaces). - (4) if present, the terminal's initialization strings will be - output as detailed in the terminfo(5) section on Tabs and + (4) if present, the terminal's initialization strings will be + output as detailed in the terminfo(5) section on Tabs and Initialization, (5) output is flushed. - If an entry does not contain the information needed for any of + If an entry does not contain the information needed for any of these activities, that activity will silently be skipped. reset This is similar to init, with two differences: @@ -185,23 +188,22 @@ o turn on newline translation and - o reset any unset special characters to their default + o reset any unset special characters to their default values - (2) Instead of putting out initialization strings, the - terminal's reset strings will be output if present (rs1, - rs2, rs3, rf). If the reset strings are not present, but + (2) Instead of putting out initialization strings, the + terminal's reset strings will be output if present (rs1, + rs2, rs3, rf). If the reset strings are not present, but initialization strings are, the initialization strings will be output. Otherwise, reset acts identically to init. longname - If the terminal database is present and an entry for the user's - terminal exists (see -Ttype above), then the long name of the - terminal will be put out. The long name is the last name in the - first line of the terminal's description in the terminfo - database [see term(5)]. + If the terminal database is present and an entry for the user's + terminal exists (see -T type above), tput reports the terminal's + description (or "long name") to the standard output, without a + trailing newline. See term(5).
Aliases
@@ -268,49 +270,50 @@
EXIT STATUS
If the -S option is used, tput checks for errors from each line, and if - any errors are found, will set the exit code to 4 plus the number of - lines with errors. If no errors are found, the exit code is 0. No - indication of which line failed can be given so exit code 1 will never - appear. Exit codes 2, 3, and 4 retain their usual interpretation. If - the -S option is not used, the exit code depends on the type of - capname: - - boolean + any errors are found, will set the exit status to 4 plus the number of + lines with errors. If no errors are found, the exit status is 0. No + indication of which line failed can be given so exit status 1 will + never appear. Exit statuses 2, 3, and 4 retain their usual + interpretation. If the -S option is not used, the exit status depends + on the type of cap-code: + + Boolean a value of 0 is set for TRUE and 1 for FALSE. - string a value of 0 is set if the capname is defined for this - terminal type (the value of capname is returned on standard - output); a value of 1 is set if capname is not defined for + string a value of 0 is set if the cap-code is defined for this + terminal type (the value of cap-code is returned on standard + output); a value of 1 is set if cap-code is not defined for this terminal type (nothing is written to standard output). integer - a value of 0 is always set, whether or not capname is defined - for this terminal type. To determine if capname is defined - for this terminal type, the user must test the value written - to standard output. A value of -1 means that capname is not - defined for this terminal type. + a value of 0 is always set, whether or not cap-code is + defined for this terminal type. To determine if cap-code is + defined for this terminal type, the user must test the value + written to standard output. A value of -1 means that cap- + code is not defined for this terminal type. other reset or init may fail to find their respective files. In - that case, the exit code is set to 4 + errno. + that case, the exit status is set to 4 + errno. - Any other exit code indicates an error; see the DIAGNOSTICS section. + Any other exit status indicates an error; see section "DIAGNOSTICS" + below.
DIAGNOSTICS
- tput prints the following error messages and sets the corresponding - exit codes. - - exit code error message - ---------------------------------------------------------------------- - 0 (capname is a numeric variable that is not specified in - the terminfo(5) database for this terminal type, e.g. - tput -T450 lines and tput -Thp2621 xmc) - 1 no error message is printed, see the EXIT STATUS section. - 2 usage error - 3 unknown terminal type or no terminfo database - 4 unknown terminfo capability capname - >4 error occurred in -S - ---------------------------------------------------------------------- + tput prints the following error messages and sets the corresponding + exit statuses. + + exit status error message + ------------------------------------------------------------------------ + 0 (cap-code is a numeric variable that is not specified in + the terminfo(5) database for this terminal type, e.g. + tput -T450 lines and tput -Thp2621 xmc) + 1 no error message is printed, see the EXIT STATUS section. + 2 usage error + 3 unknown terminal type or no terminfo database + 4 unknown terminfo capability cap-code + >4 error occurred in -S + ------------------------------------------------------------------------
FILES
@@ -322,75 +325,76 @@
PORTABILITY
- This implementation of tput differs from AT&T tput in two important + This implementation of tput differs from AT&T tput in two important areas: - o tput capname writes to the standard output. That need not be a - regular terminal. However, the subcommands which manipulate + o tput cap-code writes to the standard output. That need not be a + regular terminal. However, the subcommands which manipulate terminal modes may not use the standard output. - The AT&T implementation's init and reset commands use the BSD - (4.1c) tset source, which manipulates terminal modes. It - successively tries standard output, standard error, standard input + The AT&T implementation's init and reset commands use the BSD + (4.1c) tset source, which manipulates terminal modes. It + successively tries standard output, standard error, standard input before falling back to "/dev/tty" and finally just assumes a 1200Bd terminal. When updating terminal modes, it ignores errors. - Until changes made after ncurses 6.0, tput did not modify terminal + Until changes made after ncurses 6.0, tput did not modify terminal modes. tput now uses a similar scheme, using functions shared with - tset (and ultimately based on the 4.4BSD tset). If it is not able + tset (and ultimately based on the 4.4BSD tset). If it is not able to open a terminal, e.g., when running in cron(1), tput will return an error. - o AT&T tput guesses the type of its capname operands by seeing if all - of the characters are numeric, or not. + o AT&T tput guesses the type of its cap-code operands by seeing if + all of the characters are numeric, or not. - Most implementations which provide support for capname operands use - the tparm function to expand parameters in it. That function - expects a mixture of numeric and string parameters, requiring tput + Most implementations which provide support for cap-code operands + use the tparm function to expand parameters in it. That function + expects a mixture of numeric and string parameters, requiring tput to know which type to use. - This implementation uses a table to determine the parameter types - for the standard capname operands, and an internal library function - to analyze nonstandard capname operands. + This implementation uses a table to determine the parameter types + for the standard cap-code operands, and an internal library + function to analyze nonstandard cap-code operands. - Besides providing more reliable operation than AT&T's utility, a - portability problem is introduced by this analysis: An OpenBSD - developer adapted the internal library function from ncurses to - port NetBSD's termcap-based tput to terminfo. That had been - modified to interpret multiple commands on a line. Portable + Besides providing more reliable operation than AT&T's utility, a + portability problem is introduced by this analysis: An OpenBSD + developer adapted the internal library function from ncurses to + port NetBSD's termcap-based tput to terminfo. That had been + modified to interpret multiple commands on a line. Portable applications should not rely upon this feature; ncurses provides it to support applications written specifically for OpenBSD. This implementation (unlike others) can accept both termcap and - terminfo names for the capname feature, if termcap support is compiled - in. However, the predefined termcap and terminfo names have two + terminfo names for the cap-code feature, if termcap support is compiled + in. However, the predefined termcap and terminfo names have two ambiguities in this case (and the terminfo name is assumed): - o The termcap name dl corresponds to the terminfo name dl1 (delete + o The termcap name dl corresponds to the terminfo name dl1 (delete one line). - The terminfo name dl corresponds to the termcap name DL (delete a + The terminfo name dl corresponds to the termcap name DL (delete a given number of lines). - o The termcap name ed corresponds to the terminfo name rmdc (end + o The termcap name ed corresponds to the terminfo name rmdc (end delete mode). - The terminfo name ed corresponds to the termcap name cd (clear to + The terminfo name ed corresponds to the termcap name cd (clear to end of screen). - The longname and -S options, and the parameter-substitution features - used in the cup example, were not supported in BSD curses before - 4.3reno (1989) or in AT&T/USL curses before SVr4 (1988). + The longname and -S options, and the parameter-substitution features + used in the cup example, were not supported in AT&T/USL curses before + SVr4 (1989). Later, 4.3BSD-Reno (1990) added support for longname, and + NetBSD (1994) added support for the parameter-substitution features. IEEE Std 1003.1/The Open Group Base Specifications Issue 7 (POSIX.1-2008) documents only the operands for clear, init and reset. There are a few interesting observations to make regarding that: - o In this implementation, clear is part of the capname support. The + o In this implementation, clear is part of the cap-code support. The others (init and longname) do not correspond to terminal capabilities. o Other implementations of tput on SVr4-based systems such as Solaris, IRIX64 and HP-UX as well as others such as AIX and Tru64 - provide support for capname operands. + provide support for cap-code operands. o A few platforms such as FreeBSD recognize termcap names rather than terminfo capability names in their respective tput commands. Since @@ -404,7 +408,7 @@ set of capability names, the reasoning for documenting only a few may not be apparent. - o X/Open Curses Issue 7 documents tput differently, with capname and + o X/Open Curses Issue 7 documents tput differently, with cap-code and the other features used in this implementation. o That is, there are two standards for tput: POSIX (a subset) and @@ -413,87 +417,86 @@ terminal capabilities database. o While it is certainly possible to write a tput program without - using curses, none of the systems which have a curses - implementation provide a tput utility which does not provide the - capname feature. + using curses, no system with a curses implementation provides a + tput utility that does not also supply the cap-code feature. X/Open Curses Issue 7 (2009) is the first version to document utilities. However that part of X/Open Curses does not follow existing - practice (i.e., Unix features documented in SVID 3): + practice (that is, System V curses behavior). - o It assigns exit code 4 to "invalid operand", which may be the same - as unknown capability. For instance, the source code for Solaris' - xcurses uses the term "invalid" in this case. + o It assigns exit status 4 to "invalid operand", which may be the + same as unknown capability. For instance, the source code for + Solaris' xcurses uses the term "invalid" in this case. - o It assigns exit code 255 to a numeric variable that is not + o It assigns exit status 255 to a numeric variable that is not specified in the terminfo database. That likely is a documentation - error, confusing the -1 written to the standard output for an - absent or cancelled numeric value versus an (unsigned) exit code. + error, confusing the -1 written to the standard output for an + absent or cancelled numeric value versus an (unsigned) exit status. - The various Unix systems (AIX, HP-UX, Solaris) use the same exit-codes - as ncurses. + The various Unix systems (AIX, HP-UX, Solaris) use the same exit + statuses as ncurses. - NetBSD curses documents different exit codes which do not correspond to - either ncurses or X/Open. + NetBSD curses documents different exit statuses which do not correspond + to either ncurses or X/Open.
HISTORY
- The tput command was begun by Bill Joy in 1980. The initial version + The tput command was begun by Bill Joy in 1980. The initial version only cleared the screen. AT&T System V provided a different tput command: - o SVr2 provided a rudimentary tput which checked the parameter - against each predefined capability and returned the corresponding - value. This version of tput did not use tparm(3x) for the + o SVr2 provided a rudimentary tput which checked the parameter + against each predefined capability and returned the corresponding + value. This version of tput did not use tparm(3x) for the capabilities which are parameterized. o SVr3 replaced that, a year later, by a more extensive program whose - init and reset subcommands (more than half the program) were - incorporated from the reset feature of BSD tset written by Eric + init and reset subcommands (more than half the program) were + incorporated from the reset feature of BSD tset written by Eric Allman. o SVr4 added color initialization using the orig_colors and orig_pair capabilities in the init subcommand. - Keith Bostic replaced the BSD tput command in 1989 with a new - implementation based on the AT&T System V program tput. Like the AT&T - program, Bostic's version accepted some parameters named for terminfo - capabilities (clear, init, longname and reset). However (because he - had only termcap available), it accepted termcap names for other - capabilities. Also, Bostic's BSD tput did not modify the terminal I/O + Keith Bostic replaced the BSD tput command in 1989 with a new + implementation based on the AT&T System V program tput. Like the AT&T + program, Bostic's version accepted some parameters named for terminfo + capabilities (clear, init, longname and reset). However (because he + had only termcap available), it accepted termcap names for other + capabilities. Also, Bostic's BSD tput did not modify the terminal I/O modes as the earlier BSD tset had done. At the same time, Bostic added a shell script named "clear", which used tput to clear the screen. - Both of these appeared in 4.4BSD, becoming the "modern" BSD + Both of these appeared in 4.4BSD, becoming the "modern" BSD implementation of tput. - This implementation of tput began from a different source than AT&T or - BSD: Ross Ridge's mytinfo package, published on comp.sources.unix in - December 1992. Ridge's program made more sophisticated use of the - terminal capabilities than the BSD program. Eric Raymond used that - tput program (and other parts of mytinfo) in ncurses in June 1995. - Using the portions dealing with terminal capabilities almost without - change, Raymond made improvements to the way the command-line + This implementation of tput began from a different source than AT&T or + BSD: Ross Ridge's mytinfo package, published on comp.sources.unix in + December 1992. Ridge's program made more sophisticated use of the + terminal capabilities than the BSD program. Eric Raymond used that + tput program (and other parts of mytinfo) in ncurses in June 1995. + Using the portions dealing with terminal capabilities almost without + change, Raymond made improvements to the way the command-line parameters were handled.
EXAMPLES
tput init - Initialize the terminal according to the type of terminal in the - environmental variable TERM. This command should be included in - everyone's .profile after the environmental variable TERM has been + Initialize the terminal according to the type of terminal in the + environment variable TERM. This command should be included in + everyone's .profile after the environment variable TERM has been exported, as illustrated on the profile(5) manual page. tput -T5620 reset - Reset an AT&T 5620 terminal, overriding the type of terminal in - the environmental variable TERM. + Reset an AT&T 5620 terminal, overriding the type of terminal in + the environment variable TERM. tput cup 0 0 Send the sequence to move the cursor to row 0, column 0 (the upper - left corner of the screen, usually known as the "home" cursor + left corner of the screen, usually known as the "home" cursor position). tput clear @@ -506,36 +509,43 @@ Print the number of columns for the 450 terminal. bold=`tput smso` offbold=`tput rmso` - Set the shell variables bold, to begin stand-out mode sequence, - and offbold, to end standout mode sequence, for the current + Set the shell variables bold, to begin stand-out mode sequence, + and offbold, to end standout mode sequence, for the current terminal. This might be followed by a prompt: echo "${bold}Please type in your name: ${offbold}\c" tput hc - Set exit code to indicate if the current terminal is a hard copy + Set exit status to indicate if the current terminal is a hard copy terminal. tput cup 23 4 Send the sequence to move the cursor to row 23, column 4. tput cup - Send the terminfo string for cursor-movement, with no parameters + Send the terminfo string for cursor-movement, with no parameters substituted. tput longname - Print the long name from the terminfo database for the type of - terminal specified in the environmental variable TERM. + Print the long name from the terminfo database for the type of + terminal specified in the environment variable TERM. + + tput -S + The -S option can be profitably used with a shell "here document". + + $ tput -S <<! + > clear + > cup 10 10 + > bold + > ! + + We see tput processing several capabilities in one invocation. It + clears the screen, moves the cursor to position (10, 10) and turns + on bold (extra bright) mode. - tput -S <<! - > clear - > cup 10 10 - > bold - > ! + The same sequence of commands can be combined using the OpenBSD + feature: - This example shows tput processing several capabilities in one - invocation. It clears the screen, moves the cursor to position - 10, 10 and turns on bold (extra bright) mode. The list is - terminated by an exclamation mark (!) on a line by itself. + $ tput clear cup 10 10 bold
SEE ALSO
@@ -543,7 +553,7 @@ -ncurses 6.4 2023-12-16 tput(1) +ncurses 6.4 2023-12-23 tput(1)

diff --git a/doc/html/man/tset.1.html b/doc/html/man/tset.1.html index 5064c686..c60e2a7f 100644 --- a/doc/html/man/tset.1.html +++ b/doc/html/man/tset.1.html @@ -27,7 +27,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: tset.1,v 1.78 2023/12/16 20:32:22 tom Exp @ + * @Id: tset.1,v 1.79 2023/12/23 16:20:07 tom Exp @ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s6/reset.c * https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\ * reset.c @@ -43,12 +43,12 @@ -tset 1 2023-12-16 ncurses 6.4 User commands +tset 1 2023-12-23 ncurses 6.4 User commands -
tset 1 2023-12-16 ncurses 6.4 User commands
+
tset 1 2023-12-23 ncurses 6.4 User commands

tset(1) User commands tset(1) @@ -68,7 +68,7 @@
DESCRIPTION
-
tset - initialization
+
tset -- initialization
This program initializes terminals. First, tset retrieves the current terminal mode settings for your @@ -90,11 +90,11 @@ 1. The terminal argument specified on the command line. - 2. The value of the TERM environmental variable. + 2. The value of the TERM environment variable. 3. (BSD systems only.) The terminal type associated with the standard error output device in the /etc/ttys file. (On System V hosts and - systems using that convention, getty(1) does this job by setting TERM + systems using that convention, getty(8) does this job by setting TERM according to the type passed to it by /etc/inittab.) 4. The default terminal type, "unknown", is not suitable for curses @@ -132,7 +132,7 @@ displayed to the standard error output. -
reset - reinitialization
+
reset -- reinitialization
When invoked as reset, tset sets the terminal modes to "sane" values: o sets cooked and echo modes, @@ -168,61 +168,60 @@ When the -s option is specified, the commands to enter the information into the shell's environment are written to the standard output. If - the SHELL environmental variable ends in "csh", the commands are for - csh, otherwise, they are for sh(1). Note, the csh commands set and - unset the shell variable noglob, leaving it unset. The following line - in the .login or .profile files will initialize the environment - correctly: + the SHELL environment variable ends in "csh", the commands are for + csh(1), otherwise, they are for sh(1). The csh commands set and unset + the shell variable noglob, leaving it unset. The following line in the + .login or .profile files will initialize the environment correctly: eval `tset -s options ... `
Terminal Type Mapping
- When the terminal is not hardwired into the system (or the current - system information is incorrect) the terminal type derived from the - /etc/ttys file or the TERM environmental variable is often something - generic like network, dialup, or unknown. When tset is used in a - startup script it is often desirable to provide information about the + When the terminal is not hardwired into the system (or the current + system information is incorrect) the terminal type derived from the + /etc/ttys file or the TERM environment variable is often something + generic like network, dialup, or unknown. When tset is used in a + startup script it is often desirable to provide information about the type of terminal used on such ports. - The -m options maps from some set of conditions to a terminal type, + The -m options maps from some set of conditions to a terminal type, that is, to tell tset "If I'm on this port at a particular speed, guess that I'm on that kind of terminal". - The argument to the -m option consists of an optional port type, an - optional operator, an optional baud rate specification, an optional - colon (":") character and a terminal type. The port type is a string - (delimited by either the operator or the colon character). The - operator may be any combination of ">", "<", "@", and "!"; ">" means - greater than, "<" means less than, "@" means equal to and "!" inverts - the sense of the test. The baud rate is specified as a number and is - compared with the speed of the standard error output (which should be + The argument to the -m option consists of an optional port type, an + optional operator, an optional baud rate specification, an optional + colon (":") character and a terminal type. The port type is a string + (delimited by either the operator or the colon character). The + operator may be any combination of ">", "<", "@", and "!"; ">" means + greater than, "<" means less than, "@" means equal to and "!" inverts + the sense of the test. The baud rate is specified as a number and is + compared with the speed of the standard error output (which should be the control terminal). The terminal type is a string. - If the terminal type is not specified on the command line, the -m - mappings are applied to the terminal type. If the port type and baud - rate match the mapping, the terminal type specified in the mapping - replaces the current type. If more than one mapping is specified, the + If the terminal type is not specified on the command line, the -m + mappings are applied to the terminal type. If the port type and baud + rate match the mapping, the terminal type specified in the mapping + replaces the current type. If more than one mapping is specified, the first applicable mapping is used. - For example, consider the following mapping: dialup>9600:vt100. The + For example, consider the following mapping: dialup>9600:vt100. The port type is dialup , the operator is >, the baud rate specification is 9600, and the terminal type is vt100. The result of this mapping is to - specify that if the terminal type is dialup, and the baud rate is + specify that if the terminal type is dialup, and the baud rate is greater than 9600 baud, a terminal type of vt100 will be used. - If no baud rate is specified, the terminal type will match any baud - rate. If no port type is specified, the terminal type will match any - port type. For example, -m dialup:vt100 -m :?xterm will cause any + If no baud rate is specified, the terminal type will match any baud + rate. If no port type is specified, the terminal type will match any + port type. For example, -m dialup:vt100 -m :?xterm will cause any dialup port, regardless of baud rate, to match the terminal type vt100, - and any non-dialup port type to match the terminal type ?xterm. Note, - because of the leading question mark, the user will be queried on a + and any non-dialup port type to match the terminal type ?xterm. Note, + because of the leading question mark, the user will be queried on a default port as to whether they are actually using an xterm terminal. - No whitespace characters are permitted in the -m option argument. - Also, to avoid problems with meta-characters, it is suggested that the + No whitespace characters are permitted in the -m option argument. + Also, to avoid problems with meta-characters, it is suggested that the entire -m option argument be placed within single quote characters, and - that csh users insert a backslash character ("\") before any + that csh users insert a backslash character ("\") before any exclamation marks ("!"). @@ -234,7 +233,7 @@ -e ch Set the erase character to ch. - -I Do not send the terminal or tab initialization strings to the + -I Do not send the terminal or tab initialization strings to the terminal. -i ch @@ -244,32 +243,32 @@ Set the line kill character to ch. -m mapping - Specify a mapping from a port type to a terminal; see subsection + Specify a mapping from a port type to a terminal; see subsection "Terminal Type Mapping". - -Q Do not display any values for the erase, interrupt and line kill - characters. Normally tset displays the values for control + -Q Do not display any values for the erase, interrupt and line kill + characters. Normally tset displays the values for control characters which differ from the system's default values. - -q The terminal type is displayed to the standard output, and the - terminal is not initialized in any way. The option "-" by itself + -q The terminal type is displayed to the standard output, and the + terminal is not initialized in any way. The option "-" by itself is equivalent but archaic. -r Print the terminal type to the standard error output. -s Print the sequence of shell commands to initialize the environment - variable TERM to the standard output; see subsection "Setting the + variable TERM to the standard output; see subsection "Setting the Environment". -V reports the version of ncurses which was used in this program, and exits. - -w Resize the window to match the size deduced via setupterm(3x). - Normally this has no effect, unless setupterm is not able to + -w Resize the window to match the size deduced via setupterm(3x). + Normally this has no effect, unless setupterm is not able to detect the window size. - The arguments for the -e, -i, and -k options may either be entered as - actual characters or by using the "hat" notation, i.e., control-h may + The arguments for the -e, -i, and -k options may either be entered as + actual characters or by using the "hat" notation, i.e., control-h may be specified as "^H" or "^h". If neither -c or -w is given, both options are assumed. @@ -279,16 +278,16 @@ The tset command uses these environment variables: SHELL - tells tset whether to initialize TERM using sh(1) or csh(1) + tells tset whether to initialize TERM using sh(1) or csh(1) syntax. - TERM Denotes your terminal type. Each terminal type is distinct, + TERM Denotes your terminal type. Each terminal type is distinct, though many are similar. TERMCAP - may denote the location of a termcap database. If it is not an - absolute pathname, e.g., begins with a "/", tset removes the - variable from the environment before looking for the terminal + may denote the location of a termcap database. If it is not an + absolute pathname, e.g., begins with a "/", tset removes the + variable from the environment before looking for the terminal description. @@ -302,108 +301,108 @@
PORTABILITY
- Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7 + Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7 (POSIX.1-2008) nor X/Open Curses Issue 7 documents tset or reset. - The AT&T tput utility (AIX, HP-UX, Solaris) incorporated the terminal- - mode manipulation as well as termcap-based features such as resetting - tabstops from tset in BSD (4.1c), presumably with the intention of - making tset obsolete. However, each of those systems still provides - tset. In fact, the commonly-used reset utility is always an alias for + The AT&T tput utility (AIX, HP-UX, Solaris) incorporated the terminal- + mode manipulation as well as termcap-based features such as resetting + tabstops from tset in BSD (4.1c), presumably with the intention of + making tset obsolete. However, each of those systems still provides + tset. In fact, the commonly-used reset utility is always an alias for tset. The tset utility provides backward compatibility with BSD environments; - under most modern Unices, /etc/inittab and getty(1) can set TERM - appropriately for each dial-up line, obviating what was tset's most - important use. This implementation behaves like 4.4BSD tset, with a + under most modern Unices, /etc/inittab and getty(8) can set TERM + appropriately for each dial-up line, obviating what was tset's most + important use. This implementation behaves like 4.4BSD tset, with a few exceptions we shall consider now. - A few options are different because the TERMCAP variable is no longer + A few options are different because the TERMCAP variable is no longer supported under terminfo-based ncurses: - o The -S option of BSD tset no longer works; it prints an error + o The -S option of BSD tset no longer works; it prints an error message to the standard error and dies. o The -s option only sets TERM, not TERMCAP. - There was an undocumented 4.4BSD feature that invoking tset via a link - named "TSET" (or via any other name beginning with an upper-case + There was an undocumented 4.4BSD feature that invoking tset via a link + named "TSET" (or via any other name beginning with an upper-case letter) set the terminal to use upper-case only. This feature has been omitted. The -A, -E, -h, -u and -v options were deleted from the tset utility in - 4.4BSD. None of them were documented in 4.3BSD and all are of limited - utility at best. The -a, -d, and -p options are similarly not - documented or useful, but were retained as they appear to be in - widespread use. It is strongly recommended that any usage of these + 4.4BSD. None of them were documented in 4.3BSD and all are of limited + utility at best. The -a, -d, and -p options are similarly not + documented or useful, but were retained as they appear to be in + widespread use. It is strongly recommended that any usage of these three options be changed to use the -m option instead. The -a, -d, and -p options are therefore omitted from the usage summary above. - Very old systems, e.g., 3BSD, used a different terminal driver which - was replaced in 4BSD in the early 1980s. To accommodate these older - systems, the 4BSD tset provided a -n option to specify that the new - terminal driver should be used. This implementation does not provide + Very old systems, e.g., 3BSD, used a different terminal driver which + was replaced in 4BSD in the early 1980s. To accommodate these older + systems, the 4BSD tset provided a -n option to specify that the new + terminal driver should be used. This implementation does not provide that choice. - It is still permissible to specify the -e, -i, and -k options without + It is still permissible to specify the -e, -i, and -k options without arguments, although it is strongly recommended that such usage be fixed to explicitly specify the character. - As of 4.4BSD, executing tset as reset no longer implies the -Q option. + As of 4.4BSD, executing tset as reset no longer implies the -Q option. Also, the interaction between the - option and the terminal argument in some historic implementations of tset has been removed. - The -c and -w options are not found in earlier implementations. + The -c and -w options are not found in earlier implementations. However, a different window size-change feature was provided in 4.4BSD. - o In 4.4BSD, tset uses the window size from the termcap description - to set the window size if tset is not able to obtain the window + o In 4.4BSD, tset uses the window size from the termcap description + to set the window size if tset is not able to obtain the window size from the operating system. o In ncurses, tset obtains the window size using setupterm, which may - be from the operating system, the LINES and COLUMNS environment + be from the operating system, the LINES and COLUMNS environment variables or the terminal description. - Obtaining the window size from the terminal description is common to - both implementations, but considered obsolescent. Its only practical + Obtaining the window size from the terminal description is common to + both implementations, but considered obsolescent. Its only practical use is for hardware terminals. Generally speaking, a window size would - be unset only if there were some problem obtaining the value from the - operating system (and setupterm would still fail). For that reason, - the LINES and COLUMNS environment variables may be useful for working - around window-size problems. Those have the drawback that if the - window is resized, those variables must be recomputed and reassigned. + be unset only if there were some problem obtaining the value from the + operating system (and setupterm would still fail). For that reason, + the LINES and COLUMNS environment variables may be useful for working + around window-size problems. Those have the drawback that if the + window is resized, those variables must be recomputed and reassigned. To do this more easily, use the resize(1) program.
HISTORY
- A reset command written by Kurt Shoens appeared in 1BSD (March 1978). + A reset command written by Kurt Shoens appeared in 1BSD (March 1978). It set the erase and kill characters to ^H (backspace) and @ - respectively. Mark Horton improved this reset in 3BSD (October 1979), - adding intr, quit, start/stop, and eof characters as well as changing - the program to avoid modifying any user settings. That version of + respectively. Mark Horton improved this reset in 3BSD (October 1979), + adding intr, quit, start/stop, and eof characters as well as changing + the program to avoid modifying any user settings. That version of reset did not use termcap. - Eric Allman wrote a distinct tset command for 1BSD, using a forerunner - of termcap called ttycap. Allman's comments in the source code - indicate that he began work in October 1977, continuing development - over the next few years. By late 1979, it had migrated to termcap and - handled the TERMCAP variable. Later comments indicate that tset was - modified in September 1980 to use logic copied from the 3BSD "reset" - program when it was invoked as reset. This version appeared in - 4.1cBSD, late in 1982. Other developers such as Keith Bostic and Jim + Eric Allman wrote a distinct tset command for 1BSD, using a forerunner + of termcap called ttycap. Allman's comments in the source code + indicate that he began work in October 1977, continuing development + over the next few years. By late 1979, it had migrated to termcap and + handled the TERMCAP variable. Later comments indicate that tset was + modified in September 1980 to use logic copied from the 3BSD "reset" + program when it was invoked as reset. This version appeared in + 4.1cBSD, late in 1982. Other developers such as Keith Bostic and Jim Bloom continued to modify tset until 4.4BSD was released in 1993. - The ncurses implementation was lightly adapted from the 4.4BSD sources + The ncurses implementation was lightly adapted from the 4.4BSD sources to use the terminfo API by Eric S. Raymond <esr@snark.thyrsus.com>.
SEE ALSO
- csh(1), sh(1), stty(1), curs_terminfo(3x), tty(4), terminfo(5), + csh(1), sh(1), stty(1), curs_terminfo(3x), tty(4), terminfo(5), ttys(5), environ(7) -ncurses 6.4 2023-12-16 tset(1) +ncurses 6.4 2023-12-23 tset(1)

@@ -411,8 +410,8 @@ ncurses 6.4 2023-12-16 <
SYNOPSIS

DESCRIPTION
-
tset - initialization
-
reset - reinitialization
+
tset -- initialization
+
reset -- reinitialization

Setting the Environment

Terminal Type Mapping

diff --git a/doc/html/man/user_caps.5.html b/doc/html/man/user_caps.5.html index 0491b60a..98ae2ec9 100644 --- a/doc/html/man/user_caps.5.html +++ b/doc/html/man/user_caps.5.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: user_caps.5,v 1.42 2023/12/16 20:32:22 tom Exp @ + * @Id: user_caps.5,v 1.43 2023/12/23 16:08:25 tom Exp @ --> -user_caps 5 2023-12-16 ncurses 6.4 File formats +user_caps 5 2023-12-23 ncurses 6.4 File formats -
user_caps 5 2023-12-16 ncurses 6.4 File formats
+
user_caps 5 2023-12-23 ncurses 6.4 File formats

user_caps(5) File formats user_caps(5) @@ -179,7 +179,7 @@ terminfo. -
Recognized capabilities
+
Recognized Capabilities
The ncurses library uses the user-definable capabilities. While the terminfo database may have other extensions, ncurses makes explicit checks for these: @@ -314,7 +314,7 @@ %?%p4%tM%em%;, -
Extended key-definitions
+
Extended Key Definitions
Several terminals provide the ability to send distinct strings for combinations of modified special keys. There is no standard for what those keys can send. @@ -396,7 +396,7 @@ -ncurses 6.4 2023-12-16 user_caps(5) +ncurses 6.4 2023-12-23 user_caps(5)

@@ -405,8 +405,8 @@ ncurses 6.4 2023-12-16 DESCRIPTION

Background
-
Recognized capabilities
-
Extended key-definitions
+
Recognized Capabilities
+
Extended Key Definitions

PORTABILITY
diff --git a/man/MKncu_config.in b/man/MKncu_config.in index 269d3401..ec6aa90a 100644 --- a/man/MKncu_config.in +++ b/man/MKncu_config.in @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: MKncu_config.in,v 1.20 2023/12/16 21:43:05 tom Exp $ -.TH @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config 1 2023-12-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands" +.\" $Id: MKncu_config.in,v 1.22 2023/12/23 23:44:26 tom Exp $ +.TH @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config 1 2023-12-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands" .SH NAME \fB\%@LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config\fP \- configuration helper for \fI\%ncurses\fP libraries @@ -57,10 +57,6 @@ reports the C compiler flags needed to compile with \fI\%ncurses\fP. \fB\-\-libs\fP reports the libraries needed to link with \fI\%ncurses\fP. .TP -\fB\-\-version\fP -reports the release and patch date information of \fI\%ncurses\fP and -exits successfully. -.TP \fB\-\-abi\-version\fP reports the ABI version of \fI\%ncurses\fP. .TP @@ -95,8 +91,14 @@ for example \fI\%@TERMINFO_DIRS@\fP. reports the \fI\%TERMPATH\fP supplemental search path for the \fItermcap\fP database, if support for \fItermcap\fP is configured. -.TP +.PP +The following options cause all others to be ignored. +.TP 11 .\" "--version" + 2n \fB\-\-help\fP issues a usage message and exits successfully. +.TP +\fB\-\-version\fP +issues the release and patch date information of \fI\%ncurses\fP and +exits successfully. .SH "SEE ALSO" \fB\%curses\fP(3X) diff --git a/man/captoinfo.1m b/man/captoinfo.1m index 43a0bd6d..bd98b7d0 100644 --- a/man/captoinfo.1m +++ b/man/captoinfo.1m @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: captoinfo.1m,v 1.57 2023/12/16 21:34:23 tom Exp $ -.TH @CAPTOINFO@ 1M 2023-12-16 "ncurses 6.4" "User commands" +.\" $Id: captoinfo.1m,v 1.58 2023/12/23 16:28:31 tom Exp $ +.TH @CAPTOINFO@ 1M 2023-12-23 "ncurses 6.4" "User commands" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -40,8 +40,6 @@ .ie t .ds '' '' .el .ds '' "" .\} -. -.ds d /etc/termcap .SH NAME \fB\%@CAPTOINFO@\fP \- convert a \fItermcap\fP description into a \fI\%term\%info\fP description @@ -67,7 +65,8 @@ If no \fIfile\fPs are specified, and extracts only the entry for the terminal named in the environment variable \fITERM\fP from it. If the environment variable \fI\%TERMCAP\fP is not set, -\fB\%@CAPTOINFO@\fP reads \fI\%\*d\fP. +\fB\%@CAPTOINFO@\fP reads +.I \%/etc/termcap. .PP This utility is implemented as a link to \fB\%@TIC@\fP(1M), with the latter's @@ -82,7 +81,7 @@ and .BR \-x . The \fB\-V\fP option reports the version of \fI\%ncurses\fP associated with this program and exits with a successful status. -.SS "Translations from nonstandard capabilities" +.SS "Translations from Nonstandard Capabilities" \fB\%@CAPTOINFO@\fP translates some obsolete, nonstandard capabilities into standard (SVr4/XSI Curses) @@ -204,7 +203,7 @@ The HP-UX \fI\%\%term\%info\fP library supports two nonstandard \fB\%@CAPTOINFO@\fP discards these with a warning message. .SH FILES .TP -.I \*d +.I /etc/termcap default \fI\%termcap\fP terminal capability database .SH PORTABILITY X/Open Curses, diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x index 227acc25..2d2c1421 100644 --- a/man/curs_add_wch.3x +++ b/man/curs_add_wch.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_add_wch.3x,v 1.49 2023/12/16 21:19:37 tom Exp $ -.TH curs_add_wch 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_add_wch.3x,v 1.50 2023/12/23 16:08:25 tom Exp $ +.TH curs_add_wch 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -117,7 +117,7 @@ The knowledge that only a single character is being output is taken into consideration and, for non-control characters, a considerable performance gain might be seen by using the *\fBecho\fP* functions instead of their equivalents. -.SS Line Graphics +.SS "Line Graphics" Like \fB\%addch\fP(3X), \fBaddch_wch\fP accepts symbols which make it simple to draw lines and other frequently used special characters. @@ -255,7 +255,7 @@ may be macros. .SH PORTABILITY These functions are described in the XSI Curses standard, Issue 4. The defaults specified for line-drawing characters apply in the POSIX locale. -.SS WACS Symbols +.SS "WACS Symbols" X/Open Curses makes it clear that the WACS_ symbols should be defined as a pointer to \fBcchar_t\fP data, e.g., in the discussion of \fBborder_set\fP. A few implementations are problematic: @@ -333,7 +333,7 @@ Others have suggested these alternatives: \[u2327] U+2327 (x in a rectangle), \[u256C] U+256C (forms double vertical and horizontal), and \[u2612] U+2612 (ballot box with x). -.SS Complex Characters +.SS "Complex Characters" The complex character type \fBcchar_t\fR can store more than one wide character (\fBwchar_t\fR). The X/Open Curses description does not mention this possibility, diff --git a/man/curs_addch.3x b/man/curs_addch.3x index e61aee2f..b87f7663 100644 --- a/man/curs_addch.3x +++ b/man/curs_addch.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_addch.3x,v 1.75 2023/12/16 21:19:37 tom Exp $ -.TH curs_addch 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_addch.3x,v 1.76 2023/12/23 16:27:51 tom Exp $ +.TH curs_addch 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -66,11 +66,11 @@ add a \fIcurses\fR character to a window and advance the cursor \fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP); .fi .SH DESCRIPTION -.SS Adding characters +.SS "Adding Characters" The \fBaddch\fP, \fBwaddch\fP, \fBmvaddch\fP and \fBmvwaddch\fP routines put the character \fIch\fP into the given window at its current window position, which is then advanced. -They are analogous to \fBputchar\fP(3) in \fBstdio\fP(3). +They are analogous to the standard C library's \fI\%putchar\fP(3). If the advance is at the right margin: .bP The cursor automatically wraps to the beginning of the next line. @@ -122,7 +122,7 @@ Video attributes can be combined with a character argument passed to using \fB\%inch\fP(3X) and \fBaddch\fP.) See the \fB\%curs_attr\fP(3X) page for values of predefined video attribute constants that can be usefully OR'ed into characters. -.SS Echoing characters +.SS "Echoing Characters" The \fBechochar\fP and \fBwechochar\fP routines are equivalent to a call to \fBaddch\fP followed by a call to \fB\%refresh\fP(3X), or a call to \fBwaddch\fP followed by a call to \fBwrefresh\fP. @@ -130,7 +130,7 @@ The knowledge that only a single character is being output is used and, for non-control characters, a considerable performance gain may be seen by using these routines instead of their equivalents. -.SS Line Graphics +.SS "Line Graphics" The following variables may be used to add line drawing characters to the screen with routines of the \fBaddch\fP family. The default character listed @@ -209,7 +209,7 @@ Note that \fBaddch\fP, \fBmvaddch\fP, \fBmvwaddch\fP, and .SH PORTABILITY These functions are described in the XSI Curses standard, Issue 4. The defaults specified for forms-drawing characters apply in the POSIX locale. -.SS ACS Symbols +.SS "ACS Symbols" X/Open Curses states that the \fBACS_\fP definitions are \fBchar\fP constants. For the wide-character implementation (see \fBcurs_add_wch\fP), there are analogous \fBWACS_\fP definitions which are \fBcchar_t\fP constants. @@ -269,7 +269,7 @@ In certain cases, the terminal is unable to display line-drawing characters except by using UTF-8 (see the discussion of \fB\%NCURSES_NO_UTF8_ACS\fP in \fB\%ncurses\fP(3X)). -.SS Character Set +.SS "Character Set" X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains a single character. As discussed in \fB\%curs_attr\fP(3X), that character may have been diff --git a/man/curs_attr.3x b/man/curs_attr.3x index 475d3ab4..daba5c21 100644 --- a/man/curs_attr.3x +++ b/man/curs_attr.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_attr.3x,v 1.92 2023/12/16 21:07:24 tom Exp $ -.TH curs_attr 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_attr.3x,v 1.93 2023/12/23 16:08:25 tom Exp $ +.TH curs_attr 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -127,7 +127,7 @@ when erasing portions of the window. See \fBcurs_bkgd\fP(3X) for functions which modify the attributes used for erasing and clearing. .\" --------------------------------------------------------------------------- -.SS Window attributes +.SS "Window Attributes" There are two sets of functions: .bP functions for manipulating the window attributes and color: @@ -148,7 +148,7 @@ Use \fBattr_off\fP and \fBwattr_off\fP to turn off window attributes, again values OR'd together in \fIattr\fP, without affecting other attributes. .\" --------------------------------------------------------------------------- -.SS Legacy window attributes +.SS "Legacy Window Attributes" The X/Open window attribute routines which \fIset\fP or \fIget\fP, turn \fIon\fP or \fIoff\fP are extensions of older routines @@ -206,7 +206,7 @@ in X/Open Curses, although \fI\%ncurses\fP provides \fB\%getattrs\fP (see \fB\%curs_legacy\fP(3X)). .\" --------------------------------------------------------------------------- -.SS Change character rendition +.SS "Change Character Rendition" The routine \fBchgat\fP changes the attributes of a given number of characters starting at the current cursor location of \fBstdscr\fP. It does not update @@ -221,7 +221,7 @@ In these functions, the color \fIpair\fP argument is a color pair index (as in the first argument of \fBinit_pair\fP, see \fBcurs_color\fP(3X)). .\" --------------------------------------------------------------------------- -.SS Change window color +.SS "Change Window Color" The routine \fBcolor_set\fP sets the current color of the given window to the foreground/background combination described by the color \fIpair\fP parameter. .\" --------------------------------------------------------------------------- diff --git a/man/curs_bkgd.3x b/man/curs_bkgd.3x index 15977746..15a5e649 100644 --- a/man/curs_bkgd.3x +++ b/man/curs_bkgd.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_bkgd.3x,v 1.54 2023/12/17 23:31:28 tom Exp $ -.TH curs_bkgd 3X 2023-12-17 "ncurses 6.4" "Library calls" +.\" $Id: curs_bkgd.3x,v 1.55 2023/12/23 16:35:10 tom Exp $ +.TH curs_bkgd 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -173,7 +173,9 @@ there is no \fB\%wgetbkgd\fP function; \fB\%getbkgd\fP behaves as one would expect \fB\%wgetbkgd\fP to, accepting a \fI\%WINDOW\fP pointer argument. .PP -\fB\%bkgd\fP and \fB\%bkgdset\fP may be available as macros. +\fB\%bkgd\fP and +\fB\%bkgdset\fP +may be implemented as macros. .PP X/Open Curses mentions that the character part of the background must be a single-byte value. diff --git a/man/curs_bkgrnd.3x b/man/curs_bkgrnd.3x index f2e75cff..b80bf049 100644 --- a/man/curs_bkgrnd.3x +++ b/man/curs_bkgrnd.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_bkgrnd.3x,v 1.35 2023/12/16 23:00:21 tom Exp $ -.TH curs_bkgrnd 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_bkgrnd.3x,v 1.36 2023/12/23 16:35:10 tom Exp $ +.TH curs_bkgrnd 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -189,7 +189,7 @@ is null. \fB\%bkgrnd\fP, \fB\%bkgrndset\fP, and \fB\%getbkgrnd\fP -may be available as macros. +may be implemented as macros. .PP Unlike their counterparts in the non-\*(``wide\*('' configuration of .I \%ncurses, diff --git a/man/curs_color.3x b/man/curs_color.3x index 9cf9165e..73dce9ca 100644 --- a/man/curs_color.3x +++ b/man/curs_color.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_color.3x,v 1.93 2023/12/16 21:07:24 tom Exp $ -.TH curs_color 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_color.3x,v 1.95 2023/12/23 20:18:13 tom Exp $ +.TH curs_color 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -75,6 +75,10 @@ manipulate terminal colors with \fIcurses\fR .nf \fB#include .PP +\fI/* variables */ +\fBint COLOR_PAIRS; +\fBint COLORS; +.PP \fBint start_color(void); .PP \fBbool has_colors(void); @@ -100,43 +104,55 @@ manipulate terminal colors with \fIcurses\fR .fi .SH DESCRIPTION .SS Overview -\fIcurses\fP supports color attributes on terminals with that capability. -To use these routines \fB\%start_color\fP must be called, usually right after -\fB\%initscr\fP. -Colors are always used in pairs (referred to as color pairs). -A color pair consists of a foreground color (for characters) and a background -color (for the blank field on which the characters are displayed). -A programmer initializes a color pair with the routine \fB\%init_pair\fP. -After it has been initialized, \fB\%COLOR_PAIR\fP(\fIn\fP) -can be used to convert the pair to a video attribute. -.PP -If a terminal is capable of redefining colors, the programmer can use the -routine \fB\%init_color\fP to change the definition of a color. -The routines \fB\%has_colors\fP and \fB\%can_change_color\fP +\fIcurses\fP supports color attributes on terminals with that +capability. +Call \fB\%start_color\fP +(typically right after \fB\%initscr\fP(3X)) +to enable this feature. +Colors are always used in pairs. +A +.I "color pair" +couples a foreground color for characters with a background color for +the blank field on which characters are rendered. +\fB\%init_pair\fP initializes a color pair. +The macro \fB\%COLOR_PAIR\fP(\fIn\fP) can then convert the pair to a +video attribute. +.PP +If a terminal has the relevant capability, +\fB\%init_color\fP permits (re)definition of a color. +\fB\%has_colors\fP and \fB\%can_change_color\fP return \fBTRUE\fP or \fBFALSE\fP, -depending on whether the terminal has color capabilities and whether the +depending on whether the terminal has color capability and whether the programmer can change the colors. -The routine \fB\%color_content\fP allows a -programmer to extract the amounts of red, green, and blue components in an -initialized color. -The routine \fB\%pair_content\fP allows a programmer to find -out how a given color pair is currently defined. -.SS Color Rendering -The \fIcurses\fP library combines these inputs to produce the -actual foreground and background colors shown on the screen: +\fB\%color_content\fP permits extraction of the +red, +green, +and blue components of an initialized color. +\fB\%pair_content\fP permits discovery of a color pair's current +definition. +.SS Rendering +.I curses +combines the following data to render a character cell. +Any of them can include color information. .bP -per-character video attributes (e.g., via \fB\%waddch\fP), +.I curses +character attributes, +as from \fB\%waddch\fP(3X) or \fB\%wadd_wch\fP(3X) .bP -the window attribute (e.g., by \fB\%wattrset\fP), and +window attributes, +as from \fB\%wattrset\fP(3X) or \fB\%wattr_set\fP(3X) .bP -the background character (e.g., \fB\%wbkgdset\fP). +window background character atttributes, +as from \fB\%wbkgdset\fP(3X) or \fB\%wbkgrndset\fP(3X) .PP -Per-character and window attributes are usually set by a parameter containing -video attributes including a color pair value. -Some functions such as \fB\%wattr_set\fP use a separate parameter which -is the color pair number. +Per-character and window attributes are usually set through a function +parameter containing attributes including a color pair value. +Some functions, +such as \fB\%wattr_set\fP, +use a separate color pair number parameter. .PP -The background character is a special case: it includes a character value, +The background character is a special case: +it includes a character code, just as if it were passed to \fB\%waddch\fP. .PP The \fIcurses\fP library does the actual work of combining these color @@ -189,8 +205,21 @@ There are no standard names for those additional colors. is initialized by \fB\%start_color\fP to the maximum number of colors the terminal can support. .SS COLOR_PAIRS -is initialized by \fB\%start_color\fP to the maximum number of color pairs -the terminal can support. +is initialized by \fB\%start_color\fP to the maximum number of color +pairs the terminal can support. +Often, +its value is the product \fB\%COLORS\fP \(mu \fB\%COLORS\fP, +but this is not always true. +.bP +A few terminals use the HLS color space +(see \fB\%start_color\fP below), +ignoring this rule; +and +.bP +terminals supporting a large number of colors are limited to the number +of color pairs that a +.I "signed short" +value can represent. .SH FUNCTIONS .SS start_color The \fB\%start_color\fP routine requires no arguments. @@ -465,9 +494,18 @@ Color RGB values are not settable. .SH EXTENSIONS The functions marked as extensions were designed for \fB\%ncurses\fP(3X), -and are not found in SVr4 curses, 4.4BSD curses, -or any other previous version of curses. +and are not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous curses implementation. .SH PORTABILITY +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. +.PP This implementation satisfies XSI Curses's minimum maximums for \fB\%COLORS\fP and \fB\%COLOR_PAIRS\fP. .PP @@ -500,8 +538,8 @@ SVr3.2 introduced color support to curses in 1987. .PP SVr4 made internal changes, e.g., moving the storage for the color state -from \fBSP\fP (the \fBSCREEN\fP structure) -to \fB\%cur_term\fP (the \fB\%TERMINAL\fP structure), +from \fBSP\fP (the \fISCREEN\fP structure) +to \fB\%cur_term\fP (the \fI\%TERMINAL\fP structure), but provided the same set of library functions. .PP SVr4 curses limits the number of color pairs to 64, diff --git a/man/curs_extend.3x b/man/curs_extend.3x index 54cb1e7f..05ed5dfb 100644 --- a/man/curs_extend.3x +++ b/man/curs_extend.3x @@ -29,8 +29,8 @@ .\" .\" Author: Thomas E. Dickey 1999-on .\" -.\" $Id: curs_extend.3x,v 1.43 2023/12/16 20:32:22 tom Exp $ -.TH curs_extend 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_extend.3x,v 1.44 2023/12/23 16:36:18 tom Exp $ +.TH curs_extend 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -80,12 +80,19 @@ this in your application. .PP \fBuse_extended_names\fP returns the previous state, allowing you to save this and restore it. +.SH EXTENSIONS +These functions are \fB\%ncurses\fP(3X) extensions, +and are not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous curses implementation. .SH PORTABILITY -These routines are specific to \fI\%ncurses\fP. -They were not supported on -Version 7, BSD or System V implementations. -It is recommended that -any code depending on them be conditioned using NCURSES_VERSION. +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. .SH AUTHORS Thomas Dickey. .SH SEE ALSO diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x index 810e8d2f..dc62c156 100644 --- a/man/curs_get_wch.3x +++ b/man/curs_get_wch.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_get_wch.3x,v 1.30 2023/11/25 13:58:47 tom Exp $ -.TH curs_get_wch 3X 2023-11-25 "ncurses 6.4" "Library calls" +.\" $Id: curs_get_wch.3x,v 1.31 2023/12/23 16:35:10 tom Exp $ +.TH curs_get_wch 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -180,10 +180,10 @@ at the same time. Depending on the state of the tty driver when each character is typed, the program may produce undesirable results. .PP -All of these symbols except +All of these functions except \fB\%wget_wch\fP and \fB\%unget_wch\fP -may be available as macros. +may be implemented as macros. .SH PORTABILITY These functions are described in the XSI Curses standard, Issue 4. .SH SEE ALSO diff --git a/man/curs_getch.3x b/man/curs_getch.3x index 69067297..a44e5741 100644 --- a/man/curs_getch.3x +++ b/man/curs_getch.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getch.3x,v 1.76 2023/12/16 21:01:28 tom Exp $ -.TH curs_getch 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_getch.3x,v 1.77 2023/12/23 16:36:18 tom Exp $ +.TH curs_getch 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -68,7 +68,7 @@ get (or push back) characters from \fIcurses\fR terminal keyboard .B int has_key(int \fIch\fP); .fi .SH DESCRIPTION -.SS Reading characters +.SS "Reading Characters" The \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP and \fBmvwgetch\fP, routines read a character from the window. In no-delay mode, if no input is waiting, the value \fBERR\fP is returned. @@ -101,7 +101,7 @@ Otherwise the character is simply output to the screen. If the window is not a pad, and it has been moved or modified since the last call to \fBwrefresh\fP, \fBwrefresh\fP will be called before another character is read. -.SS Keypad mode +.SS "Keypad Mode" If \fBkeypad\fP is \fBTRUE\fP, and a function key is pressed, the token for that function key is returned instead of the raw characters: .bP @@ -135,11 +135,11 @@ it is an infinite (or very large) value. Because function keys usually begin with an escape character, the terminal may appear to hang in notimeout mode after pressing the escape key until another key is pressed. -.SS Ungetting characters +.SS "Ungetting Characters" The \fBungetch\fP routine places \fIch\fP back onto the input queue to be returned by the next call to \fBwgetch\fP. There is just one input queue for all windows. -.SS Predefined key-codes +.SS "Predefined Key Codes" The following special keys are defined in \fB\fP. .bP Except for the special case \fBKEY_RESIZE\fP, @@ -284,7 +284,7 @@ because with \fBxterm\fP(1) mouse prototocol) \fI\%ncurses\fP must read escape sequences, just like a function key. -.SS Testing key-codes +.SS "Testing Key Codes" The \fBhas_key\fP routine takes a key-code value from the above list, and returns \fBTRUE\fP or \fBFALSE\fP according to whether the current terminal type recognizes a key with that value. @@ -370,32 +370,61 @@ consoles typically support little more than \fBKEY_UP\fP, \fBKEY_DOWN\fP, \fBKEY_NPAGE\fP, \fBKEY_PPAGE\fP, and function keys 1 through 12. The Ins key is usually mapped to \fBKEY_IC\fP. +.SH EXTENSIONS +\fB\%has_key\fP was designed for \fB\%ncurses\fP(3X), +and is not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous curses implementation. .SH PORTABILITY -The *get* functions are described in the XSI Curses standard, Issue 4. -They -read single-byte characters only. -The standard specifies that they return -\fBERR\fP on failure, but specifies no error conditions. +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. .PP -The echo behavior of these functions on input of \fBKEY_\fP or backspace -characters was not specified in the SVr4 documentation. -This description is -adopted from the XSI Curses standard. +X/Open Curses, Issue 4, Version 2, describes +\fB\%getch\fP, +\fB\%wgetch\fP, +\fB\%mvgetch\fP, +\fB\%mvwgetch\fP, +and +\fB\%ungetch\fP. +They read single-byte characters only. +The standard specifies that they return \fBERR\fP on failure, +but describes no failure conditions. .PP -The behavior of \fBgetch\fP and friends in the presence of handled signals is -unspecified in the SVr4 and XSI Curses documentation. -Under historical curses -implementations, it varied depending on whether the operating system's -implementation of handled signal receipt interrupts a \fBread\fP(2) call in -progress or not, and also (in some implementations) depending on whether an -input timeout or non-blocking mode has been set. +The echo behavior of these functions on input of +.B KEY_ +or backspace characters was not specified in the SVr4 documentation. +This description is adapted from X/Open Curses. .PP -\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related -terminfo capabilities, but no higher-level functions use the feature. -The implementation in \fI\%ncurses\fP is an extension. +The behavior of \fBgetch\fP and friends in the presence of signal +handlers is unspecified in the SVr4 documentation and X/Open Curses. +Under historical curses implementations, +it varied depending on whether the operating system's dispatch of a +signal to a handler interrupts a \fBread\fP(2) call in progress or not, +and also +(in some implementations) +whether an input timeout or non-blocking mode has been set. .PP -\fBKEY_RESIZE\fP is an extension first implemented for \fI\%ncurses\fP. -NetBSD curses later added this extension. +.B KEY_MOUSE +is mentioned in X/Open Curses, +along with a few related +.I \%term\%info +capabilities, +but no higher-level functions use the feature. +The implementation in +.I \%ncurses +is an extension. +.PP +.B KEY_RESIZE +is an extension first implemented for +.I \%ncurses. +NetBSD +.I curses +later added this extension. .PP Programmers concerned about portability should be prepared for either of two cases: (a) signal receipt does not interrupt \fBgetch\fP; (b) signal receipt diff --git a/man/curs_initscr.3x b/man/curs_initscr.3x index fcb73d67..3f7c37d6 100644 --- a/man/curs_initscr.3x +++ b/man/curs_initscr.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_initscr.3x,v 1.59 2023/12/17 23:56:04 tom Exp $ -.TH curs_initscr 3X 2023-12-17 "ncurses 6.4" "Library calls" +.\" $Id: curs_initscr.3x,v 1.60 2023/12/23 16:27:25 tom Exp $ +.TH curs_initscr 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -91,7 +91,7 @@ terminal cannot support a screen-oriented program, would also use \fBnewterm\fP. .PP The routine \fBnewterm\fP should be called once for each terminal. -It returns a variable of type \fBSCREEN *\fP which should be saved +It returns a variable of type \fISCREEN *\fP which should be saved as a reference to that terminal. \fBnewterm\fP's arguments are .bP @@ -104,8 +104,8 @@ an input stream connected to the terminal If the \fItype\fP parameter is \fBNULL\fP, \fB$TERM\fP will be used. .PP The file descriptor of the output stream is passed to \fBsetupterm\fP(3X), -which returns a pointer to a \fBTERMINAL\fP structure. -\fBnewterm\fP's return value holds a pointer to the \fBTERMINAL\fP structure. +which returns a pointer to a \fI\%TERMINAL\fP structure. +\fBnewterm\fP's return value holds a pointer to the \fI\%TERMINAL\fP structure. .SS endwin The program must also call \fBendwin\fP for each terminal being used before exiting from \fBcurses\fP. @@ -138,14 +138,14 @@ and \fBFALSE\fP otherwise. The \fBset_term\fP routine is used to switch between different terminals. The screen reference \fInew\fP becomes the new current terminal. The previous terminal is returned by the routine. -This is the only routine which manipulates \fBSCREEN\fP pointers; +This is the only routine which manipulates \fISCREEN\fP pointers; all other routines affect only the current terminal. .SS delscreen The \fBdelscreen\fP routine frees storage associated with the -\fBSCREEN\fP data structure. +\fISCREEN\fP data structure. The \fBendwin\fP routine does not do this, so \fBdelscreen\fP should be called after \fBendwin\fP if a -particular \fBSCREEN\fP is no longer needed. +particular \fISCREEN\fP is no longer needed. .SH RETURN VALUE \fBendwin\fP returns the integer \fBERR\fP upon failure and \fBOK\fP upon successful completion. @@ -193,18 +193,18 @@ in XSI Curses. .PP Calling \fBendwin\fP does not dispose of the memory allocated in \fBinitscr\fP or \fBnewterm\fP. -Deleting a \fBSCREEN\fP provides a way to do this: +Deleting a \fISCREEN\fP provides a way to do this: .bP -X/Open Curses does not say what happens to \fBWINDOW\fPs when \fBdelscreen\fP -\*(``frees storage associated with the \fBSCREEN\fP\*('' +X/Open Curses does not say what happens to \fI\%WINDOW\fPs when \fBdelscreen\fP +\*(``frees storage associated with the \fISCREEN\fP\*('' nor does the SVr4 documentation help, -adding that it should be called after \fBendwin\fP if a \fBSCREEN\fP +adding that it should be called after \fBendwin\fP if a \fISCREEN\fP is no longer needed. .bP -However, \fBWINDOW\fPs are implicitly associated with a \fBSCREEN\fP. +However, \fI\%WINDOW\fPs are implicitly associated with a \fISCREEN\fP. so that it is reasonable to expect \fBdelscreen\fP to deal with these. .bP -SVr4 curses deletes the standard \fBWINDOW\fP structures +SVr4 curses deletes the standard \fI\%WINDOW\fP structures \fBstdscr\fP and \fBcurscr\fP as well as a work area \fBnewscr\fP. SVr4 curses ignores other windows. .bP @@ -214,11 +214,11 @@ using that information to delete those windows when \fBdelscreen\fP is called. .bP NetBSD copied this feature of \fI\%ncurses\fP in 2001. PDCurses follows the SVr4 model, -deleting only the standard \fBWINDOW\fP structures. +deleting only the standard \fI\%WINDOW\fP structures. .SS "High-level versus Low-level" Different implementations may disagree regarding the level of some functions. -For example, \fBSCREEN\fP (returned by \fBnewterm\fP) and -\fBTERMINAL\fP (returned by \fBsetupterm\fP(3X)) hold file descriptors for +For example, \fISCREEN\fP (returned by \fBnewterm\fP) and +\fI\%TERMINAL\fP (returned by \fBsetupterm\fP(3X)) hold file descriptors for the output stream. If an application switches screens using \fBset_term\fR, or switches terminals using \fBset_curterm\fP(3X), @@ -227,16 +227,16 @@ behavior depending on which structure holds the corresponding descriptor. .PP For example .bP -NetBSD's \fBbaudrate\fP(3X) function uses the descriptor in \fBTERMINAL\fP. -\fI\%ncurses\fP and SVr4 use the descriptor in \fBSCREEN\fP. +NetBSD's \fBbaudrate\fP(3X) function uses the descriptor in \fI\%TERMINAL\fP. +\fI\%ncurses\fP and SVr4 use the descriptor in \fISCREEN\fP. .bP NetBSD and \fI\%ncurses\fP use the descriptor -in \fBTERMINAL\fP +in \fI\%TERMINAL\fP for terminal I/O modes, e.g., \fBdef_shell_mode\fP(3X), \fBdef_prog_mode\fP(3X). -SVr4 curses uses the descriptor in \fBSCREEN\fP. +SVr4 curses uses the descriptor in \fISCREEN\fP. .SS "Unset \fITERM\fP Variable" If the \fITERM\fP variable is missing or empty, \fBinitscr\fP uses the value \*(``unknown\*('', @@ -274,14 +274,15 @@ The handler \fIattempts\fP to cleanup the screen on exit. Although it \fIusually\fP works as expected, there are limitations: .RS 5 .bP -Walking the \fBSCREEN\fP list is unsafe, since all list management +Walking the \fISCREEN\fP list is unsafe, since all list management is done without any signal blocking. .bP On systems which have \fBREENTRANT\fP turned on, \fBset_term\fP uses functions which could deadlock or misbehave in other ways. .bP -\fBendwin\fP calls other functions, many of which use stdio or -other library functions which are clearly unsafe. +\fBendwin\fP calls other functions, +many of which use \fI\%stdio\fP(3) or other library functions which are +clearly unsafe. .RE .TP 5 .B SIGTERM diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x index d5d9c968..de844c3c 100644 --- a/man/curs_inopts.3x +++ b/man/curs_inopts.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inopts.3x,v 1.59 2023/12/16 20:32:22 tom Exp $ -.TH curs_inopts 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_inopts.3x,v 1.60 2023/12/23 16:36:18 tom Exp $ +.TH curs_inopts 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -103,175 +103,243 @@ get and set \fIcurses\fR terminal input options \fBint is_raw(void); .fi .SH DESCRIPTION -The \fI\%ncurses\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. +.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 "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 +.I 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. @@ -279,7 +347,8 @@ unless otherwise noted in the preceding routine descriptions. 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. +Any function will also return an error if the terminal was not +initialized. Also, .RS 3 .TP 5 @@ -288,7 +357,6 @@ returns an error if its parameter is outside the range 1..255. .RE .SH NOTES -Note that \fBecho\fP, \fB\%noecho\fP, \fB\%halfdelay\fP, @@ -300,21 +368,28 @@ Note that \fB\%notimeout\fP, \fB\%noqiflush\fP, \fB\%qiflush\fP, -\fB\%timeout\fP, and -\fB\%wtimeout\fP may be macros. +\fB\%timeout\fP, +and +\fB\%wtimeout\fP +may be implemented as macros. .PP -The \fB\%noraw\fP and \fB\%nocbreak\fP calls follow historical practice in that -they attempt to restore to normal (\*(``cooked\*('') mode +\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 raw/noraw and cbreak/nocbreak calls leads to tty driver -control states that are hard to predict or understand; it is not recommended. +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 @@ -322,59 +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 \fI\%ncurses\fP. -They were not supported on Version 7, BSD or System V implementations. -It is recommended that any code depending on \fI\%ncurses\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 +Except as noted in section \*(``EXTENSIONS\*('' above, +X/Open Curses, Issue 4, Version 2 describes these functions. .PP -The \fI\%ncurses\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 +.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, -\fI\%ncurses\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 \fI\%ncurses\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 +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, @@ -382,16 +493,22 @@ 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 \fI\%ncurses\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 \fI\%ncurses\fP, +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 diff --git a/man/curs_ins_wch.3x b/man/curs_ins_wch.3x index 8ef12e44..1f2307a1 100644 --- a/man/curs_ins_wch.3x +++ b/man/curs_ins_wch.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_ins_wch.3x,v 1.24 2023/11/25 11:32:28 tom Exp $ -.TH curs_ins_wch 3X 2023-11-25 "ncurses 6.4" "Library calls" +.\" $Id: curs_ins_wch.3x,v 1.26 2023/12/23 16:03:24 tom Exp $ +.TH curs_ins_wch 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -44,32 +44,71 @@ \fB\%mvins_wch\fP, \fB\%mvwins_wch\fP, \fB\%wins_wch\fP \- -insert a \fIcurses\fR complex character string in a window +insert a \fIcurses\fR complex character in a window .SH SYNOPSIS .nf -#include +\fB#include \fP .PP \fBint ins_wch(const cchar_t *\fIwch\fP); \fBint wins_wch(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP); -.PP \fBint mvins_wch(int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP); \fBint mvwins_wch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fP); .fi .SH DESCRIPTION -These routines, insert the complex character \fIwch\fP with rendition -before the character under the cursor. -All characters to the right of the cursor are moved one space to the right, -with the possibility of the rightmost character on the line being lost. -The insertion operation does not change the cursor position. -.SH RETURN VALUE -If successful, these functions return \fBOK\fP. -If not, they return \fBERR\fP. +These functions insert the +.I curses +complex character +.I wch +at the cursor in the specified window +.I win +(or +.BR \%stdscr ). +The character previously at the cursor and any to its right move one +cell to the right; +the rightmost character on the line is discarded. +The cursor does not advance. +.SH "RETURN VALUE" +These functions return \fBOK\fP on success and \fBERR\fP on failure. +.PP +Functions taking a +.I \%WINDOW +pointer argument fail if the pointer is +.BR NULL . .PP -Functions with a \*(``mv\*('' prefix first perform a cursor movement using -\fBwmove\fP, and return an error if the position is outside the window, -or if the window pointer is null. +Functions prefixed with \*(``mv\*('' first perform cursor movement using +\fB\%wmove\fP and fail if the position +.RI ( y , +.IR x ) +is outside the window. +.SH NOTES +A terminal's +.B \%insert_character +.RB ( ich1 ) +capability +is not necessarily employed. +.PP +\fB\%ins_wch\fP, +\fB\%mvins_wch\fP, +and +\fB\%mvwins_wch\fP +may be implemented as macros. .SH PORTABILITY -These functions are described in the XSI Curses standard, Issue 4. -.SH SEE ALSO +X/Open Curses, Issue 4, describes these functions. +.PP +SVr4 describes successful return values only as +\*(``an integer value other than \fBERR\fP\*(''. +.SH HISTORY +SVr4 (1989) implemented these functions under the names +.BR inswch , +.BR winswch , +.BR mvinswch , +and +.BR mvwinswch . +.SH "SEE ALSO" +\fB\%curs_insch\fP(3X) describes comparable functions in the +non-wide-character +.I curses +configuration. +.PP \fB\%curses\fP(3X), -\fB\%curs_insch\fP(3X) +\fB\%terminfo\fP(5) diff --git a/man/curs_insch.3x b/man/curs_insch.3x index 889ea4ac..4be93c6b 100644 --- a/man/curs_insch.3x +++ b/man/curs_insch.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_insch.3x,v 1.34 2023/12/16 21:09:11 tom Exp $ -.TH curs_insch 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_insch.3x,v 1.36 2023/12/23 16:03:24 tom Exp $ +.TH curs_insch 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -47,39 +47,61 @@ insert a \fIcurses\fR character in a window .SH SYNOPSIS .nf -\fB#include +\fB#include \fP .PP \fBint insch(chtype \fIch\fP); \fBint winsch(WINDOW *\fIwin\fP, chtype \fIch\fP); -.PP \fBint mvinsch(int \fIy\fP, int \fIx\fP, chtype \fIch\fP); \fBint mvwinsch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, chtype \fIch\fP); .fi .SH DESCRIPTION -These routines insert the character \fIch\fP before the character under the -cursor. -All characters to the right of the cursor are moved one space to the -right, with the possibility of the rightmost character on the line being lost. -The insertion operation does not change the cursor position. -.SH RETURN VALUE -These routines return the integer \fBERR\fP upon failure and an \fBOK\fP -(SVr4 specifies only -\*(``an integer value other than \fBERR\fP\*('') -upon successful completion. +These functions insert the +.I curses +character +.I ch +at the cursor in the specified window +.I win +(or +.BR \%stdscr ). +The character previously at the cursor and any to its right move one +cell to the right; +the rightmost character on the line is discarded. +The cursor does not advance. +.SH "RETURN VALUE" +These functions return \fBOK\fP on success and \fBERR\fP on failure. +.PP +Functions taking a +.I \%WINDOW +pointer argument fail if the pointer is +.BR NULL . .PP -Functions with a \*(``mv\*('' prefix first perform a cursor movement using -\fBwmove\fP, and return an error if the position is outside the window, -or if the window pointer is null. +Functions prefixed with \*(``mv\*('' first perform cursor movement using +\fB\%wmove\fP and fail if the position +.RI ( y , +.IR x ) +is outside the window. .SH NOTES -These routines do not necessarily imply use of a hardware insert character -feature. +A terminal's +.B \%insert_character +.RB ( ich1 ) +capability +is not necessarily employed. .PP -Note that \fBinsch\fP, \fBmvinsch\fP, and \fBmvwinsch\fP may be macros. +\fB\%insch\fP, +\fB\%mvinsch\fP, +and +\fB\%mvwinsch\fP +may be implemented as macros. .SH PORTABILITY -These functions are described in the XSI Curses standard, Issue 4. -.SH SEE ALSO -\fB\%curses\fP(3X) +X/Open Curses, Issue 4, describes these functions. +.PP +SVr4 describes successful return values only as +\*(``an integer value other than \fBERR\fP\*(''. +.SH "SEE ALSO" +\fB\%curs_ins_wch\fP(3X) describes comparable functions in the +wide-character +.I curses +configuration. .PP -Comparable functions in the wide-character (ncursesw) library are -described in -\fB\%curs_ins_wch\fP(3X). +\fB\%curses\fP(3X), +\fB\%terminfo\fP(5) diff --git a/man/curs_legacy.3x b/man/curs_legacy.3x index a89337c2..b503991e 100644 --- a/man/curs_legacy.3x +++ b/man/curs_legacy.3x @@ -27,8 +27,19 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_legacy.3x,v 1.29 2023/10/21 10:28:36 tom Exp $ -.TH curs_legacy 3X 2023-10-21 "ncurses 6.4" "Library calls" +.\" $Id: curs_legacy.3x,v 1.30 2023/12/23 16:40:10 tom Exp $ +.TH curs_legacy 3X 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 '' "" +.\} +. .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 @@ -97,13 +108,23 @@ Except as noted, these functions return an integer, or \fBERR\fP if the window parameter is null. .SH NOTES -All of these interfaces are provided as macros and functions. -The macros are suppressed (and only the functions provided) -when \fB\%NCURSES_OPAQUE\fP is defined. -The standard forms such as \fB\%getyx\fP must be implemented as macros, -and (in this implementation) are defined in terms of the functions -described here, -to avoid reliance on internal details of the \fB\%WINDOW\fP structure. +All of these interfaces are implemented as macros and functions. +The macros are suppressed +(and only the functions provided) +in an \*(``opaque\*('' +.I \%ncurses +build, +which defines the preprocessor symbol +.BR \%NCURSES_OPAQUE . +See section \*(``ALTERNATE CONFIGURATIONS\*('' in \fB\%ncurses\fP(3X). +.PP +The standard forms such as \fB\%getyx\fP +.I must +be implemented as macros, +and +(in this implementation) +are defined in terms of the functions described here, +to avoid reliance on internal details of the \fI\%WINDOW\fP structure. .SH PORTABILITY These functions were supported on Version 7, BSD or System V implementations. None of those implementations checked the window parameter. diff --git a/man/curs_memleaks.3x b/man/curs_memleaks.3x index 77d05ac3..0f989502 100644 --- a/man/curs_memleaks.3x +++ b/man/curs_memleaks.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_memleaks.3x,v 1.32 2023/12/16 20:32:22 tom Exp $ -.TH curs_memleaks 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_memleaks.3x,v 1.33 2023/12/23 16:22:08 tom Exp $ +.TH curs_memleaks 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -114,7 +114,7 @@ In any implementation of X/Open Curses, an application can free part of the memory allocated by curses: .bP The portable part of \fB\%exit_curses\fP can be freed using \fB\%delscreen\fP, -passing the \fBSCREEN*\fP pointer returned by \fB\%newterm\fP. +passing the \fISCREEN\fP pointer returned by \fB\%newterm\fP. .IP In some implementations, there is a global variable \fBsp\fP which could be used, e.g., if the screen were only initialized diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x index 64c8e0f5..b7a2d829 100644 --- a/man/curs_mouse.3x +++ b/man/curs_mouse.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_mouse.3x,v 1.82 2023/12/16 21:08:16 tom Exp $ -.TH curs_mouse 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_mouse.3x,v 1.83 2023/12/23 20:37:56 tom Exp $ +.TH curs_mouse 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -106,7 +106,7 @@ current screen's mouse event mask. As a side effect, setting a zero mousemask may turn off the mouse pointer; setting a nonzero mask may turn it on. Whether this happens is device-dependent. -.SS Mouse events +.SS "Mouse Events" Here are the mouse event type masks which may be defined: .PP .TS @@ -261,29 +261,14 @@ returns the previous interval value, unless the terminal was not initialized. In that case, it returns the maximum interval value (166). .SH NOTES -The feature macro \fB\%NCURSES_MOUSE_VERSION\fP is provided so the preprocessor -can be used to test whether these features are present. -If the interface is changed, the value of \fB\%NCURSES_MOUSE_VERSION\fP will be -incremented. -These values for \fB\%NCURSES_MOUSE_VERSION\fP may be -specified when configuring \fI\%ncurses\fP: -.RS 3 -.TP 3 -1 -has definitions for reserved events. -The mask uses 28 bits. -.TP 3 -2 -adds definitions for button 5, -removes the definitions for reserved events. -The mask uses 29 bits. -.RE -.PP The order of the \fB\%MEVENT\fP structure members is not guaranteed. Additional fields may be added to the structure in the future. .PP -Under \fI\%ncurses\fP, these calls are implemented using either -xterm's built-in mouse-tracking API or +Under +.I \%ncurses, +these calls are implemented using either +.IR \%xterm 's +built-in mouse-tracking API or platform-specific drivers including .RS 3 .bP @@ -299,17 +284,25 @@ mouse events will not be visible to \fI\%ncurses\fP (and the \fB\%mousemask\fP function will always return \fB0\fP). .PP -If the terminfo entry contains a \fBXM\fP string, -this is used in the xterm mouse driver to control the +If the +.I \%term\%info +entry contains a \fBXM\fP string, +this is used in the +.I \%xterm +mouse driver to control the way the terminal is initialized for mouse operation. The default, if \fBXM\fP is not found, -corresponds to private mode 1000 of xterm: +corresponds to private mode 1000 of +.I \%xterm: .PP .RS 3 \eE[?1000%?%p1%{1}%=%th%el%; .RE .PP -The mouse driver also recognizes a newer xterm private mode 1006, e.g., +The mouse driver also recognizes a newer +.I \%xterm +private mode 1006, +e.g., .PP .RS 3 \eE[?1006;1000%?%p1%{1}%=%th%el%; @@ -323,19 +316,58 @@ for use with touch screens (which may be pressure-sensitive) or with The \fB\%ALL_MOUSE_EVENTS\fP class does not include \fB\%REPORT_MOUSE_POSITION\fP. They are distinct. -For example, in xterm, +For example, +in +.I \%xterm, wheel/scrolling mice send position reports as a sequence of presses of buttons 4 or 5 without matching button-releases. +.SH EXTENSIONS +These functions were designed for +\fB\%ncurses\fP(3X), +and are not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous curses implementation. +(SVr4 +.I curses +did have a +.I \%getmouse +function, +which took no argument and returned a different type.) .SH PORTABILITY -These calls were designed for \fI\%ncurses\fP, -and are not found in SVr4 \fIcurses\fP, -4.4BSD \fIcurses\fP, or any other previous version of \fIcurses\fP. +Applications employing the +.I \%ncurses +mouse extension should condition its use on the visibility of the +.B \%NCURSES_MOUSE_VERSION +preprocessor macro. +When the interface changes, +the macro's value increments. +Multiple versions are available when +.I \%ncurses +is configured; +see section \*(``ALTERNATE CONFIGURATIONS\*('' of \fB\%ncurses\fP(3X). +The following values may be specified. +.RS 3 +.TP 3 +1 +has definitions for reserved events. +The mask uses 28 bits. +.TP 3 +2 +adds definitions for button 5, +removes the definitions for reserved events. +The mask uses 29 bits. +.RE .PP -SVr4 \fIcurses\fP had support for the mouse in a variant of \fBxterm\fP(1). -It is mentioned in a few places, but with no supporting documentation: +SVr4 +.I curses +had support for the mouse in a variant of \fI\%xterm\fP(1). +It is mentioned in a few places, +with little supporting documentation. .bP -the \*(``libcurses\*('' manual page lists functions for this feature -which are prototyped in \fBcurses.h\fP: +Its \*(``libcurses\*('' manual page lists functions for this feature +prototyped in \fI\%curses.h\fP. .PP .RS 8 .EX @@ -349,7 +381,7 @@ extern unsigned long getmouse(void), getbmap(void); .EE .RE .bP -the \*(``terminfo\*('' manual page lists capabilities for the feature +Its \*(``terminfo\*('' manual page lists capabilities for the feature. .PP .RS 8 .EX @@ -361,56 +393,81 @@ req_mouse_pos reqmp RQ Request mouse position report .EE .RE .bP -the interface made assumptions (as does \fI\%ncurses\fP) -about the escape sequences -sent to and received from the terminal. +The interface made assumptions +(as does +.IR \%ncurses ) +about the escape sequences sent to and received from the terminal. .IP -For instance -the SVr4 \fIcurses\fP library used the \fB\%get_mouse\fP capability to tell the -terminal which mouse button events it should send, +For instance, +the SVr4 +.I curses +library used the \fB\%get_mouse\fP capability to tell the terminal which +mouse button events it should send, passing the mouse-button bit mask to the terminal. Also, it could ask the terminal where the mouse was using the \fB\%req_mouse_pos\fP capability. .IP -Those features required a terminal which had been modified -to work with \fIcurses\fP. -They were not part of the X Consortium's xterm. +Those features required a terminal program that had been modified +to work with SVr4 +.I curses. +They were not part of the X Consortium's +.I \%xterm. .PP -When developing the xterm mouse support for \fI\%ncurses\fP in September -1995, +When developing the +.I \%xterm +mouse support for +.I \%ncurses +in September 1995, Eric Raymond was uninterested in using the same interface due to its lack of documentation. Later, in 1998, Mark Hesseling provided support in -PDCurses 2.3 using the SVr4 interface. -PDCurses, however, does not use video terminals, +.I \%PDCurses +2.3 using the SVr4 interface. +.I \%PDCurses, +however, +does not use video terminals, making it unnecessary to be concerned about compatibility with the escape sequences. .SH BUGS -Mouse events from \fI\%xterm\fP are \fInot\fP ignored in cooked mode if -they have been enabled by \fB\%mousemask\fP. +Mouse events from +.I \%xterm +are +.I not +ignored in cooked mode if they have been enabled by \fB\%mousemask\fP. Instead, -the \fI\%xterm\fP mouse report sequence appears in the string read. +the +.I \%xterm +mouse report sequence appears in the string read. .PP -Mouse event reports from \fI\%xterm\fP are not detected correctly in -a window with keypad application mode disabled, +Mouse event reports from +.I \%xterm +are not detected correctly in a window with keypad application mode +disabled, since they are interpreted as a variety of function key. -Set the the terminal's \fI\%terminfo\fP capability \fB\%kmous\fP to -\*(``\eE[M\*('' -(the beginning of the response from \fI\%xterm\fP for mouse clicks). +Set the terminal's +.I \%term\%info +capability \fB\%kmous\fP to \*(``\eE[M\*('' +(the beginning of the response from +.I \%xterm +for mouse clicks). Other values of \fB\%kmous\fP are permitted under the same assumption, that is, the report begins with that sequence. .PP Because there are no standard response sequences that serve to identify -terminals supporting the \fI\%xterm\fP mouse protocol, -\fI\%ncurses\fP assumes that if \fB\%kmous\fP is defined in the terminal -description, +terminals supporting the +.I \%xterm +mouse protocol, +.I \%ncurses +assumes that if \fB\%kmous\fP is defined in the terminal description, or if the terminal type's primary name or aliases contain the string \%\*(``xterm\*('', then the terminal may send mouse events. The \fB\%kmous\fP capability is checked first, -allowing use of newer \fI\%xterm\fP mouse protocols such as its private -mode 1006. +allowing use of newer +.I \%xterm +mouse protocols, +such as its private mode 1006. .SH SEE ALSO \fB\%curses\fP(3X), \fB\%curs_inopts\fP(3X), diff --git a/man/curs_print.3x b/man/curs_print.3x index 16fac2dd..d98104a2 100644 --- a/man/curs_print.3x +++ b/man/curs_print.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_print.3x,v 1.35 2023/12/16 20:32:22 tom Exp $ -.TH curs_print 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_print.3x,v 1.36 2023/12/23 16:36:18 tom Exp $ +.TH curs_print 3X 2023-12-23 "ncurses 6.4" "Library calls" .SH NAME \fB\%mcprint\fP \- write binary data to printer using \fIterminfo\fR capabilities @@ -66,13 +66,20 @@ Couldn't allocate sufficient memory to buffer the printer write. .PP When \fB\%mcprint\fP succeeds, it returns the number of characters actually sent to the printer. +.SH EXTENSIONS +\fB\%mcprint\fP was designed for +\fB\%ncurses\fP(3X), +and was not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous curses implementation. .SH PORTABILITY -The \fB\%mcprint\fP call was designed for \fI\%ncurses\fP, -and is not found in SVr4 \fIcurses\fP, -4.4BSD \fIcurses\fP, -or any other previous version of \fIcurses\fP. -It is recommended that any code depending on \fI\%ncurses\fP extensions -be conditioned using \fB\%NCURSES_VERSION\fP. +Applications employing this +.I \%ncurses +extension should condition its use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. .SH BUGS Padding in the \fBmc5p\fP, diff --git a/man/curs_printw.3x b/man/curs_printw.3x index ea3a6b58..15dd10b5 100644 --- a/man/curs_printw.3x +++ b/man/curs_printw.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_printw.3x,v 1.45 2023/12/18 00:03:28 tom Exp $ -.TH curs_printw 3X 2023-12-17 "ncurses 6.4" "Library calls" +.\" $Id: curs_printw.3x,v 1.47 2023/12/23 14:41:07 tom Exp $ +.TH curs_printw 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -132,7 +132,7 @@ and specified \fB\%vw_printw\fP using the \fI\%stdarg.h\fP interface. .bP X/Open Curses, Issue 5, Draft 2 (December 2007) marked \fBvwprintw\fP (along with -\fBvwscanw\fP and the termcap interface) as withdrawn. +\fBvwscanw\fP and the \fItermcap\fP interface) as withdrawn. After incorporating review comments, this became X/Open Curses, Issue 7 (2009). diff --git a/man/curs_scanw.3x b/man/curs_scanw.3x index 333263d2..cf1977ac 100644 --- a/man/curs_scanw.3x +++ b/man/curs_scanw.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_scanw.3x,v 1.44 2023/12/17 22:50:40 tom Exp $ -.TH curs_scanw 3X 2023-12-17 "ncurses 6.4" "Library calls" +.\" $Id: curs_scanw.3x,v 1.47 2023/12/23 14:41:50 tom Exp $ +.TH curs_scanw 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -140,7 +140,7 @@ and specified \fB\%vw_scanw\fP using the \fI\%stdarg.h\fP interface. .bP X/Open Curses, Issue 5, Draft 2 (December 2007) marked \fB\%vwscanw\fP (along with -\fB\%vwscanw\fP and the termcap interface) as withdrawn. +\fB\%vwscanw\fP and the \fItermcap\fP interface) as withdrawn. After incorporating review comments, this became X/Open Curses, Issue 7 (2009). @@ -220,10 +220,10 @@ SVr3 (1987) added \fB\%mvwscanw\fP, stating .RS .PP -These routines correspond to \fIscanf\fP(3S), +\*(``[t]hese routines correspond to \fIscanf\fP(3S), as do their arguments and return values. \fB\%wgetstr\fP() is called on the window, -and the resulting line is used as input for the scan. +and the resulting line is used as input for the scan.\*('' .RE .PP SVr3 also implemented \fB\%vwscanw\fP, diff --git a/man/curs_sp_funcs.3x b/man/curs_sp_funcs.3x index 730ce37c..7f4be401 100644 --- a/man/curs_sp_funcs.3x +++ b/man/curs_sp_funcs.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_sp_funcs.3x,v 1.45 2023/12/16 20:32:22 tom Exp $ -.TH curs_sp_funcs 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_sp_funcs.3x,v 1.46 2023/12/23 16:26:05 tom Exp $ +.TH curs_sp_funcs 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -215,13 +215,13 @@ This implementation can be configured to provide a set of functions which improve the ability to manage multiple screens. This feature can be added to any of the configurations supported by \fI\%ncurses\fP; -it adds new entrypoints +it adds new symbols without changing the meaning of any of the existing ones. .\" *************************************************************************** -.SS IMPROVED FUNCTIONS +.SS "Improved Functions" Most of the functions are new versions of existing functions. A parameter is added at the front of the parameter list. -It is a SCREEN pointer. +It is a \fISCREEN\fP pointer. .PP The existing functions all use the current screen, which is a static variable. @@ -229,7 +229,7 @@ The extended functions use the specified screen, thereby reducing the number of variables which must be modified to update multiple screens. .\" *************************************************************************** -.SS NEW FUNCTIONS +.SS "New Functions" Here are the new functions: .TP 5 ceiling_panel @@ -245,8 +245,8 @@ With the screen-pointer extension, there are situations where it must create a current screen before the unextended library does. The \fBnew_prescr\fP function is used internally to handle these cases. -It is also provided as an entrypoint to allow applications to customize -the library initialization. +It is also provided to allow applications to customize library +initialization. .\" *************************************************************************** .SH NOTES This extension introduces some new names: diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x index 657c8335..464209f9 100644 --- a/man/curs_termcap.3x +++ b/man/curs_termcap.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_termcap.3x,v 1.76 2023/12/18 00:22:30 tom Exp $ -.TH curs_termcap 3X 2023-12-17 "ncurses 6.4" "Library calls" +.\" $Id: curs_termcap.3x,v 1.80 2023/12/23 20:19:05 tom Exp $ +.TH curs_termcap 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -87,12 +87,12 @@ entries for which a \fI\%term\%info\fP entry has been compiled. \fB\%tgetent\fP loads the terminal database entry for \fIname\fP; see \fBterm\fP(7). This must be done before calling any of the other functions. -It returns: +It returns .RS 3 -.TP 4 +.TP 5 \" "-1" + 2n + adjust for PDF 1 on success, -.TP 4 +.TP 0 if there is no such entry (or if the matching entry describes a generic terminal, @@ -100,7 +100,7 @@ having too little information for .I curses applications to run), and -.TP 4 +.TP \-1 if the \fI\%term\%info\fP database could not be found. .RE @@ -120,9 +120,9 @@ which is not the same thing. .bP The meanings of the return values differ. The BSD \fItermcap\fP library does not check whether the terminal type -description is marked with the -.B gn -.RB ( \%generic ) +description includes the +.B \%generic +.RB ( gn ) capability, nor whether the terminal type description supports an addressable cursor, @@ -189,13 +189,13 @@ Doing so reveals a quirk in \fB\%tgoto\fP: most hardware terminals use cursor addressing with \fIrow\fP first, but the original developers of the \fItermcap\fP interface chose to put the \fIcol\fP (column) parameter first. -The \fB\%tgoto\fP function swaps the order of parameters. +The \fB\%tgoto\fP function swaps the order of its parameters. It does this even for calls requiring only a single parameter. In that case, the first parameter is merely a placeholder. .bP Normally the \fI\%ncurses\fP library is compiled without -full \fI\%term\%cap\fP support. +full \fI\%termcap\fP support. In that case, \fB\%tgoto\fP uses an internal version of \fB\%tparm\fP(3X) (a more capable function). @@ -214,7 +214,7 @@ availability. .PP \fB\%tputs\fP is described in \fB\%curs_terminfo\fP(3X). It can retrieve capabilities by either \fItermcap\fP or -\fI\%term\%info\fP name. +\fI\%term\%info\fP code. .SS "Global Variables" The variables \fBPC\fP, @@ -249,9 +249,8 @@ del_curterm(cur_term); to free this memory, but there is an additional complication with \fI\%ncurses\fP. It uses a fixed-size pool of storage locations, -one per value of the \fITERM\fP environment variable when -\fB\%tgetent\fP is called. -The \fBscreen\fP(1) program relies upon this arrangement to improve its +one per value of the terminal name parameter given to \fB\%tgetent\fP. +The \fIscreen\fP(1) program relies upon this arrangement to improve its performance. .PP An application that uses only the \fItermcap\fP functions, @@ -308,17 +307,16 @@ They should not be used in new programs. .SS Standards .bP X/Open Curses, Issue 4, Version 2 (1996), -describes these functions. -However, -they are marked +describes these functions, +marking them as \*(``TO BE WITHDRAWN\*(''. .bP -X/Open Curses, Issue 7 (2009) marked the \fItermcap\fP interface +X/Open Curses, Issue 7 (2009) marks the \fItermcap\fP interface (along with \fB\%vwprintw\fP and \fB\%vwscanw\fP) as withdrawn. .PP Neither X/Open Curses nor the SVr4 man pages documented the return values of \fB\%tgetent\fP correctly, -though all three were in fact returned ever since SVr1. +though all three shown here were in fact returned ever since SVr1. In particular, an omission in the X/Open Curses specification has been misinterpreted to mean that \fB\%tgetent\fP returns \fBOK\fP or \fBERR\fP. @@ -411,20 +409,20 @@ The library remained much the same though 4.3BSD (June 1986). 4.4BSD-Lite (June 1994) -refactored it +refactored it, .\" Observe the `tncktc()`, `tnamatch()`, `tskip()`, and `tdecode()` .\" entry points disappearing from termcap.c. -but left the API unchanged. +leaving the API unchanged. .PP -Function prototypes were a feature of the forthcoming ANSI C (1989). -Thus the library provided no header file declaring them. +Function prototypes were a feature of ANSI C (1989). +Thus the library itself provided no header file declaring them. Nevertheless, the BSD sources included two different \fI\%termcap.h\fP header files over time. .bP One was used internally by \fBjove\fP(1) from 4.3BSD onward. .\" 2BSD became a branch retaining support for non-virtual memory -.\" systems (like the PDP-11) whereas most BSD development focused on +.\" systems (such as the PDP-11) whereas most BSD development focused on .\" the VAX and other VM-enabled systems starting with 3BSD. .\" .\" This man page previously located a termcap.h in 2BSD, but that may @@ -461,8 +459,8 @@ The prototype for \fB\%tputs\fP also differed, but in that instance, it was \fIlibedit\fP that differed from BSD \fItermcap\fP. .PP -GNU \fItermcap\fP 1.3 was bundled with \fIbash\fP in mid-1993 to support -the \fBreadline\fP(3) library. +GNU \fItermcap\fP 1.3 was bundled with \fIbash\fP(1) in mid-1993 to +support the \fI\%readline\fP(3) library. .PP \fI\%ncurses\fP 1.8.1 (November 1993) @@ -486,8 +484,10 @@ Any two of the four implementations thus differ, and programs that intend to work with all \fItermcap\fP library interfaces must account for that fact. .SH BUGS -If you call \fB\%tgetstr\fP to fetch \fB\%ca\fP or any other -parameterized string capability, +If you call \fB\%tgetstr\fP to fetch +.B \%column_address +.RB ( ch ) +or any other parameterized string capability, be aware that it is returned in \fI\%term\%info\fP notation, not the older and not-quite-compatible \fItermcap\fP notation. This does not cause problems if all you do with it is call \fB\%tgoto\fP @@ -521,11 +521,16 @@ looking for digits at the beginning of the string. \fB\%tputs("50")\fP in a \fItermcap\fP system may busy-wait for 50 milliseconds rather than transmitting \*(``50\*(''. .PP -\fItermcap\fP has nothing analogous to \fI\%term\%info\fP's \fBsgr\fP -string. +\fItermcap\fP has nothing analogous to \fI\%term\%info\fP's +.B \%set_attributes +.RB ( sgr ) +capability. One consequence is that \fItermcap\fP applications assume that .RB \*(`` me \*('' -(equivalent to \fI\%term\%info\fP's \fBsgr0\fP capability) +(equivalent to \fI\%term\%info\fP's +.B \%exit_attribute_mode +.RB ( sgr0 ) +capability) does not reset the alternate character set. \fI\%ncurses\fP checks for, and modifies the data shared with, diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index aeee9db8..88f5b97f 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_terminfo.3x,v 1.123 2023/12/16 21:11:53 tom Exp $ -.TH curs_terminfo 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_terminfo.3x,v 1.124 2023/12/23 17:34:39 tom Exp $ +.TH curs_terminfo 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -111,6 +111,9 @@ \fI/* extensions */ \fBchar *tiparm_s(int \fIexpected\fP, int \fImask\fP, const char *\fIstr\fP, ...); \fBint tiscan_s(int *\fIexpected\fP, int *\fImask\fP, const char *\fIstr\fP); +.PP +\fI/* deprecated */ +\fBint setterm(const char *\fIterm\fP); .fi .SH DESCRIPTION These low-level routines must be called by programs that have to deal @@ -244,7 +247,7 @@ which uses all the defaults and sends the output to \fBstdout\fP. .\" *************************************************************************** .SS "The Terminal State" The \fBsetupterm\fP routine stores its information about the terminal -in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP. +in a \fI\%TERMINAL\fP structure pointed to by the global variable \fBcur_term\fP. If it detects an error, or decides that the terminal is unsuitable (hardcopy or generic), it discards this information, @@ -339,14 +342,14 @@ which happens to share this function name with the \fIterminfo\fP interface. \fIaffcnt\fP is the number of lines affected, or 1 if not applicable. .bP -\fIputc\fP is a \fBputchar\fP-like routine to which +\fIputc\fP is a \fI\%putchar\fP-like function to which the characters are passed, one at a time. .IP If \fBtputs\fP processes a time-delay, it uses the \fBdelay_output\fP(3X) function, routing any resulting padding characters through this function. .PP -The \fBputp\fR routine calls \fBtputs(\fIstr\fB, 1, putchar)\fR. +The \fBputp\fR routine calls \fBtputs(\fIstr\fB, 1, \%putchar)\fR. The output of \fBputp\fP always goes to \fBstdout\fP, rather than the \fIfiledes\fP specified in \fBsetupterm\fP. .PP @@ -354,10 +357,10 @@ The \fBvidputs\fP routine displays the string on the terminal in the video attribute mode \fIattrs\fP, which is any combination of the attributes listed in \fBcurses\fP(3X). The characters are passed to -the \fBputchar\fP-like routine \fIputc\fP. +the \fI\%putchar\fP-like function \fIputc\fP. .PP The \fBvidattr\fP routine is like the \fBvidputs\fP routine, except -that it outputs through \fBputchar\fP. +that it outputs through \fI\%putchar\fP. .PP The \fBvid_attr\fP and \fBvid_puts\fP routines correspond to vidattr and vidputs, respectively. @@ -464,7 +467,7 @@ See \fBterminfo\fP(5) for details. to improve performance, \fI\%ncurses\fP 6.3 caches the result of analyzing terminfo strings for their parameter types. -That is stored as a binary tree referenced from the \fBTERMINAL\fP structure. +That is stored as a binary tree referenced from the \fI\%TERMINAL\fP structure. .PP The higher-level \fBinitscr\fP and \fBnewterm\fP functions use \fBsetupterm\fP. Normally they do not free this memory, but it is possible to do that using @@ -512,42 +515,75 @@ of the output function \fIputc\fP. .RE .\" *************************************************************************** .SH NOTES -X/Open notes that \fBvidattr\fP and \fBvidputs\fP may be macros. +.\" See X/Open Curses Issue 4, Version 2, pp. 227-234. +.\" See X/Open Curses Issue 7, pp. 311-318. +According to X/Open Curses, +any of the \fIenhanced curses\fP functions may be implemented as macros. +The term \*(``enhanced\*('' refers to features not found in SVr4 curses. +.PP +\fB\%ncurses\fP uses macros +.bP +for functions which return values via their parameters, +.bP +to support obsolete features, +.bP +to reuse functions, +e.g., those that move the cursor before another operation, and +.bP +a few special cases. +.PP +The \fB\%vid_puts\fP function in \fB\%ncurses\fP is a special case. +It was originally implemented based on a draft of X/Open Curses, +as a macro, +before other parts of the \fB\%ncurses\fP wide-character API were developed. .\" *************************************************************************** .SH EXTENSIONS The functions marked as extensions were designed for \fB\%ncurses\fP(3X), -and are not found in SVr4 curses, 4.4BSD curses, -or any other previous version of curses. +and are not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous curses implementation. .\" *************************************************************************** .SH PORTABILITY -The function \fBsetterm\fP is not described by X/Open and must -be considered non-portable. +\fBsetterm\fP is not described by X/Open and must be considered +non-portable. All other functions are as described by X/Open. .SS "Compatibility Macros" This implementation provides a few macros for compatibility with systems -before SVr4 (see \fIHISTORY\fP). -Those include -\fBcrmode\fP, -\fBfixterm\fP, -\fBgettmode\fP, -\fBnocrmode\fP, -\fBresetterm\fP, -\fBsaveterm\fP, and -\fBsetterm\fP. -.PP -In SVr4, those are found in \fB\fP, -but except for \fBsetterm\fP, are likewise macros. -The one function, \fBsetterm\fP, is mentioned in the manual page. -The manual page notes that the \fBsetterm\fP routine -was replaced by \fB\%setupterm\fP, stating that the call -.IP -\fBsetupterm(\fIterm\fB, 1, (int *)0)\fR -.PP +before SVr4 +(see section \*(``HISTORY\*('' below). +They include +\fB\%Bcrmode\fP, +\fB\%Bfixterm\fP, +\fB\%Bgettmode\fP, +\fB\%Bnocrmode\fP, +\fB\%Bresetterm\fP, +\fB\%Bsaveterm\fP, and +\fB\%Bsetterm\fP. +.PP +In SVr4, +these are found in +.IR \%curses.h , +but except for \fB\%setterm\fP, +are likewise macros. +The one function, +\fB\%setterm\fP, +is mentioned in the manual page. +It further notes that \fB\%setterm\fP was replaced by \fB\%setupterm\fP, +stating that the call +.RS +.EX +setupterm(\fIterm\fB, 1, (int *)0)\fP +.EE +.RE provides the same functionality as \fBsetterm(\fIterm\fB)\fR, -and is not recommended for new programs. -This implementation provides each of those symbols -as macros for BSD compatibility. +discouraging the latter for new programs. +.I \%ncurses +implements each of these symbols as macros for BSD +.I curses +compatibility. .SS "Legacy Data" \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP. This is not part of X/Open Curses, but is assumed by some applications. @@ -664,7 +700,7 @@ X/Open notes that after calling \fBmvcur\fP, the curses state may not match the actual terminal state, and that an application should touch and refresh the window before resuming normal curses calls. Both \fI\%ncurses\fP and System V Release 4 curses implement \fBmvcur\fP -using the SCREEN data allocated in either \fBinitscr\fP or +using the \fISCREEN\fP data allocated in either \fBinitscr\fP or \fBnewterm\fP. So though it is documented as a terminfo function, \fBmvcur\fP is really a curses function which is not well specified. @@ -686,7 +722,8 @@ fixterm restore tty to \*(``in curses\*('' state gettmode establish current tty modes mvcur low level cursor motion putp T{ -utility function that uses \fBtputs\fP to send characters via \fBputchar\fP. +utility function that uses \fBtputs\fP to send characters via +\fI\%putchar\fP. T} resetterm set tty modes to \*(``out of curses\*('' state resetty reset tty flags to stored value @@ -696,7 +733,7 @@ setterm establish terminal with given type setupterm establish terminal with given type tparm instantiate a string expression with parameters tputs apply padding information to a string -vidattr like \fBvidputs\fP, but outputs through \fBputchar\fP +vidattr like \fBvidputs\fP, but outputs through \fIputchar\fP vidputs T{ output a string to put terminal in a specified video attribute mode T} @@ -722,7 +759,7 @@ T} .TE .PP Early terminfo programs obtained capability values from the -\fBTERMINAL\fP structure initialized by \fBsetupterm\fP. +\fI\%TERMINAL\fP structure initialized by \fBsetupterm\fP. .PP SVr3 extended terminfo by adding functions to retrieve capability values (like the termcap interface), @@ -766,7 +803,7 @@ SVr3 introduced the functions for switching between terminal descriptions, e.g., \fBset_curterm\fP. Some of that was incremental improvements to the SVr2 library: .bP -The \fBTERMINAL\fP type definition was introduced in SVr3.01, +The \fI\%TERMINAL\fP type definition was introduced in SVr3.01, for the \fBterm\fP structure provided in SVr2. .bP The various global variables such as \fBboolnames\fP were mentioned diff --git a/man/curs_threads.3x b/man/curs_threads.3x index c0675b16..1e425440 100644 --- a/man/curs_threads.3x +++ b/man/curs_threads.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_threads.3x,v 1.50 2023/12/16 20:32:22 tom Exp $ -.TH curs_threads 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_threads.3x,v 1.51 2023/12/23 16:22:25 tom Exp $ +.TH curs_threads 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -122,7 +122,7 @@ Other global variables are not modifiable. .PP The \fBuse_window\fP and \fBuse_screen\fP functions provide coarse-grained mutexes for their respective \fI\%WINDOW\fP and -\fI\%SCREEN\fP parameters; +\fISCREEN\fP parameters; they call a user-supplied function, pass it a \fIdata\fP parameter, and return the value from the user-supplied function to the application. diff --git a/man/curs_trace.3x b/man/curs_trace.3x index 09e78778..2a55275c 100644 --- a/man/curs_trace.3x +++ b/man/curs_trace.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_trace.3x,v 1.41 2023/12/16 20:50:14 tom Exp $ -.TH curs_trace 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_trace.3x,v 1.42 2023/12/23 16:08:25 tom Exp $ +.TH curs_trace 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -127,7 +127,7 @@ When the trace mask is nonzero, If the file already exists, no tracing is done. .bP If tracing is not available, \fBcurses_trace\fP returns zero (0). -.SS Trace Parameter +.SS "Trace Parameter" The trace parameter is formed by OR'ing values from the list of \fBTRACE_\fIxxx\fR definitions in \fB\fR. These include: @@ -211,7 +211,7 @@ use_env, use_extended_names, use_tioctl .RE -.SS Command-line Utilities +.SS "Command-line Utilities" The command-line utilities such as \fBtic\fP(1) provide a verbose option which extends the set of messages written using the \fBcurses_trace\fP function. Both of these (\fB\-v\fP and \fBcurses_trace\fP) diff --git a/man/curs_util.3x b/man/curs_util.3x index d38078dc..e5f96738 100644 --- a/man/curs_util.3x +++ b/man/curs_util.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_util.3x,v 1.91 2023/12/16 20:32:22 tom Exp $ -.TH curs_util 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_util.3x,v 1.92 2023/12/23 16:24:15 tom Exp $ +.TH curs_util 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -246,7 +246,7 @@ data. It returns a pointer to the new window. There are a few caveats: .bP -the data written is a copy of the \fBWINDOW\fP structure, +the data written is a copy of the \fI\%WINDOW\fP structure, and its associated character cells. The format differs between the wide-character (\fI\%ncursesw\fP) and non-wide (\fI\%ncurses\fP) libraries. @@ -347,7 +347,7 @@ the University of California, Berkeley (in 1982) and were later (in 1988) incorporated into SVr4. Oddly, there are no such functions in the 4.3BSD curses sources. .bP -Most implementations simply dump the binary \fBWINDOW\fP structure to the file. +Most implementations simply dump the binary \fI\%WINDOW\fP structure to the file. These include SVr4 curses, NetBSD and PDCurses, as well as older \fI\%ncurses\fP versions. This implementation diff --git a/man/curs_variables.3x b/man/curs_variables.3x index e5265ab1..02d1b148 100644 --- a/man/curs_variables.3x +++ b/man/curs_variables.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_variables.3x,v 1.35 2023/12/16 21:05:52 tom Exp $ -.TH curs_variables 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_variables.3x,v 1.40 2023/12/23 23:10:13 tom Exp $ +.TH curs_variables 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -53,20 +53,21 @@ \fI\%chtype\fP, \fI\%cchar_t\fP, \fI\%attr_t\fP, +\fI\%SCREEN\fP, \fI\%WINDOW\fP, \fB\%TRUE\fP, \fB\%FALSE\fP, \fB\%ERR\fP, \fB\%OK\fP, +\fB\%curscr\fP, +\fB\%newscr\fP, +\fB\%stdscr\fP, \fB\%COLORS\fP, \fB\%COLOR_PAIRS\fP, \fB\%COLS\fP, -\fB\%ESCDELAY\fP, \fB\%LINES\fP, -\fB\%TABSIZE\fP, -\fB\%curscr\fP, -\fB\%newscr\fP, -\fB\%stdscr\fP \- +\fB\%ESCDELAY\fP, +\fB\%TABSIZE\fP \- \fIcurses\fR data types, constants, and global variables .SH SYNOPSIS .nf @@ -77,6 +78,7 @@ \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP chtype; \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP cchar_t; \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP attr_t; +\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP SCREEN; \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP WINDOW; .PP \fI/* constants */ @@ -87,12 +89,13 @@ \fBconst \fI/*\fP .\|.\|. \fI*/\fP OK; .PP \fI/* variables */ -\fBint COLOR_PAIRS; \fBint COLORS; +\fBint COLOR_PAIRS; \fBint COLS; \fBint LINES; \fBWINDOW * curscr; \fBWINDOW * stdscr; +.PP \fI/* extensions */ \fBint ESCDELAY; \fBint TABSIZE; @@ -111,16 +114,24 @@ that provide read-only access to the library's state. In either case, applications should treat them as read-only to avoid confusing the library. -.SS \fIbool\fP, TRUE, FALSE -X/Open Issue 4 \fIcurses\fP (1996) preceded the ISO C99 and ISO C++98 -standards, -each of which also defined a Boolean data type. -The \fIcurses\fP library requires an integral type \fIbool\fP and -constants \fBTRUE\fP and \fBFALSE\fP to store its two possible values. +.SH "CONSTANTS" +.SS "TRUE, FALSE" +The \fIcurses\fP library defines \fBTRUE\fP and \fBFALSE\fP +to represent the values of the Boolean data type. .SS ERR, OK \fIcurses\fP and \fIterminfo\fP routines frequently return these constant integral values indicating failure and success, respectively. +.SH "PREDEFINED TYPES" +.SS \fIbool\fP +X/Open Issue 4 \fIcurses\fP (1996) preceded the ISO C99 and ISO C++98 +standards, +each of which also defined a Boolean data type. +The \fIcurses\fP library requires an integral type \fIbool\fP. +.PP +\fB\%ncurses\fP' configure script attempts to discover the +data type used by the system's C and C++ compilers, +to reuse for the \fIcurses\fP \fIbool\fP. .SS \fIchtype\fP The \fI\%chtype\fP integral type combines a (\*(``narrow\*('', @@ -151,30 +162,59 @@ for example, \fB\%attr_on\fP(3X), and \fB\%in_wch\fP(3X). -.SS COLOR_PAIRS -Once \fIcurses\fP is initialized, -\fB\%COLOR_PAIRS\fP -contains the number of color pairs supported by the terminal. -Often, -its value is the product \fB\%COLORS\fP \(mu \fB\%COLORS\fP, -but this is not always true. -.bP -A few terminals use HLS colors, -ignoring this rule; +.SS \fISCREEN\fP +.I curses +manages a terminal device with this structure type; +see \fB\%initscr\fP(3X). +.SS "\fIWINDOW\fP" +.I curses +represents rectangular portions of the terminal screen with the +.I \%WINDOW +structure type; +see subsection \*(``Overview\*('' of \fB\%ncurses\fP(3X). +.SH "VARIABLES" +.SS "curscr, stdscr, newscr" +The library records updates to the terminal screen in a window named +\fB\%curscr\fP. +This object is referred to as the \*(``physical screen\*('' in +\fB\%curs_refresh\fP(3X) and +\fB\%curs_outopts\fP(3X). +.PP +\fI\%ncurses\fP collects pending updates to the terminal screen in a +window named \fB\%newscr\fP. +This object is referred to as the \*(``virtual screen\*('' in the +\fB\%curs_kernel\fP(3X), +\fB\%curs_refresh\fP(3X), and -.bP -terminals supporting a large number of colors are limited by the number -of color pairs that a \fIsigned short\fP value can represent. +\fB\%curs_outopts\fP(3X). +When the screen is refreshed, +\fIcurses\fP determines a minimal set of updates using the terminal's +capabilities to make \fB\%curscr\fP look like \fB\%newscr\fP. +.PP +Once \fIcurses\fP is initialized, +it creates a window named \fB\%stdscr\fP. +It is the same size as the terminal screen and is the default window +used by routines that do not take a parameter identifying one. +Many \fIcurses\fP functions use this window. .SS COLORS Once \fIcurses\fP is initialized, \fB\%COLORS\fP -contains the number of colors supported by the terminal. -.SS COLS +contains the number of colors supported by the terminal; +see \fB\%curs_color\fP(3X). +.SS COLOR_PAIRS Once \fIcurses\fP is initialized, -\fB\%COLS\fP -contains the screen's width in character cells; +\fB\%COLOR_PAIRS\fP +contains the number of color pairs supported by the terminal; +see \fB\%curs_color\fP(3X). +.SS "COLS, LINES" +Once \fIcurses\fP is initialized, +.B \%COLS +and +.B LINES +contain the screen's width and height in character cells, +respectively; that is, -the number of columns. +the number of columns and lines. .SS ESCDELAY For \fIcurses\fP to distinguish an escape character corresponding to a user's press of an \*(``Escape\*('' key on the input device from one @@ -184,41 +224,10 @@ the library waits to see if another key event occurs after the escape character. \fB\%ESCDELAY\fP stores this interval in milliseconds. -.SS LINES -Once \fIcurses\fP is initialized, -\fB\%LINES\fP -contains the screen's height in character cells; -that is, -the number of lines. .SS TABSIZE The \fIcurses\fP library converts a tab character to this number of spaces as it adds a tab to a window; see \fB\%curs_addch\fP(3X). -.SS curscr -\fIcurses\fP records updates to the terminal screen in a \fI\%WINDOW\fP -structure named \fB\%curscr\fP. -.PP -This object is referred to as the \*(``physical screen\*('' in -\fB\%curs_refresh\fP(3X) and -\fB\%curs_outopts\fP(3X). -.SS newscr -\fI\%ncurses\fP collects pending updates to the terminal screen in a -\fI\%WINDOW\fP structure named \fB\%newscr\fP. -.PP -This object is referred to as the \*(``virtual screen\*('' in the -\fB\%curs_kernel\fP(3X), -\fB\%curs_refresh\fP(3X), -and -\fB\%curs_outopts\fP(3X). -When the screen is refreshed, -\fIcurses\fP determines a minimal set of updates using the terminal's -capabilities to make \fB\%curscr\fP look like \fB\%newscr\fP. -.SS stdscr -Once \fIcurses\fP is initialized, -it creates a \fI\%WINDOW\fP structure named \fB\%stdscr\fP. -It is the same size as the terminal screen and is the default window -used by routines that do not take a parameter identifying one. -Many \fIcurses\fP functions use this window. .SH NOTES Either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) initializes \fIcurses\fP. @@ -234,18 +243,20 @@ and \fB\%ESCDELAY\fP. .PP X/Open Curses describes \fB\%curscr\fP only as \*(``an internal data structure\*(''; -SVID gave more details, +SVr4 gave more details, noting its use \*(``for certain low-level operations like clearing and redrawing a screen containing garbage\*(''. +.\" SVID 4, Volume 3, p. 408 Neither specified its interaction with the rest of the interface beyond use as an argument to \fB\%clearok\fP(3X) and \fB\%wrefresh\fP(3X). .PP \fB\%newscr\fP is a feature of SVr4 \fIcurses\fP. -When refreshing the screen, this window is used as a working area -for combining the standard screen \fB\%stdscr\fP with any other windows -which the application may have created with \fB\%newwin\fP(3X). -When the updated \fB\%newscr\fP is complete, -\fIcurses\fP updates \fB\%curscr\fP to match \fB\%newscr\fP. +When refreshing the screen, +it is used as a working area for combining the standard window +\fB\%stdscr\fP with any others the application may have created with +\fB\%newwin\fP(3X). +When the update of \fB\%newscr\fP is complete, +\fIcurses\fP modifies \fB\%curscr\fP to match \fB\%newscr\fP. .PP \fB\%TABSIZE\fP is a feature of SVr4 \fIcurses\fP. .bP @@ -294,6 +305,7 @@ most users have decided either to override the value, or to rely upon its default. .SH SEE ALSO \fB\%curses\fP(3X), +\fB\%curs_color\fP(3X), \fB\%curs_opaque\fP(3X), \fB\%curs_terminfo\fP(3X), \fB\%curs_threads\fP(3X), diff --git a/man/form.3x b/man/form.3x index 51195293..f00dfbc9 100644 --- a/man/form.3x +++ b/man/form.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form.3x,v 1.51 2023/12/16 20:32:22 tom Exp $ -.TH form 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: form.3x,v 1.52 2023/12/23 16:08:25 tom Exp $ +.TH form 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -73,7 +73,7 @@ so that input/output processing will work. A curses initialization routine such as \fBinitscr\fP must be called before using any of these functions. . -.SS Current Default Values for Field Attributes +.SS "Current Default Values for Field Attributes" . The \fBform\fP library maintains a default value for field attributes. You @@ -84,7 +84,7 @@ Changing this default with a \fBset_\fP function affects future field creations, but does not change the rendering of fields already created. . -.SS Routine Name Index +.SS "Routine Name Index" . The following table lists each \fBform\fP routine and the name of the manual page on which it is described. diff --git a/man/form_driver.3x b/man/form_driver.3x index d8434a81..43b59b64 100644 --- a/man/form_driver.3x +++ b/man/form_driver.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: form_driver.3x,v 1.53 2023/11/25 13:58:47 tom Exp $ -.TH form_driver 3X 2023-11-25 "ncurses 6.4" "Library calls" +.\" $Id: form_driver.3x,v 1.54 2023/12/23 16:08:25 tom Exp $ +.TH form_driver 3X 2023-12-23 "ncurses 6.4" "Library calls" .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 @@ -67,7 +67,7 @@ returned by \fBget_wch\fP(3X). The type must be passed as well, to enable the library to determine whether the parameter is a wide character or a request. -.SS Form-driver requests +.SS "Form Driver Requests" The form driver requests are as follows: .PP .TS @@ -139,7 +139,7 @@ If the second argument is a printable character, the driver places it in the current position in the current field. If it is one of the forms requests listed above, that request is executed. -.SS Field validation +.SS "Field Validation" The form library makes updates to the window associated with form fields rather than directly to the field buffers. .PP @@ -166,7 +166,7 @@ In each case, the move fails if the field is invalid. If the modified field is valid, the form driver copies the modified data from the window associated with the field to the field buffer. -.SS Mouse handling +.SS "Mouse Handling" If the second argument is the KEY_MOUSE special key, the associated mouse event is translated into one of the above pre-defined requests. Currently only clicks in the user window (e.g., inside the form display @@ -213,7 +213,7 @@ into a request was done, \fBform_driver\fP returns the result of this request. If you clicked outside the user window or the mouse event could not be translated into a form request an \fBE_REQUEST_DENIED\fP is returned. -.SS Application-defined commands +.SS "Application-defined Commands" If the second argument is neither printable nor one of the above pre-defined form requests, the driver assumes it is an application-specific command and returns \fBE_UNKNOWN_COMMAND\fP. Application-defined commands diff --git a/man/infocmp.1m b/man/infocmp.1m index ffe2df3b..11241bde 100644 --- a/man/infocmp.1m +++ b/man/infocmp.1m @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: infocmp.1m,v 1.102 2023/12/16 20:32:22 tom Exp $ -.TH @INFOCMP@ 1M 2023-12-16 "ncurses 6.4" "User commands" +.\" $Id: infocmp.1m,v 1.103 2023/12/23 16:08:25 tom Exp $ +.TH @INFOCMP@ 1M 2023-12-23 "ncurses 6.4" "User commands" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -90,14 +90,14 @@ binary file (\fBterm\fP) in a variety of formats. In all cases, the boolean fields will be printed first, followed by the numeric fields, followed by the string fields. -.SS Default Options +.SS "Default Options" If no options are specified and zero or one \fIterminal-types\fP are specified, the \fB\-I\fP option will be assumed. If more than one \fIterminal-type\fP is specified, the \fB\-d\fP option will be assumed. -.SS Comparison Options [\-d] [\-c] [\-n] +.SS "Comparison Options [\-d] [\-c] [\-n]" \fB@INFOCMP@\fP compares the \fBterminfo\fP description of the first terminal \fIterminal-type\fP with each of the descriptions given by the entries for the other terminal's \fIterminal-types\fP. @@ -142,7 +142,7 @@ capabilities (names prefixed with \*(``OT\*(''). If no \fIterminal-types\fP are given, \fB@INFOCMP@\fP uses the environment variable \fITERM\fP for each of the \fIterminal-types\fP. -.SS Source Listing Options [\-I] [\-L] [\-C] [\-r] +.SS "Source Listing Options [\-I] [\-L] [\-C] [\-r]" The \fB\-I\fP, \fB\-L\fP, and \fB\-C\fP options will produce a source listing for each terminal named. .PP @@ -222,7 +222,7 @@ l l l. \fB%p1%?%'x'%>%t%p1%'y'%+%;/%>xy\fP/concept \fB%p2\fP is printed before \fB%p1/%r\fP/hp .TE -.SS Use= Option [\-u] +.SS "Use= Option [\-u]" The \fB\-u\fP option produces a \fBterminfo\fP source description of the first terminal \fIterminal-type\fP which is relative to the sum of the descriptions given by the entries for the other \fIterminal-types\fP. @@ -269,7 +269,7 @@ the compilation time, is specifying extra \fBuse=\fP fields that are superfluous. \fB@INFOCMP@\fP will flag any other \fIterminal-type use=\fP fields that were not needed. -.SS Changing Databases [\-A \fIdirectory\fR] [\-B \fIdirectory\fR] +.SS "Changing Databases [\-A \fIdirectory\fR] [\-B \fIdirectory\fR]" Like other \fI\%ncurses\fP utilities, \fB@INFOCMP@\fP looks for the terminal descriptions in several places. You can use the \fI\%TERMINFO\fP and \fI\%TERMINFO_DIRS\fP environment @@ -292,7 +292,7 @@ databases. For instance, you can use this feature for comparing descriptions for the same terminal created by different people. -.SS Other Options +.SS "Other Options" .TP 5 \fB\-0\fP causes the fields to be printed on one line, without wrapping. diff --git a/man/man_db.renames.in b/man/man_db.renames.in index 433ed5e4..7780b9d4 100644 --- a/man/man_db.renames.in +++ b/man/man_db.renames.in @@ -26,7 +26,7 @@ # use or other dealings in this Software without prior written # # authorization. # ############################################################################## -# $Id: man_db.renames.in,v 1.63 2023/12/17 23:52:59 tom Exp $ +# $Id: man_db.renames.in,v 1.66 2023/12/23 16:14:04 tom Exp $ # Manual-page renamings for the man_db program # # Files: @@ -151,7 +151,7 @@ mitem_value.3x menu_value.3menu mitem_visible.3x menu_visible.3menu ncurses.3x ncurses.3ncurses new_pair.3x new_pair.3ncurses -panel.3x panel.3curses +panel.3x panel.3ncurses printf.3s printf.3 putc.3s putc.3 resizeterm.3x resizeterm.3ncurses @@ -207,7 +207,7 @@ longname.3x longname.3ncurses meta.3x meta.3ncurses move.3x move.3ncurses mvcur.3x mvcur.3ncurses -mvwin.3x mvwin.3nwinses +mvwin.3x mvwin.3ncurses newpad.3x newpad.3ncurses newterm.3x newterm.3ncurses newwin.3x newwin.3ncurses @@ -240,7 +240,10 @@ wadd_wch.3x wadd_wch.3ncurses waddch.3x waddch.3ncurses waddstr.3x waddstr.3ncurses waddwstr.3x waddwstr.3ncurses +wattrset.3x wattrset.3ncurses +wattr_set.3x wattr_set.3ncurses wbkgdset.3x wbkgdset.3ncurses +wbkgrndset.3x wbkgrndset.3ncurses wget_wch.3x wget_wch.3ncurses wgetch.3x wgetch.3ncurses wgetstr.3x wgetstr.3ncurses @@ -253,7 +256,7 @@ wsetscrreg.3x wsetscrreg.3ncurses wtimeout.3x wtimeout.3ncurses # # Other: -getty.1 getty.8 +getty.8 getty.8 scanf.3 scanf.3 ttys.5 ttys.4 system.3 system.3 diff --git a/man/manhtml.aliases b/man/manhtml.aliases index 94732df5..dd099751 100644 --- a/man/manhtml.aliases +++ b/man/manhtml.aliases @@ -1,4 +1,4 @@ -# $Id: manhtml.aliases,v 1.29 2023/12/18 00:27:56 tom Exp $ +# $Id: manhtml.aliases,v 1.30 2023/12/23 21:21:06 tom Exp $ #*************************************************************************** # Copyright 2019-2022,2023 Thomas E. Dickey * # Copyright 2013,2017 Free Software Foundation, Inc. * @@ -57,6 +57,7 @@ inch(3X) curs_inch(3X) infocmp(1) infocmp(1M) initscr(3X) curs_initscr(3X) is_scrollok(3X) curs_opaque(3X) +keyname(3X) curs_util(3X) keypad(3X) curs_inopts(3X) longname(3X) curs_termattrs(3X) meta(3X) curs_inopts(3X) @@ -89,7 +90,10 @@ wadd_wch(3X) curs_add_wch(3X) waddch(3X) curs_addch(3X) waddstr(3X) curs_addstr(3X) waddwstr(3X) curs_addwstr(3X) +wattr_set(3X) curs_attr(3X) +wattrset(3X) curs_attr(3X) wbkgdset(3X) curs_bkgd(3X) +wbkgrndset(3X) curs_bkgrnd(3X) wget_wch(3X) curs_get_wch(3X) wgetch(3X) curs_getch(3X) wgetstr(3X) curs_getstr(3X) diff --git a/man/manhtml.externs b/man/manhtml.externs index d800272a..946348e4 100644 --- a/man/manhtml.externs +++ b/man/manhtml.externs @@ -1,4 +1,4 @@ -# $Id: manhtml.externs,v 1.18 2023/12/18 00:35:38 tom Exp $ +# $Id: manhtml.externs,v 1.20 2023/12/23 23:49:04 tom Exp $ # Items in this list will not be linked by man2html #*************************************************************************** # Copyright 2019-2021,2023 Thomas E. Dickey * @@ -31,6 +31,7 @@ COLOR_PAIR(1) COLOR_PAIR(2) atoi(3) +bash(1) conflict(1) cron(1) csh(1) @@ -39,11 +40,11 @@ emacs(1) environ(7) errno(3) file(1) -getty(1) +getty(8) jove(1) lynx(1) -nvi(1) mutt(1) +nvi(1) od(1) printf(3) profile(5) @@ -54,16 +55,15 @@ read(2) readline(3) resize(1) scanf(3) +scanf(3S) screen(1) setlocale(3) sh(1) -scanf(3) -scanf(3S) sscanf(3) stdio(3) stty(1) -system(3) swprintf(3) +system(3) termios(3) tmux(1) tty(4) diff --git a/man/menu.3x b/man/menu.3x index 247ebcfb..57dae665 100644 --- a/man/menu.3x +++ b/man/menu.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu.3x,v 1.42 2023/12/16 20:32:22 tom Exp $ -.TH menu 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: menu.3x,v 1.43 2023/12/23 16:08:25 tom Exp $ +.TH menu 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -65,7 +65,7 @@ these functions. To use the \fBmenu\fP library, link with the options \fB\-lmenu \-lcurses\fP. . -.SS Current Default Values for Item Attributes +.SS "Current Default Values for Item Attributes" . The \fBmenu\fP library maintains a default value for item attributes. You can @@ -75,7 +75,7 @@ Changing this default with a \fBset_\fP function affects future item creations, but does not change the rendering of items already created. . -.SS Routine Name Index +.SS "Routine Name Index" . The following table lists each \fBmenu\fP routine and the name of the manual page on which it is described. diff --git a/man/menu_driver.3x b/man/menu_driver.3x index f3a8f02f..3204d1f5 100644 --- a/man/menu_driver.3x +++ b/man/menu_driver.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: menu_driver.3x,v 1.44 2023/12/16 20:32:22 tom Exp $ -.TH menu_driver 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: menu_driver.3x,v 1.45 2023/12/23 16:08:25 tom Exp $ +.TH menu_driver 3X 2023-12-23 "ncurses 6.4" "Library calls" .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 @@ -118,7 +118,7 @@ If there is no such match, \fBmenu_driver\fP returns .PP If the second argument is one of the above pre-defined requests, the corresponding action is performed. -.SS MOUSE HANDLING +.SS "Mouse Handling" If the second argument is the KEY_MOUSE special key, the associated mouse event is translated into one of the above pre-defined requests. Currently only clicks in the user window (e.g., inside the menu display @@ -158,7 +158,7 @@ into a request was done, \fBmenu_driver\fP returns the result of this request. If you clicked outside the user window or the mouse event could not be translated into a menu request an \fBE_REQUEST_DENIED\fP is returned. -.SS APPLICATION-DEFINED COMMANDS +.SS "Application-defined Commands" If the second argument is neither printable nor one of the above pre-defined menu requests or KEY_MOUSE, the drive assumes it is an application-specific diff --git a/man/ncurses.3x b/man/ncurses.3x index 53b83ab2..ec0e39ba 100644 --- a/man/ncurses.3x +++ b/man/ncurses.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: ncurses.3x,v 1.187 2023/12/17 23:44:14 tom Exp $ -.TH ncurses 3X 2023-12-17 "ncurses 6.4" "Library calls" +.\" $Id: ncurses.3x,v 1.189 2023/12/23 16:32:37 tom Exp $ +.TH ncurses 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -106,7 +106,7 @@ the names \fB\-lcurses\fP and \fB\-lcurses_g\fP.) The ncurses_g library generates trace logs (in a file called \*(``trace\*('' in the current directory) that describe curses actions. -See also the section on \fBALTERNATE CONFIGURATIONS\fP. +See section \*(``ALTERNATE CONFIGURATIONS\*('' below. .PP The \fI\%ncurses\fP package supports: overall screen, window and pad manipulation; output to windows and pads; reading terminal input; control over @@ -268,15 +268,16 @@ or in color on terminals that support such display enhancements. See \fB\%curs_attr\fP(3X). .PP .I curses -predefines symbols for a small set of line graphics characters, -corresponding to the VT100 line drawing set. +predefines constants for a small set of line-drawing and other graphics +corresponding to the DEC Alternate Character Set (ACS), +a feature of VT100 and other terminals. See \fB\%waddch\fP(3X) and \fB\%wadd_wch\fP(3X). .PP .I curses is implemented using the operating system's terminal driver; -keystroke events are not received as scan codes but as byte sequences. +keystroke events are received not as scan codes but as byte sequences. Graphical keycaps (alphanumeric and punctuation keys, and the space) @@ -443,7 +444,7 @@ or the constant .BR \%WEOF , analogously to the .IR int -sized -character manipulation functions of ISO C and their constant +character manipulation functions of ISO C and its constant .BR \%EOF . .RE .IP @@ -1179,7 +1180,8 @@ It does not modify the buffering of the standard output. The reason for the change was to make the behavior for interrupts and other signals more robust. One drawback is that certain nonconventional programs would mix -ordinary stdio calls with \fI\%ncurses\fP calls and (usually) work. +ordinary \fI\%stdio\fP(3) calls with \fI\%ncurses\fP calls and (usually) +work. This is no longer possible since \fI\%ncurses\fP is not using the buffered standard output but its own output (to the same file descriptor). As a special case, the low-level calls such as \fBputp\fP still use the @@ -1386,12 +1388,19 @@ setgid permissions: $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME. .EE .RE -.SH ALTERNATE CONFIGURATIONS -Several different configurations are possible, -depending on the configure script options used when building -\fI\%ncurses\fP. -There are a few main options whose effects are visible to the applications -developer using \fI\%ncurses\fP: +.SH "ALTERNATE CONFIGURATIONS" +Many different +.I \%ncurses +configurations are possible, +determined by the options given to the +.I \%configure +script when building the library. +Run the script with the +.B \-\-help +option to peruse them all. +A few are of particular significance to the application developer +employing +.I \%ncurses. .TP 5 \-\-disable\-overwrite The standard include for \fI\%ncurses\fP is as noted in \fBSYNOPSIS\fP: @@ -1593,19 +1602,19 @@ A small number of local differences (that is, individual differences between the XSI Curses and \fI\%ncurses\fP calls) are described in \fBPORTABILITY\fP sections of the library man pages. -.SS Error checking +.SS "Error Checking" In many cases, X/Open Curses is vague about error conditions, omitting some of the SVr4 documentation. .PP Unlike other implementations, this one checks parameters such as pointers -to WINDOW structures to ensure they are not null. +to \fI\%WINDOW\fP structures to ensure they are not null. The main reason for providing this behavior is to guard against programmer error. The standard interface does not provide a way for the library to tell an application which of several possible errors were detected. Relying on this (or some other) extension will adversely affect the portability of curses applications. -.SS Extensions versus portability +.SS "Extensions Versus Portability" Most of the extensions provided by \fI\%ncurses\fP have not been standardized. Some have been incorporated into other implementations, such as @@ -1629,7 +1638,7 @@ See the \fBcurs_print\fP(3X) manual page for details. The routine \fBwresize\fP is not part of XPG4, nor is it present in SVr4. See the \fBwresize\fP(3X) manual page for details. .bP -The WINDOW structure's internal details can be hidden from application +The \fI\%WINDOW\fP structure's internal details can be hidden from application programs. See \fBcurs_opaque\fP(3X) for the discussion of \fBis_scrollok\fP, etc. .bP @@ -1640,7 +1649,7 @@ See \fBcurs_threads\fP(3X) for details. This implementation can also be configured to provide a set of functions which improve the ability to manage multiple screens. See \fBcurs_sp_funcs\fP(3X) for details. -.SS Padding differences +.SS "Padding Differences" In historic curses versions, delays embedded in the capabilities \fBcr\fP, \fBind\fP, \fBcub1\fP, \fBff\fP and \fBtab\fP activated corresponding delay bits in the Unix tty driver. @@ -1648,7 +1657,7 @@ In this implementation, all padding is done by sending NUL bytes. This method is slightly more expensive, but narrows the interface to the Unix kernel significantly and increases the package's portability correspondingly. -.SS Header files +.SS "Header Files" The header file \fI\%curses.h\fP itself includes the header files \fI\%stdio.h\fP and \fI\%unctrl.h\fP. .PP diff --git a/man/panel.3x b/man/panel.3x index 6071b29a..9f4bf26f 100644 --- a/man/panel.3x +++ b/man/panel.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: panel.3x,v 1.60 2023/12/16 21:24:43 tom Exp $ -.TH panel 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: panel.3x,v 1.61 2023/12/23 16:22:25 tom Exp $ +.TH panel 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -109,7 +109,7 @@ puts panel \fIpan\fP at the bottom of all panels. .SS ceiling_panel \fB\%ceiling_panel(\fIsp\fB)\fR acts like \fB\%panel_below(NULL)\fP -for the given \fI\%SCREEN\fP \fIsp\fP. +for the given \fISCREEN\fP \fIsp\fP. .\" --------- .SS del_panel \fB\%del_panel(\fIpan\fB)\fR @@ -119,7 +119,7 @@ removes the given panel \fIpan\fP from the stack and deallocates the .SS ground_panel \fB\%ground_panel(\fIsp\fB)\fR acts like \fB\%panel_above(NULL)\fP -for the given \fI\%SCREEN\fP \fIsp\fP. +for the given \fISCREEN\fP \fIsp\fP. .\" --------- .SS hide_panel \fB\%hide_panel(\fIpan\fB)\fR diff --git a/man/scr_dump.5 b/man/scr_dump.5 index ff1fa1e0..d976fae8 100644 --- a/man/scr_dump.5 +++ b/man/scr_dump.5 @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: scr_dump.5,v 1.40 2023/12/16 21:07:24 tom Exp $ -.TH scr_dump 5 2023-12-16 "ncurses 6.4" "File formats" +.\" $Id: scr_dump.5,v 1.41 2023/12/23 16:27:25 tom Exp $ +.TH scr_dump 5 2023-12-23 "ncurses 6.4" "File formats" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -114,26 +114,26 @@ screen-size, because the library truncates or fills the screen as necessary. .bP The ncurses6 \fBgetwin\fP reads the legacy screen dumps from ncurses5. -.SS ncurses5 (legacy) +.SS "ncurses5 (Legacy)" The screen-dump feature was added to \fI\%ncurses\fP in June 1995. While there were fixes and improvements in succeeding years, the basic scheme was unchanged: .bP -The \fBWINDOW\fP structure was written in binary form. +The \fI\%WINDOW\fP structure was written in binary form. .bP -The \fBWINDOW\fP structure refers to lines of data, -which were written as an array of binary data following the \fBWINDOW\fP. +The \fI\%WINDOW\fP structure refers to lines of data, +which were written as an array of binary data following the \fI\%WINDOW\fP. .bP When \fBgetwin\fP restored the window, it would keep track of offsets into the array of line-data -and adjust the \fBWINDOW\fP structure which was read back into memory. +and adjust the \fI\%WINDOW\fP structure which was read back into memory. .PP This is similar to Unix System\ V, but does not write a \*(``magic number\*('' to identify the file format. .SH PORTABILITY There is no standard format for \fBputwin\fP. This section gives a brief description of the existing formats. -.SS X/Open Curses +.SS "X/Open Curses" Refer to \fIX/Open Curses, Issue 7\fP (2009). .PP X/Open's documentation for \fIenhanced curses\fP says only: @@ -145,7 +145,7 @@ The function then creates and initializes a new window using that data. .PP The \fBputwin(\ )\fP function writes all data associated -with \fIwin\fP into the \fBstdio\fP(3) stream to which \fIfilep\fP +with \fIwin\fP into the \fI\%stdio\fP(3) stream to which \fIfilep\fP points, using an \fBunspecified format\fP. This information can be retrieved later using \fBgetwin(\ )\fP. .RE @@ -170,10 +170,10 @@ or more specific portability warnings about use of the material. In the foregoing, emphasis was added to \fBunspecified format\fP and to \fBXPG4 or to earlier XPG releases\fP, for clarity. -.SS Unix System V +.SS "Unix System V" Unix System\ V curses identified the file format by writing a \*(``magic number\*('' at the beginning of the dump. -The \fBWINDOW\fP data and the lines of text follow, all in binary form. +The \fI\%WINDOW\fP data and the lines of text follow, all in binary form. .PP The Solaris curses source has these definitions: .PP @@ -211,7 +211,7 @@ the magic number is written with the high-order byte first, e.g., .EE .RE .PP -After the magic number, the \fBWINDOW\fP structure and line-data are +After the magic number, the \fI\%WINDOW\fP structure and line-data are written in binary format. While the magic number used by the Unix systems can be seen using \fBod\fP(1), none of the Unix systems documents the format used for screen-dumps. @@ -251,7 +251,7 @@ than writing the whole window from top to bottom. .SS PDCurses PDCurses added support for screen dumps in version 2.7 (2005). Like Unix System\ V and ncurses5, -it writes the \fBWINDOW\fP structure in binary, +it writes the \fI\%WINDOW\fP structure in binary, but begins the file with its three-byte identifier \*(``PDC\*('', followed by a one-byte version, e.g., @@ -274,9 +274,9 @@ It writes the curses shared library major and minor versions as the first two bytes (e.g., 7 and 1), .bP -followed by a binary dump of the \fBWINDOW\fP, +followed by a binary dump of the \fI\%WINDOW\fP, .bP -some data for wide-characters referenced by the \fBWINDOW\fP structure, and +some data for wide-characters referenced by the \fI\%WINDOW\fP structure, and .bP finally, lines as done by other implementations. .SH EXAMPLES diff --git a/man/tabs.1 b/man/tabs.1 index 4bcb457e..01ed44e4 100644 --- a/man/tabs.1 +++ b/man/tabs.1 @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tabs.1,v 1.51 2023/12/17 00:13:57 tom Exp $ -.TH @TABS@ 1 2023-12-16 "ncurses 6.4" "User commands" +.\" $Id: tabs.1,v 1.52 2023/12/23 16:08:25 tom Exp $ +.TH @TABS@ 1 2023-12-23 "ncurses 6.4" "User commands" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -86,7 +86,7 @@ or use the \fB@RESET@\fP program, since the normal initialization sequences do not ensure that tab-stops are reset. .SH OPTIONS -.SS General Options +.SS "General Options" .TP 5 .BI \-T "name" Tell \fB@TABS@\fP which terminal type to use. @@ -110,7 +110,7 @@ and exits. The \fB@TABS@\fP program processes a single list of tab stops. The last option to be processed which defines a list is the one that determines the list to be processed. -.SS Implicit Lists +.SS "Implicit Lists" Use a single number as an option, e.g., \*(``\fB\-5\fP\*('' to set tabs at the given interval (in this case 1, 6, 11, 16, 21, etc.). @@ -119,7 +119,7 @@ Tabs are repeated up to the right margin of the screen. Use \*(``\fB\-0\fP\*('' to clear all tabs. .PP Use \*(``\fB\-8\fP\*('' to set tabs to the standard interval. -.SS Explicit Lists +.SS "Explicit Lists" An explicit list can be defined after the options (this does not use a \*(``\-\*(''). The values in the list must be in increasing numeric order, @@ -144,7 +144,7 @@ tabs 1,+5,+5,+5,+5 .RE .PP which is equivalent to the 1,6,11,16,21 example. -.SS Predefined Tab-Stops +.SS "Predefined Tab Stops" POSIX defines several predefined lists of tab stops. .TP 5 .B \-a diff --git a/man/term.5 b/man/term.5 index e1eaa995..ede2eb1c 100644 --- a/man/term.5 +++ b/man/term.5 @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: term.5,v 1.68 2023/12/16 20:32:22 tom Exp $ -.TH term 5 2023-12-16 "ncurses 6.4" "File formats" +.\" $Id: term.5,v 1.69 2023/12/23 16:08:25 tom Exp $ +.TH term 5 2023-12-23 "ncurses 6.4" "File formats" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -62,7 +62,7 @@ compiled \fIterminfo\fR terminal description .SH SYNOPSIS .B term .SH DESCRIPTION -.SS STORAGE LOCATION +.SS "Storage Location" Compiled terminfo descriptions are placed under the directory \fB\*d\fP. Two configurations are supported (when building the \fI\%ncurses\fP libraries): @@ -97,7 +97,7 @@ It can write (or rewrite) entries in the hashed database. \fI\%TERMINFO_DIRS\fP environment variable by assuming a directory tree for entries that correspond to an existing directory, and hashed database otherwise. -.SS LEGACY STORAGE FORMAT +.SS "Legacy Storage Format" The format has been chosen so that it will be the same on all hardware. An 8 or more bit byte is assumed, but no assumptions about byte ordering or sign extension are made. @@ -215,7 +215,7 @@ Special characters in \*^X or \ec notation are stored in their interpreted form, not the printing representation. Padding information $ and parameter information %x are stored intact in uninterpreted form. -.SS EXTENDED STORAGE FORMAT +.SS "Extended Storage Format" The previous section describes the conventional terminfo binary format. With some minor variations of the offsets (see PORTABILITY), the same binary format is used in all modern Unix systems. @@ -276,7 +276,7 @@ Applications which manipulate terminal data can use the definitions described in \fBterm_variables\fP(3X) which associate the long capability names with members of a \fBTERMTYPE\fP structure. . -.SS EXTENDED NUMBER FORMAT +.SS "Extended Number Format" On occasion, 16-bit signed integers are not large enough. With \fI\%ncurses\fP 6.1, a new format was introduced by making a few changes @@ -315,7 +315,7 @@ must be prepared for both possibilities \- this is why the numbers and sizes are included. Also, new capabilities must always be added at the end of the lists of boolean, number, and string capabilities. -.SS Binary format +.SS "Binary Format" X/Open Curses does not specify a format for the terminfo database. System V curses used a directory-tree of binary files, one per terminal description. @@ -338,7 +338,7 @@ where it was found that the latter did not match X/Open Curses. The format used by the other Unix versions can be matched by building \fI\%ncurses\fP with different configuration options. -.SS Magic codes +.SS "Magic Codes" The magic number in a binary terminfo file is the first 16-bits (two bytes). Besides making it more reliable for the library to check that a file is terminfo, @@ -347,12 +347,12 @@ System V defined more than one magic number, with 0433, 0435 as screen-dumps (see \fBscr_dump\fP(5)). This implementation uses 01036 as a continuation of that sequence, but with a different high-order byte to avoid confusion. -.SS The TERMTYPE structure +.SS "The \fITERMTYPE\fP Structure" Direct access to the \fBTERMTYPE\fP structure is provided for legacy applications. Portable applications should use the \fBtigetflag\fP and related functions described in \fBcurs_terminfo\fP(3X) for reading terminal capabilities. -.SS Mixed-case terminal names +.SS "Mixed-case Terminal Names" A small number of terminal descriptions use uppercase characters in their names. If the underlying filesystem ignores the difference between diff --git a/man/term_variables.3x b/man/term_variables.3x index d0360642..b256f899 100644 --- a/man/term_variables.3x +++ b/man/term_variables.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: term_variables.3x,v 1.33 2023/11/25 14:32:36 tom Exp $ -.TH term_variables 3X 2023-11-25 "ncurses 6.4" "Library calls" +.\" $Id: term_variables.3x,v 1.34 2023/12/23 16:08:25 tom Exp $ +.TH term_variables 3X 2023-12-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -90,7 +90,7 @@ or macros (see \fBcurs_threads\fP(3X)) which provide read-only access to \fIcurses\fP's state. In either case, applications should treat them as read-only to avoid confusing the library. -.SS Alternate Character Set Mapping +.SS "Alternate Character Set Mapping" After initializing the curses or terminfo interfaces, the \fBacs_map\fP array holds information used to translate cells with the \fBA_ALTCHARSET\fP video attribute into line-drawing characters. @@ -100,7 +100,7 @@ Application developers need only know that it is used for the \*(``ACS_\*('' constants in . .PP The comparable data for the wide-character library is a private variable. -.SS Current Terminal Data +.SS "Current Terminal Data" After initializing the curses or terminfo interfaces, the \fBcur_term\fP contains data describing the current terminal. This variable is also set as a side-effect of \fBset_term\fP(3X) @@ -110,7 +110,7 @@ It is possible to save a value of \fBcur_term\fP for subsequent use as a parameter to \fBset_term\fP, for switching between screens. Alternatively, one can save the return value from \fBnewterm\fP or \fBsetupterm\fP(3X) to reuse in \fBset_term\fP. -.SS Terminfo Lookup Tables +.SS "\fIterminfo\fP Lookup Tables" The \fB@TIC@\fP(1) and \fB@INFOCMP@\fP(1) programs use lookup tables for the long and short names of terminfo capabilities, as well as the corresponding names for termcap capabilities. @@ -133,13 +133,13 @@ These are the corresponding names used for termcap descriptions: \fBnumcodes\fP, and \fBstrcodes\fP. .\" -.SS Terminal Type +.SS "Terminal Type" A terminal description begins with one or more terminal names separated by \*(``|\*('' (vertical bars). On initialization of the curses or terminfo interfaces, \fBsetupterm\fP(3X) copies the terminal names to the array \fBttytype\fP. .\" -.SS Terminfo Names +.SS "\fIterminfo\fP Names" In addition to the variables, \fB\fP also defines a symbol for each terminfo capability \fIlong name\fP. These are in terms of the symbol \fBCUR\fP, diff --git a/man/terminfo.head b/man/terminfo.head index d4989909..712da62c 100644 --- a/man/terminfo.head +++ b/man/terminfo.head @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: terminfo.head,v 1.57 2023/12/18 01:15:58 tom Exp $ -.TH terminfo 5 2023-12-17 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats" +.\" $Id: terminfo.head,v 1.59 2023/12/23 23:44:58 tom Exp $ +.TH terminfo 5 2023-12-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -77,7 +77,7 @@ specifying padding requirements and initialization sequences. .PP This manual describes \fI\%ncurses\fP version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). -.SS Terminfo Entry Syntax +.SS "\fIterminfo\fP Entry Syntax" Entries in .I terminfo consist of a sequence of fields: @@ -156,7 +156,7 @@ _ .TE .PP For more on terminal naming conventions, see the \fBterm\fP(7) manual page. -.SS Terminfo Capabilities Syntax +.SS "\fIterminfo\fP Capabilities Syntax" The terminfo entry consists of several \fIcapabilities\fP, i.e., features that the terminal has, or methods for exercising the terminal's features. @@ -185,7 +185,7 @@ Any capability can be \fIcanceled\fP, i.e., suppressed from the terminal entry, by following its name with \*(``@\*('' rather than a capability value. -.SS Similar Terminals +.SS "Similar Terminals" If there are two very similar terminals, one (the variant) can be defined as being just like the other (the base) with certain exceptions. In the @@ -220,6 +220,6 @@ user preferences. An entry included via \fBuse\fP can contain canceled capabilities, which have the same effect as if those cancels were inline in the using terminal entry. -.SS Predefined Capabilities +.SS "Predefined Capabilities" .\" Head of terminfo man page ends here .ps -1 diff --git a/man/terminfo.tail b/man/terminfo.tail index eba40996..dc527831 100644 --- a/man/terminfo.tail +++ b/man/terminfo.tail @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: terminfo.tail,v 1.139 2023/12/17 22:56:21 tom Exp $ +.\" $Id: terminfo.tail,v 1.140 2023/12/23 16:23:35 tom Exp $ .ps +1 .SS "User-Defined Capabilities" . @@ -523,7 +523,7 @@ will give unpredictable results, because dynamic variables are an uninitialized local array on the stack in the \fBtparm\fP function. .bP SVr3.2 curses supported \fIstatic\fP variables. -Those are an array in the \fBTERMINAL\fP +Those are an array in the \fI\%TERMINAL\fP structure (declared in \fBterm.h\fP), and are zeroed automatically when the \fBsetupterm\fP function allocates the data. diff --git a/man/tic.1m b/man/tic.1m index 384d8d62..7471ad8b 100644 --- a/man/tic.1m +++ b/man/tic.1m @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tic.1m,v 1.104 2023/12/16 20:33:11 tom Exp $ -.TH @TIC@ 1M 2023-12-16 "ncurses 6.4" "User commands" +.\" $Id: tic.1m,v 1.105 2023/12/23 16:08:25 tom Exp $ +.TH @TIC@ 1M 2023-12-23 "ncurses 6.4" "User commands" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -139,7 +139,7 @@ the system terminfo database (\fI\*d\fP). .PP The \fIFetching Compiled Descriptions\fP section in the \fBterminfo\fR(5) manual goes into further detail. -.SS ALIASES +.SS Aliases This is the same program as @INFOTOCAP@ and @CAPTOINFO@; usually those are linked to, or copied from this program: .bP @@ -402,7 +402,7 @@ it will infer its type (boolean, number or string) from the syntax and make an extended table entry for that. User-defined capability strings whose name begins with \*(``k\*('' are treated as function keys. -.SS PARAMETERS +.SS Parameters .TP \fIfile\fP contains one or more \fBterminfo\fP terminal descriptions in source @@ -412,7 +412,7 @@ describes the capabilities of a particular terminal. .IP If \fIfile\fP is \*(``-\*('', then the data is read from the standard input. The \fIfile\fP parameter may also be the path of a character-device. -.SS PROCESSING +.SS Processing All but one of the capabilities recognized by \fB@TIC@\fP are documented in \fBterminfo\fP(5). The exception is the \fBuse\fP capability. diff --git a/man/tput.1 b/man/tput.1 index 3811e6ad..e1e9d9d4 100644 --- a/man/tput.1 +++ b/man/tput.1 @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tput.1,v 1.92 2023/12/16 20:32:22 tom Exp $ -.TH @TPUT@ 1 2023-12-16 "ncurses 6.4" "User commands" +.\" $Id: tput.1,v 1.96 2023/12/23 20:55:36 tom Exp $ +.TH @TPUT@ 1 2023-12-23 "ncurses 6.4" "User commands" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -49,60 +49,75 @@ .SH NAME \fB\%@TPUT@\fP, \fB\%reset\fP \- -initialize a terminal or query \fIterminfo\fR database +initialize a terminal or query \fI\%term\%info\fP database .SH SYNOPSIS -\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fIcapname\fR [\fIparameters\fR] -.br -\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] [\fB\-x\fR] \fBclear\fR -.br -\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBinit\fR -.br -\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBreset\fR -.br -\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBlongname\fR -.br -\fB@TPUT@ \-S\fP \fB<<\fP -.br +\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fIcap-code\fP [\fIparameter\fP .\|.\|.] +.PP +\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP +.PP +\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP +.PP +\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBreset\fP +.PP +\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBlongname\fP +.PP +\fB@TPUT@ \-S\fP +.PP \fB@TPUT@ \-V\fP .SH DESCRIPTION -The \fB@TPUT@\fP utility uses the \fBterminfo\fP database to make the -values of terminal-dependent capabilities and information available to -the shell (see \fBsh\fP(1)), to initialize or reset the terminal, or -return the long name of the requested terminal type. -The result depends upon the capability's type: -.RS 3 -.TP 5 -string -\fB@TPUT@\fP writes the string to the standard output. -No trailing newline is supplied. +\fB@TPUT@\fP uses the \fI\%term\%info\fP library and database to make +the values of terminal-specific capabilities and information available +to the shell, +to initialize or reset the terminal, +or report the long name of the current +(or specified) +terminal type. +When retrieving capability values, +the result depends upon the capability's type. +.TP 9 \" "Boolean" + 2n +Boolean +\fB@TPUT@\fP sets its exit status to +.B 0 +if the terminal possesses +.I cap-code, +and +.B 1 +if it does not. .TP integer -\fB@TPUT@\fP writes the decimal value to the standard output, -with a trailing newline. +\fB@TPUT@\fP writes +.IR cap-code 's +decimal value to the standard output stream if defined +.RB ( \-1 +if it is not) +followed by a newline. .TP -boolean -\fB@TPUT@\fP simply sets the exit code -(\fB0\fP for TRUE if the terminal has the capability, -\fB1\fP for FALSE if it does not), -and writes nothing to the standard output. -.RE +string +\fB@TPUT@\fP writes +.IR cap-code 's +value to the standard output stream if defined, +without a trailing newline. .PP Before using a value returned on the standard output, -the application should test the exit code -(e.g., \fB$?\fP, see \fBsh\fP(1)) to be sure it is \fB0\fP. -(See the \fBEXIT STATUS\fP and \fBDIAGNOSTICS\fP sections.) -For a complete list of capabilities -and the \fIcapname\fP associated with each, see \fBterminfo\fP(5). +the application should test \fB@TPUT@\fP's exit status +(for example, +using \fB$?\fP in \fIsh\fP(1)) +to be sure it is \fB0\fP; +see sections \*(``EXIT STATUS\*('' and \*(``DIAGNOSTICS\*('' below. +For a complete list of +.I cap-codes, +see \fB\%terminfo\fP(5). .SS Options .TP \fB\-S\fP -allows more than one capability per invocation of \fB@TPUT@\fP. The -capabilities must be passed to \fB@TPUT@\fP from the standard input -instead of from the command line (see example). -Only one \fIcapname\fP is allowed per line. +allows more than one capability per invocation of \fB@TPUT@\fP. +The capabilities must be passed to \fB@TPUT@\fP from the standard input +instead of from the command line +(see example). +Only one \fIcap-code\fP is allowed per line. The \fB\-S\fP option changes the -meaning of the \fB0\fP and \fB1\fP boolean and string exit codes (see the -EXIT STATUS section). +meaning of the \fB0\fP and \fB1\fP Boolean and string exit statuses +(see section \*(``EXIT STATUS\*('' below). .IP Because some capabilities may use \fIstring\fP parameters rather than \fInumbers\fP, @@ -128,11 +143,11 @@ prevents \fB\%@TPUT@\fP from attempting to clear the scrollback buffer. A few commands (\fBinit\fP, \fBreset\fP and \fBlongname\fP) are special; they are defined by the \fB@TPUT@\fP program. The others are the names of \fIcapabilities\fP from the terminal database -(see \fBterminfo\fP(5) for a list). +(see \fB\%terminfo\fP(5) for a list). Although \fBinit\fP and \fBreset\fP resemble capability names, \fB@TPUT@\fP uses several capabilities to perform these special functions. .TP -\fIcapname\fP +\fIcap-code\fP indicates the capability from the terminal database. .IP If the capability is a string that takes parameters, the arguments @@ -194,7 +209,7 @@ standard tabs will be set (every 8 spaces). .TP (4) if present, the terminal's initialization strings will be -output as detailed in the \fBterminfo\fP(5) section on +output as detailed in the \fB\%terminfo\fP(5) section on .IR "Tabs and Initialization" , .TP (5) @@ -233,13 +248,18 @@ strings are, the \fIinitialization\fP strings will be output. .IP Otherwise, \fBreset\fP acts identically to \fBinit\fP. .TP -\fBlongname\fP -If the terminal database is present and an entry for the -user's terminal exists (see \fB\-T\fItype\fR above), then the long name -of the terminal will be put out. -The long name is the last -name in the first line of the terminal's description in the -\fBterminfo\fP database [see \fBterm\fP(5)]. +.B longname +If the terminal database is present and an entry for the user's terminal +exists +(see +.B \-T +.I type +above), +\fB\%@TPUT@\fP reports the terminal's description +(or \*(``long name\*('') +to the standard output, +without a trailing newline. +See \fBterm\fP(5). .SS Aliases \fB@TPUT@\fP handles the \fBclear\fP, \fBinit\fP and \fBreset\fP commands specially: @@ -282,7 +302,7 @@ If \fB@TPUT@\fP is invoked by a link named \fBinit\fP, this has the same effect as \fB@TPUT@ init\fP. Again, you are less likely to use that link because another program named \fBinit\fP has a more well-established use. -.SS Terminal Size +.SS "Terminal Size" Besides the special commands (e.g., \fBclear\fP), @TPUT@ treats certain terminfo capabilities specially: \fBlines\fP and \fBcols\fP. @@ -305,60 +325,61 @@ relying upon the operating system (or finally, the terminal database). .SH EXIT STATUS If the \fB\-S\fP option is used, \fB@TPUT@\fP checks for errors from each line, -and if any errors are found, will set the exit code to 4 plus the +and if any errors are found, will set the exit status to 4 plus the number of lines with errors. -If no errors are found, the exit code is \fB0\fP. +If no errors are found, the exit status is \fB0\fP. No indication of which line failed can be given so -exit code \fB1\fP will never appear. -Exit codes \fB2\fP, \fB3\fP, and +exit status \fB1\fP will never appear. +Exit statuses \fB2\fP, \fB3\fP, and \fB4\fP retain their usual interpretation. If the \fB\-S\fP option is not used, -the exit code depends on the type of \fIcapname\fP: +the exit status depends on the type of \fIcap-code\fP: .RS 3 .TP -.I boolean +.I Boolean a value of \fB0\fP is set for TRUE and \fB1\fP for FALSE. .TP .I string a value of \fB0\fP is set if the -\fIcapname\fP is defined for this terminal \fItype\fP (the value of -\fIcapname\fP is returned on standard output); -a value of \fB1\fP is set if \fIcapname\fP +\fIcap-code\fP is defined for this terminal \fItype\fP (the value of +\fIcap-code\fP is returned on standard output); +a value of \fB1\fP is set if \fIcap-code\fP is not defined for this terminal \fItype\fP (nothing is written to standard output). .TP .I integer a value of \fB0\fP is always set, -whether or not \fIcapname\fP is defined for this terminal \fItype\fP. -To determine if \fIcapname\fP is defined for this terminal \fItype\fP, +whether or not \fIcap-code\fP is defined for this terminal \fItype\fP. +To determine if \fIcap-code\fP is defined for this terminal \fItype\fP, the user must test the value written to standard output. A value of \fB\-1\fP -means that \fIcapname\fP is not defined for this terminal \fItype\fP. +means that \fIcap-code\fP is not defined for this terminal \fItype\fP. .TP .I other \fBreset\fP or \fBinit\fP may fail to find their respective files. -In that case, the exit code is set to 4 + \fBerrno\fP. +In that case, the exit status is set to 4 + \fBerrno\fP. .RE .PP -Any other exit code indicates an error; see the DIAGNOSTICS section. +Any other exit status indicates an error; +see section \*(``DIAGNOSTICS\*('' below. .SH DIAGNOSTICS -\fB@TPUT@\fP prints the following error messages and sets the corresponding exit -codes. +\fB@TPUT@\fP prints the following error messages and sets the +corresponding exit statuses. .PP .ne 15 .TS l l. -exit code error message +exit status error message = \fB0\fP T{ -(\fIcapname\fP is a numeric variable that is not specified in the -\fBterminfo\fP(5) database for this terminal type, e.g. +(\fIcap-code\fP is a numeric variable that is not specified in the +\fB\%terminfo\fP(5) database for this terminal type, e.g. \fB@TPUT@ \-T450 lines\fP and \fB@TPUT@ \-Thp2621 xmc\fP) T} \fB1\fP no error message is printed, see the \fBEXIT STATUS\fP section. \fB2\fP usage error -\fB3\fP unknown terminal \fItype\fP or no \fBterminfo\fP database -\fB4\fP unknown \fBterminfo\fP capability \fIcapname\fP +\fB3\fP unknown terminal \fItype\fP or no \fI\%term\%info\fP database +\fB4\fP unknown \fI\%term\%info\fP capability \fIcap-code\fP \fB>4\fP error occurred in \-S = .TE @@ -373,7 +394,7 @@ compiled terminal description database This implementation of \fBtput\fP differs from AT&T \fBtput\fP in two important areas: .bP -\fB@TPUT@\fP \fIcapname\fP writes to the standard output. +\fB@TPUT@\fP \fIcap-code\fP writes to the standard output. That need not be a regular terminal. However, the subcommands which manipulate terminal modes may not use the standard output. @@ -393,17 +414,18 @@ using functions shared with \fB@TSET@\fP If it is not able to open a terminal, e.g., when running in \fBcron\fP(1), \fB@TPUT@\fP will return an error. .bP -AT&T \fBtput\fP guesses the type of its \fIcapname\fP operands by seeing if -all of the characters are numeric, or not. +AT&T \fBtput\fP guesses the type of its \fIcap-code\fP operands by +seeing if all of the characters are numeric, +or not. .IP -Most implementations which provide support for \fIcapname\fP operands +Most implementations which provide support for \fIcap-code\fP operands use the \fBtparm\fP function to expand parameters in it. That function expects a mixture of numeric and string parameters, requiring \fB@TPUT@\fP to know which type to use. .IP This implementation uses a table to determine the parameter types for -the standard \fIcapname\fP operands, and an internal library -function to analyze nonstandard \fIcapname\fP operands. +the standard \fIcap-code\fP operands, and an internal library +function to analyze nonstandard \fIcap-code\fP operands. .IP Besides providing more reliable operation than AT&T's utility, a portability problem is introduced by this analysis: @@ -415,7 +437,7 @@ Portable applications should not rely upon this feature; specifically for OpenBSD. .PP This implementation (unlike others) can accept both \fItermcap\fP -and \fIterminfo\fP names for the \fIcapname\fP feature, +and \fIterminfo\fP names for the \fIcap-code\fP feature, if \fItermcap\fP support is compiled in. However, the predefined \fItermcap\fP and \fIterminfo\fP names have two @@ -435,21 +457,27 @@ the \fItermcap\fP name \fBcd\fP (clear to end of screen). .PP The \fBlongname\fP and \fB\-S\fP options, and the parameter-substitution features used in the \fBcup\fP example, -were not supported in BSD curses before 4.3reno (1989) or in -AT&T/USL curses before SVr4 (1988). +were not supported in +AT&T/USL +.I curses +before SVr4 (1989). +Later, 4.3BSD-Reno (1990) added support for \fBlongname\fP, +.\" longname was added in October 1989. +and NetBSD (1994) added support for the parameter-substitution features. .PP IEEE Std 1003.1/The Open Group Base Specifications Issue 7 (POSIX.1-2008) documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP. There are a few interesting observations to make regarding that: .bP -In this implementation, \fBclear\fP is part of the \fIcapname\fP support. +In this implementation, +\fBclear\fP is part of the \fIcap-code\fP support. The others (\fBinit\fP and \fBlongname\fP) do not correspond to terminal capabilities. .bP Other implementations of \fBtput\fP on SVr4-based systems such as Solaris, IRIX64 and HP-UX as well as others such as AIX and Tru64 -provide support for \fIcapname\fP operands. +provide support for \fIcap-code\fP operands. .bP A few platforms such as FreeBSD recognize termcap names rather than terminfo capability names in their respective \fBtput\fP commands. @@ -463,8 +491,8 @@ Because (apparently) \fIall\fP of the certified Unix systems support the full set of capability names, the reasoning for documenting only a few may not be apparent. .bP -X/Open Curses Issue 7 documents \fBtput\fP differently, with \fIcapname\fP -and the other features used in this implementation. +X/Open Curses Issue 7 documents \fBtput\fP differently, +with \fIcap-code\fP and the other features used in this implementation. .bP That is, there are two standards for \fBtput\fP: POSIX (a subset) and X/Open Curses (the full implementation). @@ -472,29 +500,35 @@ POSIX documents a subset to avoid the complication of including X/Open Curses and the terminal capabilities database. .bP While it is certainly possible to write a \fBtput\fP program -without using curses, -none of the systems which have a curses implementation provide -a \fBtput\fP utility which does not provide the \fIcapname\fP feature. +without using +.I curses, +no system with a +.I curses +implementation provides a \fBtput\fP utility that does not also supply +the \fIcap-code\fP feature. .PP X/Open Curses Issue 7 (2009) is the first version to document utilities. However that part of X/Open Curses does not follow existing practice -(i.e., Unix features documented in SVID 3): +(that is, +System\ V +.I curses +behavior). .bP -It assigns exit code 4 to \*(``invalid operand\*('', +It assigns exit status 4 to \*(``invalid operand\*('', which may be the same as \fIunknown capability\fP. For instance, the source code for Solaris' xcurses uses the term \*(``invalid\*('' in this case. .bP -It assigns exit code 255 to a numeric variable that is not specified in +It assigns exit status 255 to a numeric variable that is not specified in the terminfo database. That likely is a documentation error, confusing the \fB\-1\fP written to the standard output for an absent -or cancelled numeric value versus an (unsigned) exit code. +or cancelled numeric value versus an (unsigned) exit status. .PP -The various Unix systems (AIX, HP-UX, Solaris) use the same exit-codes +The various Unix systems (AIX, HP-UX, Solaris) use the same exit statuses as \fI\%ncurses\fP. .PP -NetBSD curses documents different exit codes which do not correspond +NetBSD curses documents different exit statuses which do not correspond to either \fI\%ncurses\fP or X/Open. .SH HISTORY The \fBtput\fP command was begun by Bill Joy in 1980. @@ -548,14 +582,14 @@ were handled. .TP 5 \fB@TPUT@ init\fP Initialize the terminal according to the type of -terminal in the environmental variable \fITERM\fP. +terminal in the environment variable \fITERM\fP. This command should be included in everyone's .profile after -the environmental variable \fITERM\fP has been exported, +the environment variable \fITERM\fP has been exported, as illustrated on the \fBprofile\fP(5) manual page. .TP 5 \fB@TPUT@ \-T5620 reset\fP Reset an AT&T 5620 terminal, overriding the type of -terminal in the environmental variable \fITERM\fP. +terminal in the environment variable \fITERM\fP. .TP 5 \fB@TPUT@ cup 0 0\fP Send the sequence to move the cursor to row \fB0\fP, column \fB0\fP @@ -579,7 +613,7 @@ This might be followed by a prompt: \fBecho "${bold}Please type in your name: ${offbold}\ec"\fP .TP 5 \fB@TPUT@ hc\fP -Set exit code to indicate if the current terminal is a hard copy terminal. +Set exit status to indicate if the current terminal is a hard copy terminal. .TP 5 \fB@TPUT@ cup 23 4\fP Send the sequence to move the cursor to row 23, column 4. @@ -588,29 +622,35 @@ Send the sequence to move the cursor to row 23, column 4. Send the terminfo string for cursor-movement, with no parameters substituted. .TP 5 \fB@TPUT@ longname\fP -Print the long name from the \fBterminfo\fP database for the -type of terminal specified in the environmental +Print the long name from the \fI\%term\%info\fP database for the +type of terminal specified in the environment variable \fITERM\fP. -.PP -.RS 5 -\fB@TPUT@ \-S < clear\fP -.br -\fB> cup 10 10\fP -.br -\fB> bold\fP -.br -\fB> !\fP -.RE .TP 5 -\& -This example shows \fB@TPUT@\fP processing several capabilities -in one invocation. +\fB@TPUT@ \-S\fP +The \fB\-S\fP option can be profitably used with a shell +\*(``here document\*(''. +.IP +.EX +$ \fB@TPUT@ \-S < \fBclear\fP +> \fBcup 10 10\fP +> \fBbold\fP +> \fB!\fP +.EE +.IP +We see \fB@TPUT@\fP processing several capabilities in one invocation. It clears the screen, -moves the cursor to position 10, 10 -and turns on bold (extra bright) mode. -The list is terminated by an exclamation mark (\fB!\fP) on a line by itself. +moves the cursor to position +(10, 10) +and turns on bold +(extra bright) +mode. +.IP +The same sequence of commands can be combined using the OpenBSD feature: +.IP +.EX +$ \fB@TPUT@ \fBclear\fP \fBcup 10 10\fP \fBbold\fP +.EE .SH SEE ALSO \fB\%@CLEAR@\fP(1), \fB\%stty\fP(1), diff --git a/man/tset.1 b/man/tset.1 index 4621c8cf..cf76c26e 100644 --- a/man/tset.1 +++ b/man/tset.1 @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tset.1,v 1.78 2023/12/16 20:32:22 tom Exp $ -.TH @TSET@ 1 2023-12-16 "ncurses 6.4" "User commands" +.\" $Id: tset.1,v 1.79 2023/12/23 16:20:07 tom Exp $ +.TH @TSET@ 1 2023-12-23 "ncurses 6.4" "User commands" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -57,7 +57,7 @@ initialize or reset terminal state .br \fB@RESET@\fP [\fB\-IQVcqrsw\fP] [\fB\-\fP] [\fB\-e\fP \fIch\fP] [\fB\-i\fP \fIch\fP] [\fB\-k\fP \fIch\fP] [\fB\-m\fP \fImapping\fP] [\fIterminal-type\fP] .SH DESCRIPTION -.SS tset - initialization +.SS "\fItset\fP \(em initialization" This program initializes terminals. .PP First, \fB@TSET@\fP retrieves the current terminal mode settings @@ -81,12 +81,12 @@ This determination is done as follows, using the first terminal type found. .PP 1. The \fBterminal\fP argument specified on the command line. .PP -2. The value of the \fITERM\fP environmental variable. +2. The value of the \fITERM\fP environment variable. .PP 3. (BSD systems only.) The terminal type associated with the standard error output device in the \fI/etc/ttys\fP file. (On System\ V hosts and systems using that convention, -\fBgetty\fP(1) does this job by setting +\fI\%getty\fP(8) does this job by setting \fITERM\fP according to the type passed to it by \fI\%/etc/inittab\fP.) .PP 4. The default terminal type, \*(``unknown\*('', @@ -129,7 +129,7 @@ and \fB@TSET@\fP waits one second (in case a hardware reset was issued). Finally, if the erase, interrupt and line kill characters have changed, or are not set to their default values, their values are displayed to the standard error output. -.SS reset - reinitialization +.SS "\fIreset\fP \(em reinitialization" When invoked as \fB@RESET@\fP, \fB@TSET@\fP sets the terminal modes to \*(``sane\*('' values: .bP @@ -164,11 +164,13 @@ This is done using the \fB\-s\fP option. .PP When the \fB\-s\fP option is specified, the commands to enter the information into the shell's environment are written to the standard output. -If the \fISHELL\fP environmental variable ends in \*(``csh\*('', +If the \fISHELL\fP environment variable ends in \*(``csh\*('', the commands -are for \fBcsh\fP, otherwise, they are for \fBsh\fP(1). -Note, the \fBcsh\fP commands set and unset the shell variable -\fBnoglob\fP, leaving it unset. +are for \fIcsh\fP(1), +otherwise, +they are for \fIsh\fP(1). +The \fIcsh\fP commands set and unset the shell variable \fBnoglob\fP, +leaving it unset. The following line in the \fB.login\fP or \fB.profile\fP files will initialize the environment correctly: .sp @@ -177,7 +179,7 @@ or \fB.profile\fP files will initialize the environment correctly: .SS "Terminal Type Mapping" When the terminal is not hardwired into the system (or the current system information is incorrect) the terminal type derived from the -\fI/etc/ttys\fP file or the \fITERM\fP environmental variable is often +\fI/etc/ttys\fP file or the \fITERM\fP environment variable is often something generic like \fBnetwork\fP, \fBdialup\fP, or \fBunknown\fP. When \fB@TSET@\fP is used in a startup script it is often desirable to provide information about the type of terminal used on such ports. @@ -234,8 +236,8 @@ terminal. No whitespace characters are permitted in the \fB\-m\fP option argument. Also, to avoid problems with meta-characters, it is suggested that the entire \fB\-m\fP option argument be placed within single quote characters, -and that \fBcsh\fP users insert a backslash character (\*(``\e\*('') before -any exclamation marks (\*(``!\*(''). +and that \fIcsh\fP users insert a backslash character (\*(``\e\*('') +before any exclamation marks (\*(``!\*(''). .SH OPTIONS The options are as follows: .TP 5 @@ -295,8 +297,8 @@ If neither \fB\-c\fP or \fB\-w\fP is given, both options are assumed. The \fB@TSET@\fP command uses these environment variables: .TP 5 .I SHELL -tells \fB@TSET@\fP whether to initialize \fITERM\fP using \fBsh\fP(1) or -\fBcsh\fP(1) syntax. +tells \fB@TSET@\fP whether to initialize \fITERM\fP using \fIsh\fP(1) or +\fIcsh\fP(1) syntax. .TP 5 .I TERM Denotes your terminal type. @@ -330,8 +332,8 @@ is always an alias for \fBtset\fP. The \fB\%@TSET@\fP utility provides backward compatibility with BSD environments; under most modern Unices, -\fI\%/etc/inittab\fP and \fBgetty\fP(1) can set \fITERM\fP appropriately -for each dial-up line, +\fI\%/etc/inittab\fP and \fI\%getty\fP(8) can set \fITERM\fP +appropriately for each dial-up line, obviating what was \fB\%@TSET@\fP's most important use. This implementation behaves like 4.4BSD \fBtset\fP, with a few exceptions we shall consider now. diff --git a/man/user_caps.5 b/man/user_caps.5 index 033f9d46..978edbc4 100644 --- a/man/user_caps.5 +++ b/man/user_caps.5 @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: user_caps.5,v 1.42 2023/12/16 20:32:22 tom Exp $ -.TH user_caps 5 2023-12-16 "ncurses 6.4" "File formats" +.\" $Id: user_caps.5,v 1.43 2023/12/23 16:08:25 tom Exp $ +.TH user_caps 5 2023-12-23 "ncurses 6.4" "File formats" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -185,7 +185,7 @@ to provide extended special-key names. Fitting that into termcap's limitation of 2-character names would be pointless. These extended keys are available only with terminfo. -.SS Recognized capabilities +.SS "Recognized Capabilities" The \fI\%ncurses\fP library uses the user-definable capabilities. While the terminfo database may have other extensions, \fI\%ncurses\fP makes explicit checks for these: @@ -347,7 +347,7 @@ xterm mouse protocols: %?%p4%tM%em%;, .fi . -.SS Extended key-definitions +.SS "Extended Key Definitions" Several terminals provide the ability to send distinct strings for combinations of modified special keys. There is no standard for what those keys can send. diff --git a/package/debian-mingw/changelog b/package/debian-mingw/changelog index 3eea42af..604dfb49 100644 --- a/package/debian-mingw/changelog +++ b/package/debian-mingw/changelog @@ -1,8 +1,8 @@ -ncurses6 (6.4+20231217) unstable; urgency=low +ncurses6 (6.4+20231223) unstable; urgency=low * latest weekly patch - -- Thomas E. Dickey Sun, 17 Dec 2023 18:18:40 -0500 + -- Thomas E. Dickey Sat, 23 Dec 2023 06:35:00 -0500 ncurses6 (5.9+20131005) unstable; urgency=low diff --git a/package/debian-mingw64/changelog b/package/debian-mingw64/changelog index 3eea42af..604dfb49 100644 --- a/package/debian-mingw64/changelog +++ b/package/debian-mingw64/changelog @@ -1,8 +1,8 @@ -ncurses6 (6.4+20231217) unstable; urgency=low +ncurses6 (6.4+20231223) unstable; urgency=low * latest weekly patch - -- Thomas E. Dickey Sun, 17 Dec 2023 18:18:40 -0500 + -- Thomas E. Dickey Sat, 23 Dec 2023 06:35:00 -0500 ncurses6 (5.9+20131005) unstable; urgency=low diff --git a/package/debian/changelog b/package/debian/changelog index 794660ba..52315841 100644 --- a/package/debian/changelog +++ b/package/debian/changelog @@ -1,8 +1,8 @@ -ncurses6 (6.4+20231217) unstable; urgency=low +ncurses6 (6.4+20231223) unstable; urgency=low * latest weekly patch - -- Thomas E. Dickey Sun, 17 Dec 2023 18:18:40 -0500 + -- Thomas E. Dickey Sat, 23 Dec 2023 06:35:00 -0500 ncurses6 (5.9+20120608) unstable; urgency=low diff --git a/package/mingw-ncurses.nsi b/package/mingw-ncurses.nsi index 96cb0d31..d6da23ae 100644 --- a/package/mingw-ncurses.nsi +++ b/package/mingw-ncurses.nsi @@ -1,4 +1,4 @@ -; $Id: mingw-ncurses.nsi,v 1.624 2023/12/17 23:18:40 tom Exp $ +; $Id: mingw-ncurses.nsi,v 1.625 2023/12/23 11:35:00 tom Exp $ ; TODO add examples ; TODO bump ABI to 6 @@ -10,7 +10,7 @@ !define VERSION_MAJOR "6" !define VERSION_MINOR "4" !define VERSION_YYYY "2023" -!define VERSION_MMDD "1217" +!define VERSION_MMDD "1223" !define VERSION_PATCH ${VERSION_YYYY}${VERSION_MMDD} !define MY_ABI "5" diff --git a/package/mingw-ncurses.spec b/package/mingw-ncurses.spec index 43652ce4..9f0736e3 100644 --- a/package/mingw-ncurses.spec +++ b/package/mingw-ncurses.spec @@ -3,7 +3,7 @@ Summary: shared libraries for terminal handling Name: mingw32-ncurses6 Version: 6.4 -Release: 20231217 +Release: 20231223 License: X11 Group: Development/Libraries URL: https://invisible-island.net/ncurses/ diff --git a/package/ncurses.spec b/package/ncurses.spec index faccbf19..391eed7a 100644 --- a/package/ncurses.spec +++ b/package/ncurses.spec @@ -1,7 +1,7 @@ Summary: shared libraries for terminal handling Name: ncurses6 Version: 6.4 -Release: 20231217 +Release: 20231223 License: X11 Group: Development/Libraries URL: https://invisible-island.net/ncurses/ diff --git a/package/ncursest.spec b/package/ncursest.spec index 4312edb7..cfe212cb 100644 --- a/package/ncursest.spec +++ b/package/ncursest.spec @@ -1,7 +1,7 @@ Summary: Curses library with POSIX thread support. Name: ncursest6 Version: 6.4 -Release: 20231217 +Release: 20231223 License: X11 Group: Development/Libraries Source: ncurses-%{version}-%{release}.tgz

captoinfo 1m 2023-12-16 ncurses 6.4 User commands

captoinfo 1m 2023-12-23 ncurses 6.4 User commands

curs_add_wch 3x 2023-12-16 ncurses 6.4 Library calls

curs_add_wch 3x 2023-12-23 ncurses 6.4 Library calls

curs_addch 3x 2023-12-16 ncurses 6.4 Library calls

curs_addch 3x 2023-12-23 ncurses 6.4 Library calls

curs_attr 3x 2023-12-16 ncurses 6.4 Library calls

curs_attr 3x 2023-12-23 ncurses 6.4 Library calls

curs_bkgd 3x 2023-12-17 ncurses 6.4 Library calls

curs_bkgd 3x 2023-12-23 ncurses 6.4 Library calls

curs_bkgrnd 3x 2023-12-16 ncurses 6.4 Library calls

curs_bkgrnd 3x 2023-12-23 ncurses 6.4 Library calls

curs_color 3x 2023-12-16 ncurses 6.4 Library calls

curs_color 3x 2023-12-23 ncurses 6.4 Library calls

curs_extend 3x 2023-12-16 ncurses 6.4 Library calls

curs_extend 3x 2023-12-23 ncurses 6.4 Library calls

curs_get_wch 3x 2023-11-25 ncurses 6.4 Library calls

curs_get_wch 3x 2023-12-23 ncurses 6.4 Library calls

curs_getch 3x 2023-12-16 ncurses 6.4 Library calls

curs_getch 3x 2023-12-23 ncurses 6.4 Library calls

curs_initscr 3x 2023-12-17 ncurses 6.4 Library calls

curs_initscr 3x 2023-12-23 ncurses 6.4 Library calls

curs_inopts 3x 2023-12-16 ncurses 6.4 Library calls

curs_inopts 3x 2023-12-23 ncurses 6.4 Library calls

curs_ins_wch 3x 2023-11-25 ncurses 6.4 Library calls

curs_ins_wch 3x 2023-12-23 ncurses 6.4 Library calls

curs_insch 3x 2023-12-16 ncurses 6.4 Library calls

curs_insch 3x 2023-12-23 ncurses 6.4 Library calls

curs_legacy 3x 2023-10-21 ncurses 6.4 Library calls

curs_legacy 3x 2023-12-23 ncurses 6.4 Library calls

curs_memleaks 3x 2023-12-16 ncurses 6.4 Library calls

curs_memleaks 3x 2023-12-23 ncurses 6.4 Library calls

curs_mouse 3x 2023-12-16 ncurses 6.4 Library calls

curs_mouse 3x 2023-12-23 ncurses 6.4 Library calls

curs_print 3x 2023-12-16 ncurses 6.4 Library calls

curs_print 3x 2023-12-23 ncurses 6.4 Library calls

curs_printw 3x 2023-12-17 ncurses 6.4 Library calls

curs_printw 3x 2023-12-23 ncurses 6.4 Library calls

curs_scanw 3x 2023-12-17 ncurses 6.4 Library calls

curs_scanw 3x 2023-12-23 ncurses 6.4 Library calls

curs_sp_funcs 3x 2023-12-16 ncurses 6.4 Library calls

curs_sp_funcs 3x 2023-12-23 ncurses 6.4 Library calls

curs_termcap 3x 2023-12-17 ncurses 6.4 Library calls

curs_termcap 3x 2023-12-23 ncurses 6.4 Library calls