7.2.64 Term::Cap - Terminal Capabilities Interface

require Term::Cap;

$terminal = Tgetent Term::Cap { TERM => undef, OSPEED => $ospeed };
$terminal->Trequire(qw/ce ku kd/);
$terminal->Tgoto('cm', $col, $row, $FH);
$terminal->Tputs('dl', $count, $FH);

These are low-level functions to extract and use capabilities from a terminal capability (termcap) database. For general information about the use of this database, see the termcap (5) manpage.

The " new " function of Term::Cap is Tgetent() , which extracts the termcap entry for the specified terminal type and returns a reference to a terminal object. If the value associated with the TERM key in the Tgetent() argument list is false or undefined, then it defaults to the environment variable TERM .

Tgetent() looks in the environment for a TERMCAP variable. If it finds one, and if the value does not begin with a slash and looks like a termcap entry in which the terminal type name is the same as the environment string TERM , then the TERMCAP string is used directly as the termcap entry and there is no search for an entry in a termcap file somewhere.

Otherwise, Tgetent() looks in a sequence of files for the termcap entry. The sequence consists of the filename in TERMCAP , if any, followed by either the files listed in the TERMPATH environment variable, if any, or otherwise the files $HOME/.termcap , /etc/termcap , and /usr/share/misc/termcap , in that order. (Filenames in TERMPATH may be separated by either a colon or a space.) Whenever multiple files are searched and a tc field occurs in the requested entry, the entry named in the tc field must be found in the same file or one of the succeeding files. If there is a tc field in the TERMCAP environment variable string, Tgetent() continues searching as indicated above.

OSPEED is the terminal output bit rate (often mistakenly called the baud rate). OSPEED can be specified as either a POSIX termios/SYSV termio speed (where 9600 equals 9600) or an old BSD-style speed (where 13 equals 9600). See the next section, "Getting Terminal Output Speed", for code illustrating how to obtain the output speed.

Tgetent() returns a reference to a blessed object ( $terminal in the examples above). The actual termcap entry is available as $terminal->{TERMCAP} . Failure to find an appropriate termcap entry results in a call to Carp::croak() .

Once you have invoked Tgetent() , you can manage a terminal by sending control strings to it with Tgoto() and Tputs() . You can also test for the existence of particular terminal capabilities with Trequire() .

Trequire() checks to see whether the named capabilities have been specified in the terminal's termcap entry. For example, this line:

$terminal->Trequire(qw/ce ku kd/);

checks whether the ce (clear to end of line), ku (keypad up-arrow), and kd (keypad down-arrow) capabilities have been defined. Any undefined capabilities will result in a listing of those capabilities and a call to Carp::croak() .

Tgoto() produces a control string to move the cursor relative to the screen. For example, to move the cursor to the fifth line and forty-fifth column on the screen, you can say:

$row = 5; $col = 45;
$terminal->Tgoto('cm', $row, $col, STDOUT);

The first argument in this call must always be cm . If a file handle is given as the final argument, then Tgoto() sends the appropriate control string to that handle. With or without a handle, the routine returns the control string, so you could achieve the same effect this way:

$str = $terminal->Tgoto('cm', $row, $col);
print STDOUT $str;

Tgoto() performs the necessary % interpolation on the control strings. (See the termcap (5) manpage for details.)

The Tputs() routine allows you to exercise other terminal capabilities. For example, the following code deletes one line at the cursor's present position, and then turns on the bold text attribute:

$count = 1;
$terminal->Tputs('dl', $count, $FILEHANDLE);  # delete one line
$terminal->Tputs('md', $count, $FILEHANDLE);  # turn on bold attribute

Again, Tputs() returns the terminal control string, and the file handle can be omitted. The $count for such calls should normally be 1 , unless padding is required. (Padding involves the output of "no-op" characters in order to effect a delay required by the terminal device. It is most commonly required for hardcopy devices.) A count greater than 1 is taken to specify the amount of padding. See the termcap (5) manpage for more about padding.

Tputs() does not perform % interpolation. This means that the following will not work:

$terminal->Tputs('DC', 1, $FILEHANDLE);  # delete one character (WRONG!)

If the terminal control string requires numeric parameters, then you must do the interpolation yourself:

$str = $terminal->Tputs('DC', 1);
$str =~ s/%d/7/;
print STDOUT $str;        # delete seven characters

The output strings for Tputs() are cached for counts of 1. Tgoto() does not cache. $terminal->{_ xx } is the raw termcap data and $terminal->{ xx } is the cached version (where xx is the two-character terminal capability code).

require POSIX;
my $termios = new POSIX::Termios;
$termios->getattr;
my $ospeed = $termios->getospeed;

require 'ioctl.pl';
ioctl(TTY, $TIOCGETP, $sgtty);
($ispeed, $ospeed) = unpack('cc', $sgtty);