X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fterminfo.5.html;h=859a54554379300821cb044c0e193dde7016feb0;hb=122d3739b3c11c83decc625d53f26fff6e825710;hp=82381c9d26290808aafc6eff677d0fc3e67d54c6;hpb=9b51794524995304d8788e42aacb36feede9364f;p=ncurses.git diff --git a/doc/html/man/terminfo.5.html b/doc/html/man/terminfo.5.html index 82381c9d..859a5455 100644 --- a/doc/html/man/terminfo.5.html +++ b/doc/html/man/terminfo.5.html @@ -5,7 +5,7 @@ * Note: this must be run through tbl before nroff. * The magic cookie on the first line triggers this under some man programs. **************************************************************************** - * Copyright 2018-2020,2021 Thomas E. Dickey * + * Copyright 2018-2021,2023 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -32,10 +32,10 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: terminfo.head,v 1.41 2021/08/15 19:32:53 tom Exp @ + * @Id: terminfo.head,v 1.53 2023/10/14 19:53:57 tom Exp @ * Head of terminfo man page ends here **************************************************************************** - * Copyright 2018-2020,2021 Thomas E. Dickey * + * Copyright 2018-2022,2023 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -62,32 +62,31 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: terminfo.tail,v 1.106 2021/08/28 19:00:29 tom Exp @ + * @Id: terminfo.tail,v 1.134 2023/10/14 19:18:14 tom Exp @ *.in -2 *.in +2 *.in -2 *.in +2 - *.TH -->
--terminfo(5) File Formats terminfo(5) +terminfo(5) File formats terminfo(5)
- terminfo - terminal capability database + terminfo - terminal capability database
@@ -106,7 +105,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 20210828). + This manual describes ncurses version 6.4 (patch 20231111).
@@ -161,6 +160,7 @@ following suffixes should be used where possible: Suffix Meaning Example + ------------------------------------------------------------- -nn Number of lines on the screen aaa-60 -np Number of pages of memory c100-4p -am With automargins (usually the default) vt100-am @@ -243,25 +243,29 @@ terminfo description block and available to terminfo-using code. In each line of the table, - The variable is the name by which the programmer (at the terminfo - level) accesses the capability. + o The variable is the name by which the programmer (at the terminfo + level) accesses the capability. + + o The capname (Cap-name) is the short name used in the text of the + database, and is used by a person updating the database. + + Whenever possible, capnames are chosen to be the same as or similar + to the ANSI X3.64-1979 standard (now superseded by ECMA-48, which + uses identical or very similar names). Semantics are also intended + to match those of the specification. - The capname is the short name used in the text of the database, and is - used by a person updating the database. Whenever possible, capnames - are chosen to be the same as or similar to the ANSI X3.64-1979 standard - (now superseded by ECMA-48, which uses identical or very similar - names). Semantics are also intended to match those of the - specification. + Capability names have no hard length limit, but an informal limit + of 5 characters has been adopted to keep them short and to allow + the tabs in the source file Caps to line up nicely. - The termcap code is the old termcap capability name (some capabilities - are new, and have names which termcap did not originate). + o The termcap (Tcap) code is the old capability name (some + capabilities are new, and have names which termcap did not + originate). - Capability names have no hard length limit, but an informal limit of 5 - characters has been adopted to keep them short and to allow the tabs in - the source file Caps to line up nicely. + o Finally, the description field attempts to convey the semantics of + the capability. - Finally, the description field attempts to convey the semantics of the - capability. You may find some codes in the description field: + You may find some codes in the description field: (P) indicates that padding may be specified @@ -283,9 +287,6 @@ Variable Cap- TCap Description Booleans name Code - - - auto_left_margin bw bw cub1 wraps from column 0 to last column @@ -349,9 +350,9 @@ f2=ctrl C) no_pad_char npc NP pad character does not exist + non_dest_scroll_region ndscr ND scrolling region is non-destructive - non_rev_rmcup nrrmc NR smcup does not reverse rmcup over_strike os os terminal can @@ -417,7 +418,6 @@ with SVr4's printer support. - Variable Cap- TCap Description Numeric name Code bit_image_entwining bitwin Yo number of passes for @@ -483,7 +483,6 @@ change_res_horz chr ZC Change horizontal resolution to #1 - change_res_vert cvr ZD Change vertical resolution to #1 change_scroll_region csr cs change region to @@ -958,9 +957,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 +1009,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 +1020,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 +1074,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 +1103,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,41 +1136,46 @@
- 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 ncurses library uses a few of these user-defined capabilities, as + described in user_caps(5). Other user-defined capabilities (including + function keys) are described in the terminal database, in the section + on NCURSES USER-DEFINABLE CAPABILITIES +
The following entry, describing an ANSI-standard terminal, is @@ -1233,7 +1235,7 @@ 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 + 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 @@ -1245,7 +1247,7 @@ o Both \E and \e map to an ESCAPE character, - o ^x maps to a control-x for any appropriate x, and + o ^xx maps to a control-x for any appropriate x, and o the sequences @@ -1313,104 +1315,123 @@
- 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. + Terminal descriptions in ncurses are stored in terminal databases. + These databases, which are found by their pathname, may be configured + either as directory trees or hashed databases (see term(5)), + + The library uses a compiled-in list of pathnames, which can be + overridden by environment variables. Before starting to search, + ncurses checks the search list, eliminating duplicates and pathnames + where no terminal database is found. The ncurses library reads the + first description which passes its consistency checks. - 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 The environment variable TERMINFO is checked first, for a terminal + database containing the terminal description. - o If TERMINFO is not set, ncurses will instead look in the directory - $HOME/.terminfo for a compiled description. + o Next, ncurses looks in $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- - separated directories (or database files) to be searched. + This is an optional feature which may be omitted entirely from the + library, or limited to prevent accidental use by privileged + applications. - An empty directory name (i.e., if the variable begins or ends with - a colon, or contains adjacent colons) is interpreted as the system + o Next, if the environment variable TERMINFO_DIRS is set, ncurses + interprets the contents of that variable as a list of colon- + separated pathnames of terminal databases to be searched. + + An empty pathname (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 a list of directories (/usr/share/terminfo), and + + o the system terminfo directory, /usr/share/terminfo + + The TERMINFO variable can contain a terminal description instead of the + pathname of a terminal database. If this variable begins with "hex:" + or "b64:" then ncurses reads a terminal description from hexadecimal- + or base64-encoded data, and if that description matches the name + sought, will use that. This encoded data can be set using the "-Q" + option of tic or infocmp. - o the system terminfo directory, /usr/share/terminfo (the - compiled-in default). + The preceding addresses the usual configuration of ncurses, which uses + terminal descriptions prepared in terminfo format. While termcap is + less expressive, ncurses can also be configured to read termcap + descriptions. In that configuration, it checks the TERMCAP and + TERMPATH variables (for content and search path, respectively) after + the system terminal database.
- 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 +1449,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,11 +1469,11 @@ %% 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. - %c print pop() like %c in printf + %c print pop() like %c in printf %s print pop() like %s in printf @@ -1462,7 +1483,7 @@ %P[a-z] set dynamic variable [a-z] to pop() - %g[a-z]/ + %g[a-z] get dynamic variable [a-z] and push it %P[A-Z] @@ -1471,36 +1492,41 @@ %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: - 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 + 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 + 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 + 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 + 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. + o Beginning with version 6.3, ncurses stores static and dynamic + variables in the same manner as SVr4. + + o Unlike other implementations, ncurses zeros dynamic + variables before the first %g or %P operator. + + o Like SVr2, the scope of dynamic variables in ncurses is + within the current call to tparm. Use static variables if + persistent storage is needed. %'c' char constant c @@ -1547,28 +1573,31 @@ variables are persistent across escape-string evaluations. Consider the HP2645, which, to get to row 3 and column 12, needs to be - sent \E&a12c03Y padded for 6 milliseconds. Note that the order of the - rows and columns is inverted here, and that the row and column are - printed as two digits. Thus its cup capability is - "cup=6\E&%p2%2dc%p1%2dY". - - The Microterm ACT-IV needs the current row and column sent preceded by - a ^T, with the row and column simply encoded in binary, - "cup=^T%p1%c%p2%c". Terminals which use "%c" need to be able to - backspace the cursor (cub1), and to move the cursor up one line on the - screen (cuu1). This is necessary because it is not always safe to - transmit \n ^D and \r, as the system may change or discard them. (The - library routines dealing with terminfo set tty modes so that tabs are - never expanded, so \t is safe to send. This turns out to be essential - for the Ann Arbor 4080.) - - A final example is the LSI ADM-3a, which uses row and column offset by - a blank character, thus "cup=\E=%p1%' '%+%c%p2%' '%+%c". After sending - "\E=", this pushes the first parameter, pushes the ASCII value for a - space (32), adds them (pushing the sum on the stack in place of the two - previous values) and outputs that value as a character. Then the same - is done for the second parameter. More complex arithmetic is possible - using the stack. + sent \E&a12c03Y padded for 6 milliseconds. The order of the rows and + columns is inverted here, and the row and column are printed as two + digits. The corresponding terminal description is expressed thus: + cup=\E&a%p2%dc%p1%dY$<6>, + + The Microterm ACT-IV needs the current row and column sent preceded by + a ^T, with the row and column simply encoded in binary, + cup=^T%p1%c%p2%c + + Terminals which use "%c" need to be able to backspace the cursor + (cub1), and to move the cursor up one line on the screen (cuu1). This + is necessary because it is not always safe to transmit \n ^D and \r, as + the system may change or discard them. (The library routines dealing + with terminfo set tty modes so that tabs are never expanded, so \t is + safe to send. This turns out to be essential for the Ann Arbor 4080.) + + A final example is the LSI ADM-3a, which uses row and column offset by + a blank character, thus + cup=\E=%p1%' '%+%c%p2%' '%+%c + + After sending "\E=", this pushes the first parameter, pushes the ASCII + value for a space (32), adds them (pushing the sum on the stack in + place of the two previous values) and outputs that value as a + character. Then the same is done for the second parameter. More + complex arithmetic is possible using the stack.
@@ -1605,6 +1634,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 @@ -1775,26 +1913,26 @@ If there is a sequence to set arbitrary combinations of modes, this should be given as sgr (set attributes), taking 9 parameters. Each - parameter is either 0 or nonzero, as the corresponding attribute is on - or off. The 9 parameters are, in order: standout, underline, reverse, - blink, dim, bold, blank, protect, alternate character set. Not all - modes need be supported by sgr, only those for which corresponding - separate attribute commands exist. + parameter is either zero (0) or nonzero, as the corresponding attribute + is on or off. The 9 parameters are, in order: standout, underline, + reverse, blink, dim, bold, blank, protect, alternate character set. + Not all modes need be supported by sgr, only those for which + corresponding separate attribute commands exist. For example, the DEC vt220 supports most of the modes: - tparm parameter attribute escape sequence - - none none \E[0m - p1 standout \E[0;1;7m - p2 underline \E[0;4m - p3 reverse \E[0;7m - p4 blink \E[0;5m - p5 dim not available - p6 bold \E[0;1m - p7 invis \E[0;8m - p8 protect not used - p9 altcharset ^O (off) ^N (on) + tparm Parameter Attribute Escape Sequence + ------------------------------------------------ + none none \E[0m + p1 standout \E[0;1;7m + p2 underline \E[0;4m + p3 reverse \E[0;7m + p4 blink \E[0;5m + p5 dim not available + p6 bold \E[0;1m + p7 invis \E[0;8m + p8 protect not used + p9 altcharset ^O (off) ^N (on) We begin each escape sequence by turning off any existing modes, since there is no quick way to determine whether they are active. Standout @@ -1811,16 +1949,16 @@ Writing out the above sequences, along with their dependencies yields - sequence when to output terminfo translation - - \E[0 always \E[0 - ;1 if p1 or p6 %?%p1%p6%|%t;1%; - ;4 if p2 %?%p2%|%t;4%; - ;5 if p4 %?%p4%|%t;5%; - ;7 if p1 or p3 %?%p1%p3%|%t;7%; - ;8 if p7 %?%p7%|%t;8%; - m always m - ^N or ^O if p9 ^N, else ^O %?%p9%t^N%e^O%; + Sequence When to Output terminfo Translation + ---------------------------------------------------- + \E[0 always \E[0 + ;1 if p1 or p6 %?%p1%p6%|%t;1%; + ;4 if p2 %?%p2%|%t;4%; + ;5 if p4 %?%p4%|%t;5%; + ;7 if p1 or p3 %?%p1%p3%|%t;7%; + ;8 if p7 %?%p7%|%t;8%; + m always m + ^N or ^O if p9 ^N, else ^O %?%p9%t^N%e^O%; Putting this all together into the sgr sequence gives: @@ -2104,42 +2242,41 @@ 4410v1 added. This alternate character set may be specified by the acsc capability. - Glyph ACS Ascii acsc acsc - Name Name Default Char Value + ASCII acsc acsc + Glyph Name ACS Name Fallback Symbol Value -------------------------------------------------------------------- - arrow pointing right ACS_RARROW > + 0x2b - arrow pointing left ACS_LARROW < , 0x2c - arrow pointing up ACS_UARROW ^ - 0x2d - arrow pointing down ACS_DARROW v . 0x2e - solid square block ACS_BLOCK # 0 0x30 - diamond ACS_DIAMOND + ` 0x60 - checker board (stipple) ACS_CKBOARD : a 0x61 - - degree symbol ACS_DEGREE \ f 0x66 - plus/minus ACS_PLMINUS # g 0x67 - board of squares ACS_BOARD # h 0x68 - lantern symbol ACS_LANTERN # i 0x69 - lower right corner ACS_LRCORNER + j 0x6a - upper right corner ACS_URCORNER + k 0x6b - upper left corner ACS_ULCORNER + l 0x6c - lower left corner ACS_LLCORNER + m 0x6d - large plus or crossover ACS_PLUS + n 0x6e - scan line 1 ACS_S1 ~ o 0x6f - scan line 3 ACS_S3 - p 0x70 - horizontal line ACS_HLINE - q 0x71 - scan line 7 ACS_S7 - r 0x72 - scan line 9 ACS_S9 _ s 0x73 - tee pointing right ACS_LTEE + t 0x74 - tee pointing left ACS_RTEE + u 0x75 - tee pointing up ACS_BTEE + v 0x76 - tee pointing down ACS_TTEE + w 0x77 - vertical line ACS_VLINE | x 0x78 - less-than-or-equal-to ACS_LEQUAL < y 0x79 - greater-than-or-equal-to ACS_GEQUAL > z 0x7a - greek pi ACS_PI * { 0x7b - not-equal ACS_NEQUAL ! | 0x7c - UK pound sign ACS_STERLING f } 0x7d - bullet ACS_BULLET o ~ 0x7e + arrow pointing right ACS_RARROW > + 0x2b + arrow pointing left ACS_LARROW < , 0x2c + arrow pointing up ACS_UARROW ^ - 0x2d + arrow pointing down ACS_DARROW v . 0x2e + solid square block ACS_BLOCK # 0 0x30 + diamond ACS_DIAMOND + ` 0x60 + checker board (stipple) ACS_CKBOARD : a 0x61 + degree symbol ACS_DEGREE \ f 0x66 + plus/minus ACS_PLMINUS # g 0x67 + board of squares ACS_BOARD # h 0x68 + lantern symbol ACS_LANTERN # i 0x69 + lower right corner ACS_LRCORNER + j 0x6a + upper right corner ACS_URCORNER + k 0x6b + upper left corner ACS_ULCORNER + l 0x6c + lower left corner ACS_LLCORNER + m 0x6d + large plus or crossover ACS_PLUS + n 0x6e + scan line 1 ACS_S1 ~ o 0x6f + scan line 3 ACS_S3 - p 0x70 + horizontal line ACS_HLINE - q 0x71 + scan line 7 ACS_S7 - r 0x72 + scan line 9 ACS_S9 _ s 0x73 + tee pointing right ACS_LTEE + t 0x74 + tee pointing left ACS_RTEE + u 0x75 + tee pointing up ACS_BTEE + v 0x76 + tee pointing down ACS_TTEE + w 0x77 + vertical line ACS_VLINE | x 0x78 + less-than-or-equal-to ACS_LEQUAL < y 0x79 + greater-than-or-equal-to ACS_GEQUAL > z 0x7a + greek pi ACS_PI * { 0x7b + not-equal ACS_NEQUAL ! | 0x7c + UK pound sign ACS_STERLING f } 0x7d + bullet ACS_BULLET o ~ 0x7e A few notes apply to the table itself: @@ -2220,28 +2357,30 @@ free to map these as it likes, but the RGB values indicate normal locations in color space. - Color #define Value RGB - black COLOR_BLACK 0 0, 0, 0 - red COLOR_RED 1 max,0,0 - green COLOR_GREEN 2 0,max,0 - yellow COLOR_YELLOW 3 max,max,0 - blue COLOR_BLUE 4 0,0,max - magenta COLOR_MAGENTA 5 max,0,max - cyan COLOR_CYAN 6 0,max,max - white COLOR_WHITE 7 max,max,max + Color #define Value RGB + ------------------------------------------------ + black COLOR_BLACK 0 0, 0, 0 + red COLOR_RED 1 max, 0, 0 + green COLOR_GREEN 2 0, max, 0 + yellow COLOR_YELLOW 3 max, max, 0 + blue COLOR_BLUE 4 0, 0, max + magenta COLOR_MAGENTA 5 max, 0, max + cyan COLOR_CYAN 6 0, max, max + white COLOR_WHITE 7 max, max, max The argument values of setf/setb historically correspond to a different mapping, i.e., - Color #define Value RGB - black COLOR_BLACK 0 0, 0, 0 - blue COLOR_BLUE 1 0,0,max - green COLOR_GREEN 2 0,max,0 - cyan COLOR_CYAN 3 0,max,max - red COLOR_RED 4 max,0,0 - magenta COLOR_MAGENTA 5 max,0,max - yellow COLOR_YELLOW 6 max,max,0 - white COLOR_WHITE 7 max,max,max + Color #define Value RGB + ------------------------------------------------ + black COLOR_BLACK 0 0, 0, 0 + blue COLOR_BLUE 1 0, 0, max + green COLOR_GREEN 2 0, max, 0 + cyan COLOR_CYAN 3 0, max, max + red COLOR_RED 4 max, 0, 0 + magenta COLOR_MAGENTA 5 max, 0, max + yellow COLOR_YELLOW 6 max, max, 0 + white COLOR_WHITE 7 max, max, max It is important to not confuse the two sets of color capabilities; otherwise red/blue will be interchanged on the display. @@ -2271,23 +2410,25 @@ of attributes not to be used when colors are enabled. The correspondence with the attributes understood by curses is as follows: - Attribute Bit Decimal Set by - A_STANDOUT 0 1 sgr - A_UNDERLINE 1 2 sgr - A_REVERSE 2 4 sgr - A_BLINK 3 8 sgr - A_DIM 4 16 sgr - A_BOLD 5 32 sgr - A_INVIS 6 64 sgr - A_PROTECT 7 128 sgr - A_ALTCHARSET 8 256 sgr - A_HORIZONTAL 9 512 sgr1 - A_LEFT 10 1024 sgr1 - A_LOW 11 2048 sgr1 - A_RIGHT 12 4096 sgr1 - A_TOP 13 8192 sgr1 - A_VERTICAL 14 16384 sgr1 - A_ITALIC 15 32768 sitm + Attribute Bit Decimal Set by + -------------------------------------- + A_STANDOUT 0 1 sgr + A_UNDERLINE 1 2 sgr + A_REVERSE 2 4 sgr + A_BLINK 3 8 sgr + A_DIM 4 16 sgr + A_BOLD 5 32 sgr + A_INVIS 6 64 sgr + A_PROTECT 7 128 sgr + A_ALTCHARSET 8 256 sgr + A_HORIZONTAL 9 512 sgr1 + A_LEFT 10 1024 sgr1 + A_LOW 11 2048 sgr1 + A_RIGHT 12 4096 sgr1 + A_TOP 13 8192 sgr1 + + A_VERTICAL 14 16384 sgr1 + A_ITALIC 15 32768 sitm For example, on many IBM PC consoles, the underline attribute collides with the foreground color blue and is not available in color mode. @@ -2401,12 +2542,18 @@ safe length for a termcap entry 1k-1 (1023) bytes. Depending on what the application and the termcap library being used does, and where in the termcap file the terminal type that tgetent is searching for is, - several bad things can happen. + several bad things can happen: + + o some termcap libraries print a warning message, + + o some exit if they find an entry that's longer than 1023 bytes, + + o some neither exit nor warn, doing nothing useful, and + + o some simply truncate the entries to 1023 bytes. - Some termcap libraries print a warning message or exit if they find an - entry that's longer than 1023 bytes; others do not; others truncate the - entries to 1023 bytes. Some application programs allocate more than - the recommended 1K for the termcap entry; others do not. + Some application programs allocate more than the recommended 1K for the + termcap entry; others do not. Each termcap entry has two important sizes associated with it: before "tc" expansion, and after "tc" expansion. "tc" is the capability that @@ -2500,9 +2647,9 @@ X/Open Curses does not mention italics. Portable applications must assume that numeric capabilities are signed 16-bit values. This - includes the no_color_video (ncv) capability. The 32768 mask value - used for italics with ncv can be confused with an absent or cancelled - ncv. If italics should work with colors, then the ncv value must be + includes the no_color_video (ncv) capability. The 32768 mask value + used for italics with ncv can be confused with an absent or cancelled + ncv. If italics should work with colors, then the ncv value must be specified, even if it is zero. Different commercial ports of terminfo and curses support different @@ -2530,22 +2677,23 @@
- /usr/share/terminfo/?/* files containing terminal descriptions - - -
- infocmp(1m), tabs(1), tic(1m), curses(3x), curs_color(3x), - curs_variables(3x), printf(3), term_variables(3x). term(5). - user_caps(5). + /usr/share/terminfo + compiled terminal description database directory
- 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. +
+ infocmp(1m), tabs(1), tic(1m), curses(3x), curs_color(3x), + curs_terminfo(3x), curs_variables(3x), printf(3), term_variables(3x), + term(5), user_caps(5) + + - terminfo(5) +ncurses 6.4 2023-10-14 terminfo(5)