Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

some docs for the terminfo file format (including extended capabilities)

  • Loading branch information...
commit 33831e59ef9be8baa129eabcb5988dd82be04715 1 parent 4bd70cf
@mauke authored
Showing with 206 additions and 0 deletions.
  1. +206 −0 secret/terminfo.pod
View
206 secret/terminfo.pod
@@ -0,0 +1,206 @@
+=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
Please sign in to comment.
Something went wrong with that request. Please try again.