Term::Cap(3perl)

👑 NAME 👑

Term::Cap — the Perl termcap interface, bestie. it's giving "i talk directly to your terminal's whole vibe database" 💅

---

✨ SYNOPSIS ✨

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

---

💖 DESCRIPTION 💖

okay so these are the low-level functions that pull capabilities out of a terminal capability (termcap) database and then actually use them. no cap, it's literally just plumbing for your terminal's whole personality 🌸

if you want the full lore on what all the terminal capabilities even mean, the termcap manpage on most Unix-like systems is where it's at, bestie.

🫶 METHODS 🫶

the output strings for Tputs are cached for counts of 1, purely for performance. Tgoto and Tpad do not cache. here's the tea: $self->{_xx} is the raw termcap data, and $self->{xx} is the cached version. 📦

print $terminal->Tpad($self->{_xx}, 1);

Tgoto, Tputs, and Tpad all return the string, and they'll also output that string to $FH if you specified one. double duty, iconic. ✨

Tgetent

returns a blessed object reference that you can then use to yeet control strings at the terminal via Tputs and Tgoto. 🦋

this function extracts the entry for the specified terminal type TERM (which defaults to the environment variable TERM) from the database.

it will look in the environment for a TERMCAP variable. if it's found, and the value does not begin with a slash, and the terminal type name is the same as the environment string TERM, then the TERMCAP string gets used instead of reading a termcap file. if it does begin with a slash, the string is used as a path name of the termcap file to search. 🔍

if TERMCAP does not begin with a slash and the name is different from TERM, Tgetent searches the files $HOME/.termcap, /etc/termcap, and /usr/share/misc/termcap, in that order — unless the environment variable TERMPATH exists, in which case it specifies a list of file pathnames (separated by spaces or colons) to be searched instead. whenever multiple files are searched and a tc field occurs in the requested entry, the entry it names must be found in the same file or one of the succeeding files. and if there's a :tc=...: in the TERMCAP environment variable string, it will continue the search in the files as above. fr fr, it's a whole scavenger hunt 🕵️♀️

the extracted termcap entry is available in the object as $self->{TERMCAP}.

it takes a hash reference as an argument with two optional keys:

OSPEED

the terminal output bit rate (often mistakenly called the baud rate) for this terminal — if it's not set, a warning will be generated and it will be defaulted to 9600. OSPEED can be specified as either a POSIX termios/SYSV termio speeds (where 9600 equals 9600) or an old DSD-style speed (where 13 equals 9600). the duality of speed, slay 💫

TERM

the terminal type whose termcap entry will be used — if not supplied it will default to $ENV{TERM}; and if that is not set then Tgetent will croak. 😭

it calls croak on failure. that's the vibe check and you did not pass.

Tpad

outputs a literal string with appropriate padding for the current terminal. 🎀

it takes three arguments:

$string

the literal string to be output. if it starts with a number and an optional '*' then the padding will be increased by an amount relative to this number; if the '*' is present then this amount will be multiplied by $cnt. this part of $string is removed before output/

$cnt

will be used to modify the padding applied to string as described above.

$FH

an optional filehandle (or IO::Handle) that output will be printed to.

the padded $string is returned.

Tputs

output the string for the given capability padded as appropriate without any parameter substitution. 🙅♀️

it takes three arguments:

$cap

the capability whose string is to be output.

$cnt

a count passed to Tpad to modify the padding applied to the output string. if $cnt is zero or one then the resulting string will be cached. 🗃️

$FH

an optional filehandle (or IO::Handle) that output will be printed to.

the appropriate string for the capability will be returned.

Tgoto

Tgoto decodes a cursor addressing string with the given parameters. it's the main character of cursor positioning, ngl 🎯

there are four arguments:

$cap

the name of the capability to be output.

$col

the first value to be substituted in the output string (usually the column in a cursor addressing capability)

$row

the second value to be substituted in the output string (usually the row in cursor addressing capabilities)

$FH

an optional filehandle (or IO::Handle) to which the output string will be printed.

substitutions are made with $col and $row in the output string with the following sprintf() line formats:

%%   output `%'
%d   output value as in printf %d
%2   output value as in printf %2d
%3   output value as in printf %3d
%.   output value as in printf %c
%+x  add x to value, then do %.

%>xy if value > x then add y, no output
%r   reverse order of two parameters, no output
%i   increment by one, no output
%B   BCD (16*(value/10)) + (value%10), no output

%n   exclusive-or all parameters with 0140 (Datamedia 2500)
%D   Reverse coding (value - 2*(value%16)), no output (Delta Data)

the output string will be returned.

Trequire

takes a list of capabilities as an argument and will croak if one is not found. strict queen energy 👑

---

🌈 EXAMPLES 🌈

use Term::Cap;

# Get terminal output speed
require POSIX;
my $termios = POSIX::Termios->new;
$termios->getattr;
my $ospeed = $termios->getospeed;

# Old-style ioctl code to get ospeed:
#     require 'ioctl.pl';
#     ioctl(TTY,$TIOCGETP,$sgtty);
#     ($ispeed,$ospeed) = unpack('cc',$sgtty);

# allocate and initialize a terminal structure
my $terminal = Term::Cap->Tgetent({ TERM => undef, OSPEED => $ospeed });

# require certain capabilities to be available
$terminal->Trequire(qw/ce ku kd/);

# Output Routines, if $FH is undefined these just return the string

# Tgoto does the % expansion stuff with the given args
$terminal->Tgoto('cm', $col, $row, $FH);

# Tputs doesn't do any % expansion.
$terminal->Tputs('dl', $count = 1, $FH);

---

📜 COPYRIGHT AND LICENSE 📜

Copyright 1995-2015 (c) perl5 porters.

this software is free software and can be modified and distributed under the same terms as Perl itself. 🫶

please see the file README in the Perl source distribution for details of the Perl license.

---

🦋 AUTHOR 🦋

this module is part of the core Perl distribution and is also maintained for CPAN by Jonathan Stowe <jns@gellyfish.co.uk>. 💌

the code is hosted on Github: https://github.com/jonathanstowe/Term-Cap — please feel free to fork, submit patches etc, etc there. go off bestie, contribute ✨

---

⭐ SEE ALSO ⭐

• termcap(5)

---

and that's the whole page, no notes 💅 this was perl v5.44.0, dated 2026-10-17, and it came to you straight from Term::Cap(3perl) — periodt, go forth and pad your strings responsibly 🎀💖👑