Inspect and Maintain Legacy termcap Entries Safely

You will inspect the terminal description selected by TERM, view it in termcap syntax, and understand where a legacy termcap file fits into a modern Linux system. Allow about fifteen minutes. You need a shell and the ncurses infocmp utility. The examples are read-only until you deliberately choose to edit a database.

This guide follows the installed termcap(5) manual from Linux man-pages 6.7, supplied by Debian package version manpages 6.7-2. The manual calls termcap obsolete and recommends terminfo for new programs. That is a practical boundary: inspect termcap when an old program requires it, but do not introduce it into a new application without a compatibility reason.

1. Check the terminal name

Termcap is indexed by the TERM environment variable. First inspect the value that applications will use. This is an ordinary command and does not need elevated privileges:

$ printf 'TERM=%s\n' "$TERM"
TERM=dumb
$ command -v infocmp
/home/linuxbrew/.linuxbrew/bin/infocmp

Your terminal name will probably differ. Do not replace it with a name copied from another host unless that terminal really is in use. A wrong value can make a program choose escape sequences that your terminal does not understand.

Checkpoint: record the exact TERM value. The commands below use $TERM, so they follow the current shell rather than assuming a particular emulator.

2. Inspect the modern terminfo entry

Most current systems store compiled terminal descriptions in terminfo databases. With no format option, infocmp prints a source-like terminfo description. The -1 option puts each capability on its own line, which makes a long entry easier to search:

$ infocmp -1 "$TERM" | sed -n '1,24p'
#       Reconstructed via infocmp from file: .../d/dumb
dumb|80-column dumb tty,
        am,
        cols#80,
        bel=^G,
        cr=\r,
        cud1=\n,
        ind=\n,
        lines#24,
        ...

The exact entry and output depend on the host. Boolean capabilities appear first, followed by numeric and string capabilities. For example, am means automatic margins, co#80 means 80 columns in termcap notation, and cl= would hold the clear-screen string. The output is a description, not a command to send directly to the terminal.

3. Convert the entry to termcap syntax

Use -C when an old tool expects termcap capability names and punctuation. Add -r to ask ncurses to include non-standard capabilities. This prints to standard output and changes no database:

$ infocmp -C -r -1 "$TERM" | sed -n '1,22p'
#       Reconstructed via infocmp from file: .../d/dumb
dumb|80-column dumb tty:\
        :am:\
        :co#80:\
        :bl=^G:\
        :cr=\r:\
        :do=\n:\
        :sf=\n:\
        ...

Termcap entries use a colon between fields. Names before the first colon are separated by vertical bars, and a trailing backslash continues one logical entry over several physical lines. Boolean fields have no value, numeric fields use #, and strings use =. The displayed escape sequences are data for a terminal library, not shell commands.

Checkpoint: if an old program only needs a capability name, search the generated output rather than editing a file:

$ infocmp -C -r "$TERM" | grep -E '(^|:)co#|(^|:)li#|(^|:)cl='
        :co#80:\

Output formatting varies. In particular, control characters may be shown as readable escapes or caret notation.

4. Understand the legacy file boundary

The Linux manual documents /etc/termcap as the ASCII database master, with one logical entry per terminal and continued capability lines indented by a tab. On this machine that path is absent, which is normal for a system using terminfo. An application may instead use its own compatibility library or a separately configured database.

Do not create /etc/termcap merely because a tutorial mentions it. Creating a system-wide database can change the behaviour of old applications and normally requires root. Before any edit, identify the program that reads the file, check its documentation, and make a backup. A malformed entry can affect every user of that database.

If you have been given a termcap file to inspect, read it without executing anything:

$ sed -n '1,80p' /path/to/termcap
$ grep -n '^xterm' /path/to/termcap

Replace the path with a real file. Never use an untrusted termcap file as a shell script. It contains escape sequences and terminal control data, which may have visible or disruptive effects if sent to a terminal, but it is not a program.

5. Treat conversion as a compatibility check

The ncurses manual warns that termcap strings are less expressive than terminfo strings. infocmp -C converts most parameterised capabilities, but it may comment out information that cannot be represented. The output is therefore a useful starting point, not proof that two databases are equivalent.

Save generated output only when you have a clear reason, and write to a new file so an existing compatibility file cannot be truncated by shell redirection:

$ umask 077
$ infocmp -C -r -1 "$TERM" > /tmp/termcap-entry.$$
$ test -s /tmp/termcap-entry.$$ && sed -n '1,12p' /tmp/termcap-entry.$$
$ rm -- /tmp/termcap-entry.$$

This temporary file contains terminal capability data and is removed after inspection. If you adapt the command for a persistent file, use a controlled destination and keep the original until an old application has been tested. Do not use sudo infocmp ... > /etc/termcap as a shortcut: the shell performs the redirection before privilege escalation, and overwriting a shared file is difficult to undo.

6. Diagnose the common failures

If infocmp reports that a terminal type is unknown, check the spelling and the database search configuration:

$ printf 'TERM=%s\n' "$TERM"
$ infocmp -D
$ infocmp "$TERM"
infocmp: couldn't open terminfo file

The final message is an example of a failure, not expected success. It means the selected name was not found in the databases that ncurses searched. Do not solve it by inventing a termcap entry. First check whether TERMINFO or TERMINFO_DIRS points to an incomplete directory, and confirm that the ncurses data package is installed through your normal package manager.

If a program behaves incorrectly after a terminal change, restore the previous TERM value in the shell or reconnect with the terminal's normal configuration. If you changed a shared termcap file, restore the backup, then restart the affected program. A running process may have already cached its terminal description.