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