Convert a Termcap File to Terminfo Safely with captoinfo

You will finish with readable terminfo source converted from a legacy termcap file, while keeping the original file intact and checking for unresolved inheritance. The examples use the captoinfo command found on this machine, which reports ncurses 6.6.20251230. The Debian package record for ncurses-bin is 6.4+20240113-1ubuntu2.2, but this shell resolves captoinfo to the Homebrew ncurses binary, so check your own path before relying on version-specific output.

Allow about ten minutes. You need a readable termcap text file and a shell. The conversion writes terminfo source to standard output; it does not install a compiled database unless you separately run tic. Ordinary conversion and checking do not need sudo.

1. Check the binary and its version

Start with two read-only checks. They confirm which implementation will process the file and make later troubleshooting less ambiguous:

$ command -v captoinfo
/home/linuxbrew/.linuxbrew/bin/captoinfo
$ captoinfo -V
ncurses 6.6.20251230

Your path and version may differ. captoinfo is implemented as a link to tic, with the input translated to terminfo format. The exact diagnostics and defaults therefore belong to the ncurses build you are actually running, not necessarily to the distribution package name you expected.

Checkpoint: if command -v prints an unexpected location, stop and decide whether to adjust PATH or use an absolute path. Do not mix output from two ncurses installations while investigating a conversion.

2. Inspect the input without changing it

A termcap file normally contains one terminal entry per line. An entry starts with one or more names, followed by colon-separated capabilities. Numeric values use #, strings use =, and a tc capability inherits from another entry. The following commands only read the file:

$ test -r /path/to/legacy.termcap && echo readable
readable
$ sed -n '1,12p' /path/to/legacy.termcap

Replace the path with your real file. Do not treat a file copied from an untrusted source as harmless merely because it is text: review the terminal names and capabilities before feeding it into another tool. Keep the original available until the converted output has passed your checks.

3. Convert to a reviewable output file

Write to a new name so a failed conversion cannot truncate a useful result. This command translates every entry in the input file and sends terminfo source to the new file:

$ captoinfo /path/to/legacy.termcap > converted.terminfo.new
$ test -s converted.terminfo.new && echo conversion-produced-output
conversion-produced-output

Shell redirection creates or truncates its destination before captoinfo runs. That is why the example uses .new rather than the final name. If the command reports an error, retain the original and inspect the diagnostic. Remove the incomplete converted.terminfo.new only after checking that you do not need it for diagnosis, then rerun with a new output name. No elevated privilege is needed when reading and writing in your working directory.

Open the new file as text. A small entry should now look like this, although the names and escape sequences depend on the input:

demo|demo terminal,
	cols#80, lines#24,
	clear=\\E[H\\E[2J, cup=\\E[%%i%%d;%%dH,

Termcap tc=base becomes terminfo use=base. That is an inheritance reference, not a copied expansion. The base entry must be available when the converted source is later validated or compiled.

4. Make long entries easier to review

Use -1 when the default comma-separated layout is hard to scan. It asks the underlying tic translator to put one capability on each line:

$ captoinfo -1 /path/to/legacy.termcap > converted.terminfo.new
$ sed -n '1,20p' converted.terminfo.new
demo|demo terminal,
	cols#80,
	lines#24,
	clear=\\E[H\\E[2J,
	cup=\\E[%%i%%d;%%dH,

This changes presentation, not the terminal definition. Keep the one-per-line form when reviewing a large migration or comparing changes in version control. If parameterised strings are difficult to understand, -f formats complex terminfo expressions for readability. It does not repair an invalid expression.

5. Validate inheritance and syntax

Use tic -c against the converted source when you want validation without producing compiled output. This is a read-only check of the input file:

$ tic -c converted.terminfo.new
$ printf 'validation exit: %s\n' "$?"
validation exit: 0

A non-zero status means you should read the diagnostic before proceeding. Common causes include malformed capability syntax and a use reference whose target entry is absent. A warning about a legacy or non-standard capability deserves review even when the process exits successfully, because ncurses may translate, discard or reinterpret compatibility extensions.

If your source deliberately uses inheritance, include the file containing the base entries in the same validation input or combine the entries into one reviewed source file. Do not assume that a successful text conversion proves a complete terminal definition: captoinfo translates references but does not silently invent missing parents.

6. Review compatibility warnings before installing anything

The converter recognises several obsolete capability names and translates them to standard terminfo names. It can also compose certain XENIX box-drawing capabilities into acsc. Some double-line capabilities and the old GG field are discarded with a warning. AIX extensions are mapped where ncurses has a corresponding standard capability, while HP-UX meml and memu are discarded with a warning.

Do not redirect standard error away while doing the first conversion. A warning is a prompt to compare the old terminal behaviour with the generated entry, not proof that the result is safe to deploy. Save the diagnostic alongside your review notes if this is a migration. Only after the output and warnings are understood should you replace .new with the intended filename:

$ mv converted.terminfo.new converted.terminfo

The mv changes the filename in your working directory and is reversible while the old file remains available. Do not overwrite a system terminfo database as part of this guide. Compiling or installing an entry is a separate operational change and may affect applications that use that terminal name.

7. Understand the no-file default

Running captoinfo without a file does not mean "read standard input". According to the installed manual, it treats TERMCAP as a file name and extracts only the entry named by TERM. If TERMCAP is unset, it reads /etc/termcap. Check those variables explicitly before using the shorthand:

$ printf 'TERM=%s\nTERMCAP=%s\n' "$TERM" "${TERMCAP-}"
TERM=xterm-256color
TERMCAP=/path/to/legacy.termcap
$ captoinfo > selected.terminfo.new

For repeatable scripts, pass the input file explicitly. The environment-based form depends on the current terminal and can select a different entry from the one you intended. If you need one terminal from a multi-entry file, filter or prepare a reviewed input file first, then convert that file deliberately.