2 .\"***************************************************************************
3 .\" Copyright 2018-2022,2023 Thomas E. Dickey *
4 .\" Copyright 1998-2017,2018 Free Software Foundation, Inc. *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a *
7 .\" copy of this software and associated documentation files (the *
8 .\" "Software"), to deal in the Software without restriction, including *
9 .\" without limitation the rights to use, copy, modify, merge, publish, *
10 .\" distribute, distribute with modifications, sublicense, and/or sell *
11 .\" copies of the Software, and to permit persons to whom the Software is *
12 .\" furnished to do so, subject to the following conditions: *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 .\" Except as contained in this notice, the name(s) of the above copyright *
26 .\" holders shall not be used in advertising or otherwise to promote the *
27 .\" sale, use or other dealings in this Software without prior written *
29 .\"***************************************************************************
31 .\" $Id: infocmp.1m,v 1.90 2023/09/09 21:14:05 tom Exp $
32 .TH @INFOCMP@ 1M 2023-09-09 "ncurses 6.4" "User commands"
63 \fB@INFOCMP@\fP \- compare or print out \fIterminfo\fP descriptions
65 \fB@INFOCMP@\fP [\fB\-\
93 [\fB\-v\fR \fIn\fR] [\fB\-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR] [\fB\-Q\fR \fIn\fR] [\fB\-R \fBsubset\fR]
94 [\fB\-w\fP\ \fIwidth\fP] [\fB\-A\fP\ \fIdirectory\fP] [\fB\-B\fP\ \fIdirectory\fP]
97 \fB@INFOCMP@\fP can be used to compare a binary \fBterminfo\fP entry with other
98 terminfo entries, rewrite a \fBterminfo\fP description to take advantage of the
99 \fBuse=\fP terminfo field, or print out a \fBterminfo\fP description from the
100 binary file (\fBterm\fP) in a variety of formats.
101 In all cases, the boolean
102 fields will be printed first, followed by the numeric fields, followed by the
105 If no options are specified and zero or one \fItermnames\fP are specified, the
106 \fB\-I\fP option will be assumed.
107 If more than one \fItermname\fP is specified,
108 the \fB\-d\fP option will be assumed.
109 .SS Comparison Options [\-d] [\-c] [\-n]
110 \fB@INFOCMP@\fP compares the \fBterminfo\fP description of the first terminal
111 \fItermname\fP with each of the descriptions given by the entries for the other
112 terminal's \fItermnames\fP.
113 If a capability is defined for only one of the
114 terminals, the value returned depends on the type of the capability:
116 \fBF\fP for missing boolean variables
118 \fBNULL\fP for missing integer or string variables
120 Use the \fB\-q\fP option to show the distinction between
121 \fIabsent\fP and \fIcancelled\fP capabilities.
123 These options produce a list which you can use to compare two
124 or more terminal descriptions:
127 produces a list of each capability that is \fIdifferent\fP
129 Each item in the list shows \*(``:\*('' after the capability name,
130 followed by the capability values, separated by a comma.
133 produces a list of each capability that is \fIcommon\fP between
135 Missing capabilities are ignored.
136 Each item in the list shows \*(``=\*('' after the capability name,
137 followed by the capability value.
139 The \fB\-u\fP option provides a related output,
140 showing the first terminal description rewritten to use the second
141 as a building block via the \*(``use=\*('' clause.
144 produces a list of each capability that is in \fInone\fP of the given entries.
145 Each item in the list shows \*(``!\*('' before the capability name.
147 Normally only the conventional capabilities are shown.
148 Use the \fB\-x\fP option to add the BSD-compatibility
149 capabilities (names prefixed with \*(``OT\*('').
151 If no \fItermnames\fP are given,
152 \fB@INFOCMP@\fP uses the environment variable \fBTERM\fP
153 for each of the \fItermnames\fP.
154 .SS Source Listing Options [\-I] [\-L] [\-C] [\-r]
155 The \fB\-I\fP, \fB\-L\fP, and \fB\-C\fP options will produce
156 a source listing for each terminal named.
161 \fB\-I\fP/use the \fBterminfo\fP names
162 \fB\-L\fP/use the long C variable name listed in <\fBterm.h\fP>
163 \fB\-C\fP/use the \fBtermcap\fP names
164 \fB\-r\fP/when using \fB\-C\fP, put out all capabilities in \fBtermcap\fP form
165 \fB\-K\fP/modifies the \fB\-C\fP option, improving BSD-compatibility.
168 If no \fItermnames\fP are given, the environment variable \fBTERM\fP will be
169 used for the terminal name.
171 The source produced by the \fB\-C\fP option may be used directly as a
172 \fBtermcap\fP entry, but not all parameterized strings can be changed to
173 the \fBtermcap\fP format.
174 \fB@INFOCMP@\fP will attempt to convert most of the
175 parameterized information, and anything not converted will be plainly marked in
176 the output and commented out.
177 These should be edited by hand.
179 For best results when converting to \fBtermcap\fP format,
180 you should use both \fB\-C\fP and \fB\-r\fP.
181 Normally a termcap description is limited to 1023 bytes.
182 \fB@INFOCMP@\fP trims away less essential parts to make it fit.
183 If you are converting to one of the (rare) termcap implementations
184 which accept an unlimited size of termcap,
185 you may want to add the \fB\-T\fP option.
186 More often however, you must help the termcap implementation,
187 and trim excess whitespace (use the \fB\-0\fP option for that).
189 All padding information for strings will be collected together and placed
190 at the beginning of the string where \fBtermcap\fP expects it.
192 padding (padding information with a trailing \*(``/\*('') will become optional.
194 All \fBtermcap\fP variables no longer supported by \fBterminfo\fP, but which
195 are derivable from other \fBterminfo\fP variables, will be output.
197 \fBterminfo\fP capabilities will be translated; only those variables which were
198 part of \fBtermcap\fP will normally be output.
199 Specifying the \fB\-r\fP option
200 will take off this restriction, allowing all capabilities to be output in
202 Normally you would use both the \fB\-C\fP and \fB\-r\fP options.
203 The actual format used incorporates some improvements for escaped characters
204 from terminfo format.
205 For a stricter BSD-compatible translation, use the \fB\-K\fP option
206 rather than \fB\-C\fP.
208 Note that because padding is collected to the beginning of the capability, not
209 all capabilities are output.
210 Mandatory padding is not supported.
212 \fBtermcap\fP strings are not as flexible, it is not always possible to convert
213 a \fBterminfo\fP string capability into an equivalent \fBtermcap\fP format.
214 A subsequent conversion of the \fBtermcap\fP file
215 back into \fBterminfo\fP format
216 will not necessarily reproduce the original \fBterminfo\fP source.
218 Some common \fBterminfo\fP parameter sequences, their \fBtermcap\fP
219 equivalents, and some terminal types which commonly have such sequences, are:
225 \fBterminfo/termcap\fP/Representative Terminals
228 \fB%p1%d/%d\fP/hp, ANSI standard, vt100
229 \fB%p1%'x'%+%c/%+x\fP/concept
230 \fB%i/%i\fPq/ANSI standard, vt100
231 \fB%p1%?%'x'%>%t%p1%'y'%+%;/%>xy\fP/concept
232 \fB%p2\fP is printed before \fB%p1/%r\fP/hp
234 .SS Use= Option [\-u]
235 The \fB\-u\fP option produces a \fBterminfo\fP source description of the first
236 terminal \fItermname\fP which is relative to the sum of the descriptions given
237 by the entries for the other terminals \fItermnames\fP.
239 analyzing the differences between the first \fItermname\fP and the other
240 \fItermnames\fP and producing a description with \fBuse=\fP fields for the
242 In this manner, it is possible to retrofit generic terminfo
243 entries into a terminal's description.
244 Or, if two similar terminals exist, but
245 were coded at different times or by different people so that each description
246 is a full description, using \fB@INFOCMP@\fP
247 will show what can be done to change
248 one description to be relative to the other.
250 A capability will be printed with an at-sign (@) if it no longer exists in the
251 first \fItermname\fP, but one of the other \fItermname\fP entries contains a
253 A capability's value will be printed if the value in the first
254 \fItermname\fP is not found in any of the other \fItermname\fP entries, or if
255 the first of the other \fItermname\fP entries that has this capability gives a
256 different value for the capability than that in the first \fItermname\fP.
258 The order of the other \fItermname\fP entries is significant.
260 terminfo compiler \fB@TIC@\fP does a left-to-right scan of the capabilities,
261 specifying two \fBuse=\fP entries that contain differing entries for the same
262 capabilities will produce different results depending on the order that the
263 entries are given in.
264 \fB@INFOCMP@\fP will flag any such inconsistencies between
265 the other \fItermname\fP entries as they are found.
267 Alternatively, specifying a capability \fIafter\fP a \fBuse=\fP entry that
268 contains that capability will cause the second specification to be ignored.
269 Using \fB@INFOCMP@\fP to recreate a description can be a useful check to make
270 sure that everything was specified correctly in the original source
273 Another error that does not cause incorrect compiled files, but will slow down
274 the compilation time, is specifying extra \fBuse=\fP fields that are
276 \fB@INFOCMP@\fP will flag any other \fItermname use=\fP fields that
278 .SS Changing Databases [\-A \fIdirectory\fR] [\-B \fIdirectory\fR]
279 Like other \fBncurses\fP utilities,
280 \fB@INFOCMP@\fP looks for the terminal descriptions in several places.
281 You can use the \fBTERMINFO\fP and \fBTERMINFO_DIRS\fP environment variables
282 to override the compiled-in default list of places to search.
283 See \fBcurses\fP(3X), as well as
284 the \fIFetching Compiled Descriptions\fP section in \fBterminfo\fR(\*n).
286 You can also use the options \fB\-A\fP
287 and \fB\-B\fP to override the list of places to search
288 when comparing terminal descriptions:
290 The \fB\-A\fP option sets the location for the first \fItermname\fP
292 The \fB\-B\fP option sets the location for the other \fItermnames\fP.
294 Using these options, it is possible to
295 compare descriptions for a terminal with the same name located in two different
298 you can use this feature for comparing descriptions for the same terminal
299 created by different people.
303 causes the fields to be printed on one line, without wrapping.
306 causes the fields to be printed out one to a line.
308 the fields will be printed several to a line to a maximum width
312 tells \fB@INFOCMP@\fP to retain commented-out capabilities
313 rather than discarding them.
314 Capabilities are commented by prefixing them with a period.
317 tells \fB@INFOCMP@\fP to print the database locations that it knows about,
321 Dump the capabilities of the given terminal as tables, needed in
322 the C initializer for a
323 TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fP).
324 This option is useful for preparing versions of the curses library hardwired
325 for a given terminal type.
326 The tables are all declared static, and are named according to the type
327 and the name of the corresponding terminal entry.
329 Before ncurses 5.0, the split between the \fB\-e\fP and \fB\-E\fP
330 options was not needed; but support for extended names required making
331 the arrays of terminal capabilities separate from the TERMTYPE structure.
334 Dump the capabilities of the given terminal as a C initializer for a
335 TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fP).
336 This option is useful for preparing versions of the curses library hardwired
337 for a given terminal type.
340 compare terminfo files.
341 This assumes that two following arguments are filenames.
342 The files are searched for pairwise matches between
343 entries, with two entries considered to match if any of their names do.
344 The report printed to standard output lists entries with no matches in
345 the other file, and entries with more than one match.
347 with exactly one match it includes a difference report.
349 to reduce the volume of the report, use references are
350 not resolved before looking for differences, but resolution can be forced
351 by also specifying \fB\-r\fP.
354 Display complex terminfo strings which contain if/then/else/endif expressions
355 indented for readability.
358 Display constant literals in decimal form
359 rather than their character equivalents.
362 Display constant character literals in quoted form
363 rather than their decimal equivalents.
366 Analyze the initialization (\fBis1\fP, \fBis2\fP, \fBis3\fP), and reset
367 (\fBrs1\fP, \fBrs2\fP, \fBrs3\fP), strings in the entry,
368 as well as those used for starting/stopping cursor-positioning mode
369 (\fBsmcup\fP, \fBrmcup\fP) as well as starting/stopping keymap mode
370 (\fBsmkx\fP, \fBrmkx\fP).
373 code tries to analyze it into actions in terms of the other capabilities in the
374 entry, certain X3.64/ISO 6429/ECMA\-48 capabilities, and certain DEC VT-series
375 private modes (the set of recognized special sequences has been selected for
376 completeness over the existing terminfo database).
377 Each report line consists
378 of the capability name, followed by a colon and space, followed by a printable
379 expansion of the capability string with sections matching recognized actions
380 translated into {}-bracketed descriptions.
382 Here is a list of the DEC/ANSI
383 special sequences recognized:
395 RSR/reset scroll region
397 DECSTR/soft reset (VT320)
398 S7C1T/7-bit controls (VT220)
400 ISO DEC G0/enable DEC graphics for G0
401 ISO UK G0/enable UK chars for G0
402 ISO US G0/enable US chars for G0
403 ISO DEC G1/enable DEC graphics for G1
404 ISO UK G1/enable UK chars for G1
405 ISO US G1/enable US chars for G1
407 DECPAM/application keypad mode
408 DECPNM/normal keypad mode
409 DECANSI/enter ANSI mode
411 ECMA[+\-]AM/keyboard action mode
412 ECMA[+\-]IRM/insert replace mode
413 ECMA[+\-]SRM/send receive mode
414 ECMA[+\-]LNM/linefeed mode
416 DEC[+\-]CKM/application cursor keys
417 DEC[+\-]ANM/set VT52 mode
418 DEC[+\-]COLM/132-column mode
419 DEC[+\-]SCLM/smooth scroll
420 DEC[+\-]SCNM/reverse video mode
421 DEC[+\-]OM/origin mode
422 DEC[+\-]AWM/wraparound mode
423 DEC[+\-]ARM/auto-repeat mode
426 It also recognizes a SGR action corresponding to ANSI/ISO 6429/ECMA Set
427 Graphics Rendition, with the values NORMAL, BOLD, UNDERLINE, BLINK, and
429 All but NORMAL may be prefixed with
432 \*(``+\*('' (turn on) or
434 \*(``\-\*('' (turn off).
437 An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}).
440 Set output format to terminfo.
443 Ignore padding specifications when comparing strings.
446 Rather than show source in terminfo (text) format,
447 print the compiled (binary) format in hexadecimal or base64 form,
448 depending on the option's value:
458 hexadecimal and base64
461 For example, this prints the compiled terminfo value as a string
462 which could be assigned to the \fBTERMINFO\fP environment variable:
468 This makes the output a little shorter:
471 Make the comparison listing shorter by omitting subheadings, and using
472 \*(``\-\*('' for absent capabilities, \*(``@\*(''
473 for canceled rather than \*(``NULL\*(''.
475 However, show differences between absent and cancelled capabilities.
477 Omit the \*(``Reconstructed from\*('' comment for source listings.
481 Restrict output to a given subset.
482 This option is for use with archaic
483 versions of terminfo like those on SVr1, Ultrix, or HP-UX that do not support
484 the full set of SVR4/XSI Curses terminfo; and variants such as AIX
485 that have their own extensions incompatible with SVr4/XSI.
489 subsets are \*(``SVr1\*('', \*(``Ultrix\*('', \*(``HP\*('', and \*(``AIX\*('';
490 see \fBterminfo\fP(\*n) for details.
492 You can also choose the subset \*(``BSD\*('' which selects only capabilities
493 with termcap equivalents recognized by 4.4BSD.
495 If you select any other value for \fB\-R\fP,
496 it is the same as no subset, i.e., all capabilities are used.
499 A few options override the subset selected with \fB\-R\fP,
500 if they are processed later in the command parameters:
504 sets the \*(``BSD\*('' subset as a side-effect.
507 sets the subset to all capabilities.
510 sets the subset to all capabilities.
513 \fB\-s \fI[d|i|l|c]\fR
514 The \fB\-s\fP option sorts the fields within each type according to the argument
520 leave fields in the order that they are stored in the \fIterminfo\fP database.
523 sort by \fIterminfo\fP name.
526 sort by the long C variable name.
529 sort by the \fItermcap\fP name.
532 If the \fB\-s\fP option is not given, the fields printed out will be
533 sorted alphabetically by the \fBterminfo\fP name within each type,
534 except in the case of the \fB\-C\fP or the \fB\-L\fP options, which cause the
535 sorting to be done by the \fBtermcap\fP name or the long C variable
539 eliminates size-restrictions on the generated text.
540 This is mainly useful for testing and analysis, since the compiled
541 descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
544 tells \fB@TIC@\fP to discard commented-out capabilities.
545 Normally when translating from terminfo to termcap,
546 untranslatable capabilities are commented-out.
549 tells \fB@INFOCMP@\fP to not post-process the data
550 after parsing the source file.
551 This feature helps when comparing the actual contents of two source files,
552 since it excludes the inferences that \fB@INFOCMP@\fP makes to fill in missing
556 reports the version of ncurses which was used in this program, and exits.
559 prints out tracing information on standard error as the program runs.
561 The optional parameter \fIn\fP is a number from 1 to 10, inclusive,
562 indicating the desired level of detail of information.
563 If ncurses is built without tracing support, the optional parameter is ignored.
566 By itself, the \fB\-w\fP option will not force long strings to be wrapped.
567 Use the \fB\-W\fP option to do this.
569 \fB\-w\fP \fIwidth\fP
570 changes the output to \fIwidth\fP characters.
573 print information for user-defined capabilities (see \fBuser_caps(\*n)\fP.
574 These are extensions to the terminfo repertoire which can be loaded
575 using the \fB\-x\fP option of \fB@TIC@\fP.
579 Compiled terminal description database.
581 Although System V Release 2 provided a terminfo library,
582 it had no documented tool for decompiling the terminal descriptions.
583 Tony Hansen (AT&T) wrote the first \fBinfocmp\fP in early 1984,
584 for System V Release 3.
586 Eric Raymond used the AT&T documentation in 1995 to provide an equivalent
587 \fB@INFOCMP@\fP for ncurses.
588 In addition, he added a few new features such as:
590 the \fB\-e\fP option, to support \fIfallback\fP
591 (compiled-in) terminal descriptions
593 the \fB\-i\fP option, to help with analysis
595 Later, Thomas Dickey added the \fB\-x\fP (user-defined capabilities)
596 option, and the \fB\-E\fP option to support fallback entries with
597 user-defined capabilities.
599 For a complete list, see the \fIEXTENSIONS\fP section.
601 In 2010, Roy Marples provided an \fBinfocmp\fP program for NetBSD.
602 It is less capable than the SVr4 or ncurses versions
603 (e.g., it lacks the sorting options documented in X/Open),
604 but does include the \fB\-x\fP option adapted from ncurses.
606 X/Open Curses, Issue 7 (2009) provides a description of \fBinfocmp\fP.
607 It does not mention the options used for converting to termcap format.
628 options are not supported in SVr4 curses.
630 SVr4 infocmp does not distinguish between absent and cancelled capabilities.
631 Also, it shows missing integer capabilities as \fB\-1\fP
632 (the internal value used to represent missing integers).
633 This implementation shows those as \*(``NULL\*('',
634 for consistency with missing strings.
636 The \fB\-r\fP option's notion of \*(``termcap\*('' capabilities
637 is System V Release 4's.
638 Actual BSD curses versions will have a more restricted set.
640 4.4BSD set, use \fB\-r\fP \fB\-RBSD\fP.
642 The \fB\-F\fP option of \fB@INFOCMP@\fP(1M) should be a \fB@TOE@\fP(1M) mode.
644 \fB@CAPTOINFO@\fP(1M),
645 \fB@INFOTOCAP@\fP(1M),
650 \fBuser_caps\fP(\*n).
652 https://invisible-island.net/ncurses/tctest.html
654 This describes \fBncurses\fP
655 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
657 Eric S. Raymond <esr@snark.thyrsus.com>
660 Thomas E. Dickey <dickey@invisible-island.net>