=pod

=head1 The I<terminfo> file format (as used by ncurses)

In the following description, these data type representations are assumed:

=over

=item byte

An 8-bit quantity. Synonymous with "octet".

=item bool

A single byte that's either 0 (I<false>) or 1 (I<true>).

=item int

Two bytes representing a 16-bit integer in little endian format. The value
must be either a non-negative 15-bit value or the special value -1 (stored as
C<FF FF>).

=item string data

Character data is stored as NUL-terminated ASCII strings.

=back

=head2 Standard capabilities

=head3 Header

A terminfo file starts with a 12 byte header, consisting of 6 ints:

=over

=item MAGIC

The number 282 (stored in the file as C<1A 01>).

=item NAME_SIZE

The size (in bytes) of the name section.

=item BOOL_COUNT

The number of entries in the bool section.

=item NUM_COUNT

The number of entries in the num section.

=item STRING_COUNT

The number of entries in the string section.

=item TABLE_SIZE

The size (in bytes) of the string table.

=back

=head3 Data

To make sense of the stored data, you need to know that there is a
fixed number of bool/num/string capabilities each, and that they have a fixed
order. So if a terminfo file wanted to set the third num capability to 4 and
leave the first/second num capabilities unspecified, it would fill its num
section with C<{ -1, -1, 4 }>.

B<TODO>: Document the names/order of all capabilities.

=over

=item The name section

The name section contains a (NUL-terminated) string with one or more parts
separated by C<|> (pipe). The first part is the primary name of the terminal;
the last part is a human-readable description. The middle parts should be
other names for the terminal. All parts except for the last should contain
lowercase letters only.

=item The bool section

The bool section consists of I<BOOL_COUNT> bytes, each representing a boolean
value.

=item Interlude: padding

If I<NAME_SIZE> + I<BOOL_COUNT> is not an even number, a padding byte is
inserted here.

=item The num section

The num section consists of I<NUM_COUNT> ints. A value of -1 indicates that
the corresponding numeric capability is missing.

=item The string section

The string section consists of I<STRING_COUNT> ints. A value of -1 indicates
that the corresponding string capability is missing. Any other value is an
offset from the beginning of the string table.

=item The string table

The string table consists of I<TABLE_SIZE> bytes. It stores the data for
string capabilities. Each entry in the string section specifies the byte at
which the corresponding string starts; the end of a string is marked by a NUL
byte.

=back

=head2 Extended capabilities

In addition to the standard capabilities described above, ncurses supports
user-defined capabilities with arbitrary names. If any of these are present,
instead of the end of the file an extended header follows after the main
data.

=head3 Header

The extended header consists of possibly a padding byte and 5 ints.

=over

=item Interlude: padding

If the standard part of the file contains an odd number of bytes, a padding
byte is inserted here.

=item EXT_BOOL_COUNT

The number of entries in the extended bool section.

=item EXT_NUM_COUNT

The number of entries in the extended num section.

=item EXT_STRING_COUNT

The number of entries in the extended string section.

=item EXT_OFFSET_COUNT

The number of entries in the string table.

NB: The ncurses code for writing terminfo files calculates this as
I<EXT_BOOL_COUNT> + I<EXT_NUM_COUNT> + I<EXT_STRING_COUNT> +
I<EXT_STRING_COUNT> (one entry for each capability name plus one entry for
each string value). The ncurses code for reading terminfo files ignores this
field.

NB: L<term(5)> (part of ncurses) misdocuments this field as "size of the
extended string table in bytes". This is wrong.

=item EXT_TABLE_SIZE

The size (in bytes) of the extended string table.

NB: L<term(5)> (part of ncurses) misdocuments this field as "last offset of
the extended string table". This is wrong.

=back

=head3 Data

=over

=item The extended bool section

The extended bool section consists of I<EXT_BOOL_COUNT> bytes, each
representing a boolean value.

=item Interlude: padding

If I<EXT_BOOL_COUNT> is not an even number, a padding byte is inserted here.

=item The extended num section

The extended num section consists of I<EXT_NUM_COUNT> ints.

=item The extended string section

The extended string section consists of I<EXT_STRING_COUNT> ints that are
offsets from the beginning of the extended string table.

=item The extended string section 2: Electric boogaloo

The extended string section 2 consists of I<EXT_BOOL_COUNT> +
I<EXT_NUM_COUNT> + I<EXT_STRING_COUNT> ints that are offsets from the middle
(see below) of the extended string table.

=item The extended string table

The extended string table consists of I<EXT_TABLE_SIZE> bytes. The first half
of the extended string table stores the data for extended string
capabilities. The second half of the string table stores the names of all
extended capabilities.

The start of the second half (what I call the "middle") must be computed
dynamically from the number (I<EXT_STRING_COUNT>) and size of the strings in
the first half.

=back

=cut
