1=pod 2 3=head1 The I<terminfo> file format (as used by ncurses) 4 5In the following description, these data type representations are assumed: 6 7=over 8 9=item byte 10 11An 8-bit quantity. Synonymous with "octet". 12 13=item bool 14 15A single byte that's either 0 (I<false>) or 1 (I<true>). 16 17=item int 18 19Two bytes representing a 16-bit integer in little endian format. The value 20must be either a non-negative 15-bit value or the special value -1 (stored as 21C<FF FF>). 22 23=item string data 24 25Character data is stored as NUL-terminated ASCII strings. 26 27=back 28 29=head2 Standard capabilities 30 31=head3 Header 32 33A terminfo file starts with a 12 byte header, consisting of 6 ints: 34 35=over 36 37=item MAGIC 38 39The number 282 (stored in the file as C<1A 01>). 40 41=item NAME_SIZE 42 43The size (in bytes) of the name section. 44 45=item BOOL_COUNT 46 47The number of entries in the bool section. 48 49=item NUM_COUNT 50 51The number of entries in the num section. 52 53=item STRING_COUNT 54 55The number of entries in the string section. 56 57=item TABLE_SIZE 58 59The size (in bytes) of the string table. 60 61=back 62 63=head3 Data 64 65To make sense of the stored data, you need to know that there is a 66fixed number of bool/num/string capabilities each, and that they have a fixed 67order. So if a terminfo file wanted to set the third num capability to 4 and 68leave the first/second num capabilities unspecified, it would fill its num 69section with C<{ -1, -1, 4 }>. 70 71B<TODO>: Document the names/order of all capabilities. 72 73=over 74 75=item The name section 76 77The name section contains a (NUL-terminated) string with one or more parts 78separated by C<|> (pipe). The first part is the primary name of the terminal; 79the last part is a human-readable description. The middle parts should be 80other names for the terminal. All parts except for the last should contain 81lowercase letters only. 82 83=item The bool section 84 85The bool section consists of I<BOOL_COUNT> bytes, each representing a boolean 86value. 87 88=item Interlude: padding 89 90If I<NAME_SIZE> + I<BOOL_COUNT> is not an even number, a padding byte is 91inserted here. 92 93=item The num section 94 95The num section consists of I<NUM_COUNT> ints. A value of -1 indicates that 96the corresponding numeric capability is missing. 97 98=item The string section 99 100The string section consists of I<STRING_COUNT> ints. A value of -1 indicates 101that the corresponding string capability is missing. Any other value is an 102offset from the beginning of the string table. 103 104=item The string table 105 106The string table consists of I<TABLE_SIZE> bytes. It stores the data for 107string capabilities. Each entry in the string section specifies the byte at 108which the corresponding string starts; the end of a string is marked by a NUL 109byte. 110 111=back 112 113=head2 Extended capabilities 114 115In addition to the standard capabilities described above, ncurses supports 116user-defined capabilities with arbitrary names. If any of these are present, 117instead of the end of the file an extended header follows after the main 118data. 119 120=head3 Header 121 122The extended header consists of possibly a padding byte and 5 ints. 123 124=over 125 126=item Interlude: padding 127 128If the standard part of the file contains an odd number of bytes, a padding 129byte is inserted here. 130 131=item EXT_BOOL_COUNT 132 133The number of entries in the extended bool section. 134 135=item EXT_NUM_COUNT 136 137The number of entries in the extended num section. 138 139=item EXT_STRING_COUNT 140 141The number of entries in the extended string section. 142 143=item EXT_OFFSET_COUNT 144 145The number of entries in the string table. 146 147NB: The ncurses code for writing terminfo files calculates this as 148I<EXT_BOOL_COUNT> + I<EXT_NUM_COUNT> + I<EXT_STRING_COUNT> + 149I<EXT_STRING_COUNT> (one entry for each capability name plus one entry for 150each string value). The ncurses code for reading terminfo files ignores this 151field. 152 153NB: L<term(5)> (part of ncurses) misdocuments this field as "size of the 154extended string table in bytes". This is wrong. 155 156=item EXT_TABLE_SIZE 157 158The size (in bytes) of the extended string table. 159 160NB: L<term(5)> (part of ncurses) misdocuments this field as "last offset of 161the extended string table". This is wrong. 162 163=back 164 165=head3 Data 166 167=over 168 169=item The extended bool section 170 171The extended bool section consists of I<EXT_BOOL_COUNT> bytes, each 172representing a boolean value. 173 174=item Interlude: padding 175 176If I<EXT_BOOL_COUNT> is not an even number, a padding byte is inserted here. 177 178=item The extended num section 179 180The extended num section consists of I<EXT_NUM_COUNT> ints. 181 182=item The extended string section 183 184The extended string section consists of I<EXT_STRING_COUNT> ints that are 185offsets from the beginning of the extended string table. 186 187=item The extended string section 2: Electric boogaloo 188 189The extended string section 2 consists of I<EXT_BOOL_COUNT> + 190I<EXT_NUM_COUNT> + I<EXT_STRING_COUNT> ints that are offsets from the middle 191(see below) of the extended string table. 192 193=item The extended string table 194 195The extended string table consists of I<EXT_TABLE_SIZE> bytes. The first half 196of the extended string table stores the data for extended string 197capabilities. The second half of the string table stores the names of all 198extended capabilities. 199 200The start of the second half (what I call the "middle") must be computed 201dynamically from the number (I<EXT_STRING_COUNT>) and size of the strings in 202the first half. 203 204=back 205 206=cut 207