X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fterminfo.5.html;h=70748ba944093c242ff91d27e15b8a0f4176c852;hb=74433bcf4f6fe40862a28f3c00edaedcd5054b01;hp=953d01ed686bbaf7077d0f6b9accdc23cab7ebd3;hpb=91d451ffc473b358d8d74506d2da8871e44fbd7b;p=ncurses.git diff --git a/doc/html/man/terminfo.5.html b/doc/html/man/terminfo.5.html index 953d01ed..70748ba9 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.40 2021/06/17 21:30:22 tom Exp @ + * @Id: terminfo.head,v 1.42 2021/12/25 17:39:16 tom Exp @ * Head of terminfo man page ends here **************************************************************************** * Copyright 2018-2020,2021 Thomas E. Dickey * @@ -62,7 +62,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: terminfo.tail,v 1.101 2021/06/17 21:30:22 tom Exp @ + * @Id: terminfo.tail,v 1.110 2021/12/25 20:14:56 tom Exp @ *.in -2 *.in +2 *.in -2 @@ -76,7 +76,7 @@
- terminfo - terminal capability data base + terminfo - terminal capability database
@@ -95,7 +95,7 @@
- Terminfo is a data base describing terminals, used by screen-oriented + Terminfo is a database describing terminals, used by screen-oriented programs such as nvi(1), lynx(1), mutt(1), and other curses applications, using high-level calls to libraries such as curses(3x). It is also used via low-level calls by non-curses applications which @@ -106,7 +106,7 @@ have, by specifying how to perform screen operations, and by specifying padding requirements and initialization sequences. - This manual describes ncurses version 6.2 (patch 20210710). + This manual describes ncurses version 6.3 (patch 20211225).
@@ -958,9 +958,8 @@ #1 set_left_margin smgl ML set left soft margin at current - column. See - smgl. (ML is not in - BSD termcap). + column. (ML is + not in BSD termcap). set_left_margin_parm smglp Zm Set left (right) margin at column #1 set_right_margin smgr MR set right soft @@ -1011,8 +1010,8 @@ user3 u3 u3 User string #3 user4 u4 u4 User string #4 user5 u5 u5 User string #5 - user6 u6 u6 User string #6 + user7 u7 u7 User string #7 user8 u8 u8 User string #8 user9 u9 u9 User string #9 @@ -1022,7 +1021,7 @@ zero_motion zerom Zx No motion for subsequent character - The following string capabilities are present in the SVr4.0 term + The following string capabilities are present in the SVr4.0 term structure, but were originally not documented in the man page. @@ -1076,10 +1075,9 @@ key #1 to type string #2 and show string #3 - - req_mouse_pos reqmp RQ Request mouse position + scancode_escape scesc S7 Escape for scancode emulation set0_des_seq s0ds s0 Shift to codeset 0 @@ -1106,11 +1104,11 @@ bottom margins to #1, #2 - The XSI Curses standard added these hardcopy capabilities. They were - used in some post-4.1 versions of System V curses, e.g., Solaris 2.5 - and IRIX 6.x. Except for YI, the ncurses termcap names for them are - invented. According to the XSI Curses standard, they have no termcap - names. If your compiled terminfo entries use these, they may not be + The XSI Curses standard added these hardcopy capabilities. They were + used in some post-4.1 versions of System V curses, e.g., Solaris 2.5 + and IRIX 6.x. Except for YI, the ncurses termcap names for them are + invented. According to the XSI Curses standard, they have no termcap + names. If your compiled terminfo entries use these, they may not be binary-compatible with System V terminfo entries after SVr4.1; beware! @@ -1139,44 +1137,44 @@
- The preceding section listed the predefined capabilities. They deal - with some special features for terminals no longer (or possibly never) - produced. Occasionally there are special features of newer terminals - which are awkward or impossible to represent by reusing the predefined + The preceding section listed the predefined capabilities. They deal + with some special features for terminals no longer (or possibly never) + produced. Occasionally there are special features of newer terminals + which are awkward or impossible to represent by reusing the predefined capabilities. - ncurses addresses this limitation by allowing user-defined - capabilities. The tic and infocmp programs provide the -x option for + ncurses addresses this limitation by allowing user-defined + capabilities. The tic and infocmp programs provide the -x option for this purpose. When -x is set, tic treats unknown capabilities as user- - defined. That is, if tic encounters a capability name which it does - not recognize, it infers its type (boolean, number or string) from the - syntax and makes an extended table entry for that capability. The - use_extended_names(3x) function makes this information conditionally - available to applications. The ncurses library provides the data + defined. That is, if tic encounters a capability name which it does + not recognize, it infers its type (boolean, number or string) from the + syntax and makes an extended table entry for that capability. The + use_extended_names(3x) function makes this information conditionally + available to applications. The ncurses library provides the data leaving most of the behavior to applications: - o User-defined capability strings whose name begins with "k" are + o User-defined capability strings whose name begins with "k" are treated as function keys. - o The types (boolean, number, string) determined by tic can be + o The types (boolean, number, string) determined by tic can be inferred by successful calls on tigetflag, etc. o If the capability name happens to be two characters, the capability is also available through the termcap interface. - While termcap is said to be extensible because it does not use a - predefined set of capabilities, in practice it has been limited to the - capabilities defined by terminfo implementations. As a rule, user- + While termcap is said to be extensible because it does not use a + predefined set of capabilities, in practice it has been limited to the + capabilities defined by terminfo implementations. As a rule, user- defined capabilities intended for use by termcap applications should be - limited to booleans and numbers to avoid running past the 1023 byte - limit assumed by termcap implementations and their applications. In - particular, providing extended sets of function keys (past the 60 + limited to booleans and numbers to avoid running past the 1023 byte + limit assumed by termcap implementations and their applications. In + particular, providing extended sets of function keys (past the 60 numbered keys and the handful of special named keys) is best done using the longer names available using terminfo.
- The following entry, describing an ANSI-standard terminal, is + The following entry, describing an ANSI-standard terminal, is representative of what a terminfo entry for a modern terminal typically looks like. @@ -1211,36 +1209,36 @@ smul=\E[4m, tbc=\E[3g, u6=\E[%i%d;%dR, u7=\E[6n, u8=\E[?%[;0123456789]c, u9=\E[c, vpa=\E[%i%p1%dd, - Entries may continue onto multiple lines by placing white space at the - beginning of each line except the first. Comments may be included on + Entries may continue onto multiple lines by placing white space at the + beginning of each line except the first. Comments may be included on lines beginning with "#". Capabilities in terminfo are of three types: - o Boolean capabilities which indicate that the terminal has some + o Boolean capabilities which indicate that the terminal has some particular feature, o numeric capabilities giving the size of the terminal or the size of particular delays, and - o string capabilities, which give a sequence which can be used to + o string capabilities, which give a sequence which can be used to perform particular terminal operations.
All capabilities have names. For instance, the fact that ANSI-standard - terminals have automatic margins (i.e., an automatic return and line- - feed when the end of a line is reached) is indicated by the capability - am. Hence the description of ansi includes am. Numeric capabilities - are followed by the character "#" and then a positive value. Thus + terminals have automatic margins (i.e., an automatic return and line- + feed when the end of a line is reached) is indicated by the capability + am. Hence the description of ansi includes am. Numeric capabilities + are followed by the character "#" and then a positive value. Thus cols, which indicates the number of columns the terminal has, gives the - value "80" for ansi. Values for numeric capabilities may be specified - in decimal, octal or hexadecimal, using the C programming language + value "80" for ansi. Values for numeric capabilities may be specified + in decimal, octal or hexadecimal, using the C programming language conventions (e.g., 255, 0377 and 0xff or 0xFF). - Finally, string valued capabilities, such as el (clear to end of line - sequence) are given by the two-character code, an "=", and then a + Finally, string valued capabilities, such as el (clear to end of line + sequence) are given by the two-character code, an "=", and then a string ending at the next following ",". - A number of escape sequences are provided in the string valued + A number of escape sequences are provided in the string valued capabilities for easy encoding of characters there: o Both \E and \e map to an ESCAPE character, @@ -1258,9 +1256,9 @@ respectively. X/Open Curses does not say what "appropriate x" might be. In practice, - that is a printable ASCII graphic character. The special case "^?" is - interpreted as DEL (127). In all other cases, the character value is - AND'd with 0x1f, mapping to ASCII control codes in the range 0 through + that is a printable ASCII graphic character. The special case "^?" is + interpreted as DEL (127). In all other cases, the character value is + AND'd with 0x1f, mapping to ASCII control codes in the range 0 through 31. Other escapes include @@ -1276,141 +1274,141 @@ o and \0 for null. \0 will produce \200, which does not terminate a string but behaves - as a null character on most terminals, providing CS7 is specified. + as a null character on most terminals, providing CS7 is specified. See stty(1). - The reason for this quirk is to maintain binary compatibility of - the compiled terminfo files with other implementations, e.g., the - SVr4 systems, which document this. Compiled terminfo files use - null-terminated strings, with no lengths. Modifying this would - require a new binary format, which would not work with other + The reason for this quirk is to maintain binary compatibility of + the compiled terminfo files with other implementations, e.g., the + SVr4 systems, which document this. Compiled terminfo files use + null-terminated strings, with no lengths. Modifying this would + require a new binary format, which would not work with other implementations. Finally, characters may be given as three octal digits after a \. - A delay in milliseconds may appear anywhere in a string capability, - enclosed in $<..> brackets, as in el=\EK$<5>, and padding characters + A delay in milliseconds may appear anywhere in a string capability, + enclosed in $<..> brackets, as in el=\EK$<5>, and padding characters are supplied by tputs(3x) to provide this delay. - o The delay must be a number with at most one decimal place of + o The delay must be a number with at most one decimal place of precision; it may be followed by suffixes "*" or "/" or both. - o A "*" indicates that the padding required is proportional to the - number of lines affected by the operation, and the amount given is - the per-affected-unit padding required. (In the case of insert + o A "*" indicates that the padding required is proportional to the + number of lines affected by the operation, and the amount given is + the per-affected-unit padding required. (In the case of insert character, the factor is still the number of lines affected.) Normally, padding is advisory if the device has the xon capability; it is used for cost computation but does not trigger delays. - o A "/" suffix indicates that the padding is mandatory and forces a + o A "/" suffix indicates that the padding is mandatory and forces a delay of the given number of milliseconds even on devices for which xon is present to indicate flow control. - Sometimes individual capabilities must be commented out. To do this, - put a period before the capability name. For example, see the second + Sometimes individual capabilities must be commented out. To do this, + put a period before the capability name. For example, see the second ind in the example above.
- The ncurses library searches for terminal descriptions in several - places. It uses only the first description found. The library has a - compiled-in list of places to search which can be overridden by - environment variables. Before starting to search, ncurses eliminates + The ncurses library searches for terminal descriptions in several + places. It uses only the first description found. The library has a + compiled-in list of places to search which can be overridden by + environment variables. Before starting to search, ncurses eliminates duplicates in its search list. - o If the environment variable TERMINFO is set, it is interpreted as + o If the environment variable TERMINFO is set, it is interpreted as the pathname of a directory containing the compiled description you are working on. Only that directory is searched. - o If TERMINFO is not set, ncurses will instead look in the directory + o If TERMINFO is not set, ncurses will instead look in the directory $HOME/.terminfo for a compiled description. - o Next, if the environment variable TERMINFO_DIRS is set, ncurses - will interpret the contents of that variable as a list of colon- + o Next, if the environment variable TERMINFO_DIRS is set, ncurses + will interpret the contents of that variable as a list of colon- separated directories (or database files) to be searched. - An empty directory name (i.e., if the variable begins or ends with - a colon, or contains adjacent colons) is interpreted as the system + An empty directory name (i.e., if the variable begins or ends with + a colon, or contains adjacent colons) is interpreted as the system location /usr/share/terminfo. o Finally, ncurses searches these compiled-in locations: o a list of directories (no default value), and - o the system terminfo directory, /usr/share/terminfo (the + o the system terminfo directory, /usr/share/terminfo (the compiled-in default).
- We now outline how to prepare descriptions of terminals. The most - effective way to prepare a terminal description is by imitating the - description of a similar terminal in terminfo and to build up a + We now outline how to prepare descriptions of terminals. The most + effective way to prepare a terminal description is by imitating the + description of a similar terminal in terminfo and to build up a description gradually, using partial descriptions with vi or some other - screen-oriented program to check that they are correct. Be aware that - a very unusual terminal may expose deficiencies in the ability of the + screen-oriented program to check that they are correct. Be aware that + a very unusual terminal may expose deficiencies in the ability of the terminfo file to describe it or bugs in the screen-handling code of the test program. - To get the padding for insert line right (if the terminal manufacturer - did not document it) a severe test is to edit a large file at 9600 + To get the padding for insert line right (if the terminal manufacturer + did not document it) a severe test is to edit a large file at 9600 baud, delete 16 or so lines from the middle of the screen, then hit the "u" key several times quickly. If the terminal messes up, more padding is usually needed. A similar test can be used for insert character.
- The number of columns on each line for the terminal is given by the - cols numeric capability. If the terminal is a CRT, then the number of - lines on the screen is given by the lines capability. If the terminal - wraps around to the beginning of the next line when it reaches the - right margin, then it should have the am capability. If the terminal - can clear its screen, leaving the cursor in the home position, then - this is given by the clear string capability. If the terminal + The number of columns on each line for the terminal is given by the + cols numeric capability. If the terminal is a CRT, then the number of + lines on the screen is given by the lines capability. If the terminal + wraps around to the beginning of the next line when it reaches the + right margin, then it should have the am capability. If the terminal + can clear its screen, leaving the cursor in the home position, then + this is given by the clear string capability. If the terminal overstrikes (rather than clearing a position when a character is struck - over) then it should have the os capability. If the terminal is a + over) then it should have the os capability. If the terminal is a printing terminal, with no soft copy unit, give it both hc and os. (os - applies to storage scope terminals, such as TEKTRONIX 4010 series, as - well as hard copy and APL terminals.) If there is a code to move the + applies to storage scope terminals, such as TEKTRONIX 4010 series, as + well as hard copy and APL terminals.) If there is a code to move the cursor to the left edge of the current row, give this as cr. (Normally - this will be carriage return, control/M.) If there is a code to + this will be carriage return, control/M.) If there is a code to produce an audible signal (bell, beep, etc) give this as bel. If there is a code to move the cursor one position to the left (such as - backspace) that capability should be given as cub1. Similarly, codes - to move to the right, up, and down should be given as cuf1, cuu1, and - cud1. These local cursor motions should not alter the text they pass - over, for example, you would not normally use "cuf1= " because the + backspace) that capability should be given as cub1. Similarly, codes + to move to the right, up, and down should be given as cuf1, cuu1, and + cud1. These local cursor motions should not alter the text they pass + over, for example, you would not normally use "cuf1= " because the space would erase the character moved over. A very important point here is that the local cursor motions encoded in - terminfo are undefined at the left and top edges of a CRT terminal. + terminfo are undefined at the left and top edges of a CRT terminal. Programs should never attempt to backspace around the left edge, unless - bw is given, and never attempt to go up locally off the top. In order - to scroll text up, a program will go to the bottom left corner of the + bw is given, and never attempt to go up locally off the top. In order + to scroll text up, a program will go to the bottom left corner of the screen and send the ind (index) string. - To scroll text down, a program goes to the top left corner of the + To scroll text down, a program goes to the top left corner of the screen and sends the ri (reverse index) string. The strings ind and ri are undefined when not on their respective corners of the screen. - Parameterized versions of the scrolling sequences are indn and rin - which have the same semantics as ind and ri except that they take one - parameter, and scroll that many lines. They are also undefined except + Parameterized versions of the scrolling sequences are indn and rin + which have the same semantics as ind and ri except that they take one + parameter, and scroll that many lines. They are also undefined except at the appropriate edge of the screen. - The am capability tells whether the cursor sticks at the right edge of - the screen when text is output, but this does not necessarily apply to - a cuf1 from the last column. The only local motion which is defined - from the left edge is if bw is given, then a cub1 from the left edge - will move to the right edge of the previous row. If bw is not given, - the effect is undefined. This is useful for drawing a box around the + The am capability tells whether the cursor sticks at the right edge of + the screen when text is output, but this does not necessarily apply to + a cuf1 from the last column. The only local motion which is defined + from the left edge is if bw is given, then a cub1 from the left edge + will move to the right edge of the previous row. If bw is not given, + the effect is undefined. This is useful for drawing a box around the edge of the screen, for example. If the terminal has switch selectable - automatic margins, the terminfo file usually assumes that this is on; - i.e., am. If the terminal has a command which moves to the first - column of the next line, that command can be given as nel (newline). - It does not matter if the command clears the remainder of the current - line, so if the terminal has no cr and lf it may still be possible to + automatic margins, the terminfo file usually assumes that this is on; + i.e., am. If the terminal has a command which moves to the first + column of the next line, that command can be given as nel (newline). + It does not matter if the command clears the remainder of the current + line, so if the terminal has no cr and lf it may still be possible to craft a working nel out of one or both of them. These capabilities suffice to describe hard-copy and "glass-tty" @@ -1428,19 +1426,19 @@
Cursor addressing and other strings requiring parameters in the - terminal are described by a parameterized string capability, with - printf-like escapes such as %x in it. For example, to address the - cursor, the cup capability is given, using two parameters: the row and - column to address to. (Rows and columns are numbered from zero and - refer to the physical screen visible to the user, not to any unseen - memory.) If the terminal has memory relative cursor addressing, that + terminal are described by a parameterized string capability, with + printf-like escapes such as %x in it. For example, to address the + cursor, the cup capability is given, using two parameters: the row and + column to address to. (Rows and columns are numbered from zero and + refer to the physical screen visible to the user, not to any unseen + memory.) If the terminal has memory relative cursor addressing, that can be indicated by mrcup. - The parameter mechanism uses a stack and special % codes to manipulate - it. Typically a sequence will push one of the parameters onto the - stack and then print it in some format. Print (e.g., "%d") is a - special case. Other operations, including "%t" pop their operand from - the stack. It is noted that more complex operations are often + The parameter mechanism uses a stack and special % codes to manipulate + it. Typically a sequence will push one of the parameters onto the + stack and then print it in some format. Print (e.g., "%d") is a + special case. Other operations, including "%t" pop their operand from + the stack. It is noted that more complex operations are often necessary, e.g., in the sgr string. The % encodings have the following meanings: @@ -1448,7 +1446,7 @@ %% outputs "%" %[[:]flags][width[.precision]][doxXs] - as in printf(3), flags are [-+#] and space. Use a ":" to allow + as in printf(3), flags are [-+#] and space. Use a ":" to allow the next character to be a "-" flag, avoiding interpreting "%-" as an operator. @@ -1471,11 +1469,36 @@ %g[A-Z] get static variable [a-z] and push it - The terms "static" and "dynamic" are misleading. Historically, + The terms "static" and "dynamic" are misleading. Historically, these are simply two different sets of variables, whose values are - not reset between calls to tparm(3x). However, that fact is not + not reset between calls to tparm(3x). However, that fact is not documented in other implementations. Relying on it will adversely - impact portability to other implementations. + impact portability to other implementations: + + o SVr2 curses supported dynamic variables. Those are set only + by a %P operator. A %g for a given variable without first + setting it with %P will give unpredictable results, because + dynamic variables are an uninitialized local array on the + 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 + automatically when the setupterm function allocates the data. + + o SVr4 curses made no further improvements to the dynamic/static + variable feature. + + o Solaris XPG4 curses does not distinguish between dynamic and + static variables. They are the same. Like SVr4 curses, XPG4 + curses does not initialize these explicitly. + + o Before version 6.3, ncurses stores both dynamic and static + variables in persistent storage, initialized to zeros. + + o Beginning with version 6.3, ncurses stores static and dynamic + variables in the same manner as SVr4. Unlike other + implementations, ncurses zeros dynamic variables before the + first %g or %P operator. %'c' char constant c @@ -1580,6 +1603,115 @@ outputting rmcup), specify nrrmc. +
+ SVr4 (and X/Open Curses) list several string capabilities for setting + margins. Two were intended for use with terminals, and another six + were intended for use with printers. + + o The two terminal capabilities assume that the terminal may have the + capability of setting the left and/or right margin at the current + cursor column position. + + o The printer capabilities assume that the printer may have two types + of capability: + + o the ability to set a top and/or bottom margin using the current + line position, and + + o parameterized capabilities for setting the top, bottom, left, + right margins given the number of rows or columns. + + In practice, the categorization into "terminal" and "printer" is not + suitable: + + o The AT&T SVr4 terminal database uses smgl four times, for AT&T + hardware. + + Three of the four are printers. They lack the ability to set + left/right margins by specifying the column. + + o Other (non-AT&T) terminals may support margins but using different + assumptions from AT&T. + + For instance, the DEC VT420 supports left/right margins, but only + using a column parameter. As an added complication, the VT420 uses + two settings to fully enable left/right margins (left/right margin + mode, and origin mode). The former enables the margins, which + causes printed text to wrap within margins, but the latter is + needed to prevent cursor-addressing outside those margins. + + o Both DEC VT420 left/right margins are set with a single control + sequence. If either is omitted, the corresponding margin is set to + the left or right edge of the display (rather than leaving the + margin unmodified). + + These are the margin-related capabilities: + + Name Description + ------------------------------------------------------ + smgl Set left margin at current column + smgr Set right margin at current column + smgb Set bottom margin at current line + smgt Set top margin at current line + smgbp Set bottom margin at line N + smglp Set left margin at column N + smgrp Set right margin at column N + smgtp Set top margin at line N + smglr Set both left and right margins to L and R + smgtb Set both top and bottom margins to T and B + + When writing an application that uses these string capabilities, the + pairs should be first checked to see if each capability in the pair is + set or only one is set: + + o If both smglp and smgrp are set, each is used with a single + argument, N, that gives the column number of the left and right + margin, respectively. + + o If both smgtp and smgbp are set, each is used to set the top and + bottom margin, respectively: + + o smgtp is used with a single argument, N, the line number of the + top margin. + + o smgbp is used with two arguments, N and M, that give the line + number of the bottom margin, the first counting from the top of + the page and the second counting from the bottom. This + accommodates the two styles of specifying the bottom margin in + different manufacturers' printers. + + When designing a terminfo entry for a printer that has a settable + bottom margin, only the first or second argument should be used, + depending on the printer. When developing an application that uses + smgbp to set the bottom margin, both arguments must be given. + + Conversely, when only one capability in the pair is set: + + o If only one of smglp and smgrp is set, then it is used with two + arguments, the column number of the left and right margins, in that + order. + + o Likewise, if only one of smgtp and smgbp is set, then it is used + with two arguments that give the top and bottom margins, in that + order, counting from the top of the page. + + When designing a terminfo entry for a printer that requires setting + both left and right or top and bottom margins simultaneously, only + one capability in the pairs smglp and smgrp or smgtp and smgbp + should be defined, leaving the other unset. + + Except for very old terminal descriptions, e.g., those developed for + SVr4, the scheme just described should be considered obsolete. An + improved set of capabilities was added late in the SVr4 releases (smglr + and smgtb), which explicitly use two parameters for setting the + left/right or top/bottom margins. + + When setting margins, the line- and column-values are zero-based. + + The mgc string capability should be defined. Applications such as + tabs(1) rely upon this to reset all margins. + +
If the terminal can clear from the current position to the end of the line, leaving the cursor where it is, this should be given as el. If @@ -2515,7 +2647,7 @@
- Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on pcurses + Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on pcurses by Pavel Curtis. @@ -2540,6 +2672,7 @@