Skip to content

A tour of the terminfo compiler

Adapted from A Hacker’s Guide to NCURSES, by Eric S. Raymond.

The ncurses implementation of tic is rather complex internally; it has to do a trying combination of missions. This starts with the fact that, in addition to its normal duty of compiling terminfo sources into loadable terminfo binaries, it has to be able to handle termcap syntax and compile that too into terminfo entries.

The implementation therefore starts with a table-driven, dual-mode lexical analyzer (in comp_scan.c). The lexer chooses its mode (termcap or terminfo) based on the first , or : it finds in each entry. The lexer does all the work of recognizing capability names and values; the grammar above it is trivial, just “parse entries till you run out of file”.

Translation of most things besides use capabilities is pretty straightforward. The lexical analyzer’s tokenizer hands each capability name to a hash function, which drives a table lookup. The table entry yields an index which is used to look up the token type in another table, and controls interpretation of the value.

One possibly interesting aspect of the implementation is the way the compiler tables are initialized. All the tables are generated by various awk/sed/sh scripts from a master table include/Caps; these scripts actually write C initializers which are linked to the compiler. Furthermore, the hash table is generated in the same way, so it doesn’t have to be generated at compiler startup time (another benefit of this organization is that the hash table can be in shareable text space).

Thus, adding a new capability is usually pretty trivial, just a matter of adding one line to the include/Caps file. We will have more to say about this in source-form translation.

The background problem that makes tic tricky isn’t the capability translation itself, it’s the resolution of use capabilities. Older versions would not handle forward use references for this reason (that is, a using terminal always had to follow its use target in the source file). By doing this, they got away with a simple implementation tactic: compile everything as it blows by, then resolve uses from compiled entries.

This won’t do for ncurses. The problem is that the whole compilation process has to be embeddable in the ncurses library so that it can be called by the startup code to translate termcap entries on the fly. The embedded version can’t go promiscuously writing everything it translates out to disk; for one thing, it will typically be running with non-root permissions.

So our tic is designed to parse an entire terminfo file into a doubly-linked list of entry structures in-core, and then do use resolution in-memory before writing everything out. This design has other advantages: it makes forward and back use-references equally easy (so we get the latter for free), and it makes checking for name collisions before they are written out easy to do.

And this is exactly how the embedded version works. But the stand-alone user-accessible version of tic partly reverts to the historical strategy; it writes to disk (not keeping in core) any entry with no use references.

This is strictly a core-economy kluge, implemented because the terminfo master file is large enough that some core-poor systems swap like crazy when you compile it all in memory. There have been reports of this process taking three hours, rather than the twenty seconds or less typical on the author’s development box.

So the executable tic passes the entry-parser a hook that immediately writes out the referenced entry if it has no use capabilities. The compiler main loop refrains from adding the entry to the in-core list when this hook fires. If some other entry later needs to reference an entry that got written immediately, that’s OK; the resolution code will fetch it off disk when it can’t find it in core.

Name collisions will still be detected, just not as cleanly. The write_entry() code complains before overwriting an entry that postdates the time of tic’s first call to write_entry(). Thus it will complain about overwriting entries newly made during the tic run, but not about overwriting ones that predate it.

Another use of tic is to do source translation between various termcap and terminfo formats. There are more variants out there than you might think; the ones we know about are described in the captoinfo(1M) manual page.

The translation output code (dump_entry() in progs/dump_entry.c) is shared with the infocmp(1M) utility. It takes the same internal representation used to generate the binary form and dumps it to standard output in a specified format.

The include/Caps file has a header comment describing ways you can specify source translations for nonstandard capabilities just by altering the master table. It’s possible to set up capability aliasing or tell the compiler to plain ignore a given capability without writing any C code at all.

For circumstances where you need to do algorithmic translation, there are functions in parse_entry.c called after the parse of each entry that are specifically intended to encapsulate such translations. This, for example, is where the AIX box1 capability gets translated to an acsc string.