DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
terminfo programming

3. Specify capabilities

Once you know the capabilities of your terminal, you have to describe them in your terminal description. You describe them with a string of comma-separated fields that contain the abbreviated terminfo name and, in some cases, the terminal's value for each capability. For example, bel is the abbreviated name for the beeping or ringing capability. On most terminals, a <CTRL-G> is the instruction that produces a beeping sound. Therefore, the beeping capability would be shown in the terminal description as bel=^G,.

The list of capabilities may continue onto multiple lines as long as white space (that is, tabs and spaces) begins every line but the first of the description. Comments can be included in the description by putting a # at the beginning of the line.

The oldterminfo(4) manual page has a complete list of the capabilities you can use in a terminal description. This list contains the name of the capability, the abbreviated name used in the database, the two-letter code that corresponds to the old termcap database name, and a short description of the capability. The abbreviated name that you will use in your database descriptions is shown in the column titled ``Capname.''


NOTE: For a curses program to run on any given terminal, its description in the terminfo database must include, at least, the capabilities to move a cursor in all four directions and to clear the screen.

A terminal's character sequence (value) for a capability can be a keyed operation (like <CTRL-G>), a numeric value, or a parameter string containing the sequence of operations required to achieve the particular capability. In a terminal description, certain characters are used after the capability name to show what type of character sequence is required. Explanations of these characters follow:


#
This shows a numeric value is to follow. This character follows a capability that needs a number as a value. For example, the number of columns is defined as cols#80.

=
This shows that the capability value is the character string that follows. This string instructs the terminal how to act and may actually be a sequence of commands. There are certain characters used in the instruction strings that have special meanings. These special characters follow:

^
This shows a control character is to be used. For example, the beeping sound is produced by a <CTRL-G>. This would be shown as ^G.

\E or \e
These characters followed by another character show an escape instruction. An entry of \EC would transmit to the terminal as <ESCAPE-C>.

\n
These characters provide a <NL> character sequence.

\l
These characters provide a linefeed character sequence.

\r
These characters provide a return character sequence.

\t
These characters provide a tab character sequence.

\b
These characters provide a backspace character sequence.

\f
These characters provide a formfeed character sequence.

\s
These characters provide a space character sequence.

\nnn
This is a character whose three-digit octal is nnn, where nnn can be one to three digits.

$< >
These symbols are used to show a delay in milliseconds. The desired length of delay is enclosed inside the ``less than/greater than'' symbols (< >). The amount of delay may be a whole number, a numeric value to one decimal place (tenths), or either form followed by an asterisk (*). The * shows that the delay will be proportional to the number of lines affected by the operation. For example, a 20-millisecond delay per line would appear as $<20*>. See the oldterminfo(4) manual page for more information about delays and padding.

Sometimes, it may be necessary to comment out a capability so that the terminal ignores this particular field. This is done by placing a period ( . ) in front of the abbreviated name for the capability. For example, if you would like to comment out the beeping capability, the description entry would appear as

   .bel=^G,
With this background information about specifying capabilities, let us add the capability string to our description of myterm. We will consider basic, screen-oriented, keyboard-entered, and parameter string capabilities.

Basic capabilities

Some capabilities common to most terminals are bells, columns, lines on the screen, and overstriking of characters, if necessary. Suppose our fictitious terminal has these and a few other capabilities, as listed below. Note that the list gives the abbreviated terminfo name for each capability in the parentheses following the capability description:

By combining the name string (see ``1. Name the terminal'') and the capability descriptions that we now have, we get the following general terminfo database entry:
   myterm|mytm|mine|fancy|terminal|My FANCY terminal,
   	am, bel=^G, cols#80, lines#30, xon,

Screen-oriented capabilities

Screen-oriented capabilities manipulate the contents of a screen. Our example terminal myterm has the following screen-oriented capabilities. Again, the abbreviated command associated with the given capability is shown in parentheses.

The revised terminal description for myterm including these screen-oriented capabilities follows:
   myterm|mytm|mine|fancy|terminal|My FANCY Terminal,
   	am, bel=^G, cols#80, lines#30, xon,
   	cr=^M, cuu1=^K, cud1=^J, cub1=^H, cuf1=^L,
   	smso=\ED, rmso=\EZ, el=\EK$<3>, ind=\n,

Keyboard-entered capabilities

Keyboard-entered capabilities are sequences generated when a key is typed on a terminal keyboard. Most terminals have, at least, a few special keys on their keyboard, such as arrow keys and the backspace key. Our example terminal has several of these keys whose sequences are, as follows:

Adding this new information to our database entry for myterm produces:
   myterm|mytm|mine|fancy|terminal|My FANCY Terminal,
   	am, bel=^G, cols#80, lines#30, xon,
   	cr=^M, cuu1=^K, cud1=^J, cub1=^H, cuf1=^L,
   	smso=\ED, rmso=\EZ, el=\EK$<3>, ind=,
   	kbs=^H, kcuu1=\E[A, kcud1=\E[B, kcuf1=\E[C,
   	kcub1=\E[D, khome=\E[H,

Parameter string capabilities

Parameter string capabilities are capabilities that can take parameters -- for example, those used to position a cursor on a screen or turn on a combination of video modes. To address a cursor, the cup capability is used and is passed two parameters: the row and column to address. String capabilities, such as cup and set attributes (sgr) capabilities, are passed arguments in a terminfo program by the tparm routine.

The arguments to string capabilities are manipulated with special '%' sequences similar to those found in a printf [see fprintf(3S)] statement. In addition, many of the features found on a simple stack-based RPN calculator are available. cup, as noted above, takes two arguments: the row and column. sgr, takes nine arguments, one for each of the nine video attributes. See oldterminfo(4) for the list and order of the attributes and further examples of sgr.

Our fancy terminal's cursor position sequence requires a row and column to be output as numbers separated by a semicolon, preceded by <ESCAPE->[ and followed with H. The coordinate numbers are 1-based rather than 0-based. Thus, to move to row 5, column 18, from (0,0), the sequence 'ESCAPE-[ 6 ; 19 H' would be output.

Integer arguments are pushed onto the stack with a '%p' sequence followed by the argument number, such as '%p2' to push the second argument. A shorthand sequence to increment the first two arguments is '%i'. To output the top number on the stack as a decimal, a '%d' sequence is used, exactly as in printf.

Our terminal's cup sequence is:

   cup=\E[%i%p1%d;%p2%dH,
which is built from the following elements:

\E[ Output <ESC-[>
%i Increment the two arguments
%p1 Push the first argument (the row) onto the stack
%d Output the row as a decimal
; Output a semi-colon
%p2 Push the second argument (the column) onto the stack
%d Output the column as a decimal
H Output the trailing letter

Adding this new information to our database entry for myterm produces:

   myterm|mytm|mine|fancy|terminal|My FANCY Terminal,
   	am, bel=^G, cols#80, lines#30, xon,
   	cr=^M, cuu1=^K, cud1=^J, cub1=^H, cuf1=^L,
   	smso=\ED, rmso=\EZ, el=\EK$<3>, ind=,
   	kbs=^H, kcuu1=\E[A, kcud1=\E[B, kcuf1=\E[C,
   	kcub1=\E[D, khome=\E[H,
   	cup=\E[%i%p1%d;%p2%dH,
See oldterminfo(4) for more information about parameter string capabilities.
Next topic: 4. Compile the description
Previous topic: 2. Learn about the capabilities

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004