78c02edffefdd636cd4b2d81961fc2bf44b73482
[ncurses.git] / doc / html / man / infocmp.1m.html
1 <HTML>
2 <BODY>
3 <PRE>
4 <!-- Manpage converted by man2html 3.0.1 -->
5
6 </PRE>
7 <H2>NAME</H2><PRE>
8        <B>infocmp</B> - compare or print out <I>terminfo</I> descriptions
9
10
11 </PRE>
12 <H2>SYNOPSIS</H2><PRE>
13        <B>infocmp</B> [<B>-dceEGgnpqrILCuV1</B>] [<B>-v</B> <I>n</I>] [<B>-s</B> <B>d</B>| <B>i</B>| <B>l</B>| <B>c</B>]
14              [<B>-w</B> <I>width</I>] [<B>-A</B> <I>directory</I>] [<B>-B</B> <I>directory</I>]
15              [<I>termname</I>...]
16
17
18 </PRE>
19 <H2>DESCRIPTION</H2><PRE>
20        <B>infocmp</B>  can  be  used  to compare a binary <B>terminfo</B> entry
21        with other terminfo entries, rewrite a  <B>terminfo</B>  descrip-
22        tion  to  take  advantage  of  the <B>use=</B> terminfo field, or
23        print out a <B>terminfo</B>  description  from  the  binary  file
24        (<B>term</B>) in a variety of formats.  In all cases, the boolean
25        fields will be printed  first,  followed  by  the  numeric
26        fields, followed by the string fields.
27
28    <B>Default</B> <B>Options</B>
29        If  no options are specified and zero or one <I>termnames</I> are
30        specified, the <B>-I</B> option will be assumed.   If  more  than
31        one  <I>termname</I> is specified, the <B>-d</B> option will be assumed.
32
33    <B>Comparison</B> <B>Options</B> <B>[-d]</B> <B>[-c]</B> <B>[-n]</B>
34        <B>infocmp</B> compares the <B>terminfo</B>  description  of  the  first
35        terminal  <I>termname</I>  with each of the descriptions given by
36        the entries for the  other  terminal's  <I>termnames</I>.   If  a
37        capability  is  defined for only one of the terminals, the
38        value returned will depend on the type of the  capability:
39        <B>F</B>  for  boolean  variables,  <B>-1</B> for integer variables, and
40        <B>NULL</B> for string variables.
41
42        The <B>-d</B> option produces a list of each capability  that  is
43        different  between  two entries.  This option is useful to
44        show the difference between two entries, created  by  dif-
45        ferent people, for the same or similar terminals.
46
47        The  <B>-c</B>  option produces a list of each capability that is
48        common between two entries.  Capabilities that are not set
49        are  ignored.  This option can be used as a quick check to
50        see if the <B>-u</B> option is worth using.
51
52        The <B>-n</B> option produces a list of each capability  that  is
53        in neither entry.  If no <I>termnames</I> are given, the environ-
54        ment variable <B>TERM</B> will be used for both of the <I>termnames</I>.
55        This  can  be used as a quick check to see if anything was
56        left out of a description.
57
58    <B>Source</B> <B>Listing</B> <B>Options</B> <B>[-I]</B> <B>[-L]</B> <B>[-C]</B> <B>[-r]</B>
59        The <B>-I</B>, <B>-L</B>, and <B>-C</B> options will produce a  source  listing
60        for each terminal named.
61
62       <B>-I</B>   use the <B>terminfo</B> names
63       <B>-L</B>   use the long C variable name listed in &lt;<B>term.h</B>&gt;
64
65       <B>-C</B>   use the <B>termcap</B> names
66       <B>-r</B>   when using <B>-C</B>, put out all capabilities in <B>termcap</B> form
67
68        If  no  <I>termnames</I> are given, the environment variable <B>TERM</B>
69        will be used for the terminal name.
70
71        The source produced by the <B>-C</B> option may be used  directly
72        as  a <B>termcap</B> entry, but not all parameterized strings can
73        be changed to the <B>termcap</B> format.  <B>infocmp</B> will attempt to
74        convert  most  of  the parameterized information, and any-
75        thing not converted will be plainly marked in  the  output
76        and commented out.  These should be edited by hand.
77
78        All  padding  information  for  strings  will be collected
79        together and placed at the beginning of the  string  where
80        <B>termcap</B>  expects  it.  Mandatory padding (padding informa-
81        tion with a trailing '/') will become optional.
82
83        All <B>termcap</B> variables no longer supported by <B>terminfo</B>, but
84        which are derivable from other <B>terminfo</B> variables, will be
85        output.  Not all <B>terminfo</B> capabilities will be translated;
86        only  those variables which were part of <B>termcap</B> will nor-
87        mally be output.  Specifying the <B>-r</B> option will  take  off
88        this  restriction,  allowing all capabilities to be output
89        in <I>termcap</I> form.
90
91        Note that because padding is collected to the beginning of
92        the  capability,  not all capabilities are output.  Manda-
93        tory padding is not supported.   Because  <B>termcap</B>  strings
94        are  not as flexible, it is not always possible to convert
95        a <B>terminfo</B> string capability into  an  equivalent  <B>termcap</B>
96        format.   A subsequent conversion of the <B>termcap</B> file back
97        into <B>terminfo</B> format will not  necessarily  reproduce  the
98        original <B>terminfo</B> source.
99
100        Some  common  <B>terminfo</B>  parameter sequences, their <B>termcap</B>
101        equivalents, and some terminal types which  commonly  have
102        such sequences, are:
103
104      <B>terminfo</B>                    <B>termcap</B>   Representative Terminals
105      ---------------------------------------------------------------
106      <B>%p1%c</B>                       <B>%.</B>        adm
107      <B>%p1%d</B>                       <B>%d</B>        hp, ANSI standard, vt100
108      <B>%p1%'x'%+%c</B>                 <B>%+x</B>       concept
109      <B>%i</B>                          <B>%i</B>q       ANSI standard, vt100
110      <B>%p1%?%'x'%&gt;%t%p1%'y'%+%;</B>    <B>%&gt;xy</B>      concept
111      <B>%p2</B> is printed before <B>%p1</B>   <B>%r</B>        hp
112
113    <B>Use=</B> <B>Option</B> <B>[-u]</B>
114        The  <B>-u</B>  option  produces a <B>terminfo</B> source description of
115        the first terminal <I>termname</I> which is relative to  the  sum
116        of  the  descriptions  given  by the entries for the other
117        terminals <I>termnames</I>.  It does this by analyzing  the  dif-
118        ferences   between   the  first  <I>termname</I>  and  the  other
119        <I>termnames</I> and producing a description with <B>use=</B> fields for
120        the  other  terminals.   In this manner, it is possible to
121        retrofit  generic  terminfo  entries  into  a   terminal's
122        description.  Or, if two similar terminals exist, but were
123        coded at different times or by different  people  so  that
124        each description is a full description, using <B>infocmp</B> will
125        show what can be done to change one description to be rel-
126        ative to the other.
127
128        A capability will get printed with an at-sign (@) if it no
129        longer exists in the first <I>termname</I>, but one of the  other
130        <I>termname</I>  entries contains a value for it.  A capability's
131        value gets printed if the value in the first  <I>termname</I>  is
132        not  found in any of the other <I>termname</I> entries, or if the
133        first of the other <I>termname</I> entries that has this capabil-
134        ity  gives  a different value for the capability than that
135        in the first <I>termname</I>.
136
137        The order of the other <I>termname</I>  entries  is  significant.
138        Since  the terminfo compiler <B>tic</B> does a left-to-right scan
139        of the capabilities, specifying two <B>use=</B> entries that con-
140        tain differing entries for the same capabilities will pro-
141        duce different results depending on  the  order  that  the
142        entries  are  given in.  <B>infocmp</B> will flag any such incon-
143        sistencies between the other <I>termname</I> entries as they  are
144        found.
145
146        Alternatively,  specifying a capability <I>after</I> a <B>use=</B> entry
147        that contains that capability will cause the second speci-
148        fication  to  be  ignored.   Using  <B>infocmp</B>  to recreate a
149        description can be a useful check to make sure that every-
150        thing  was  specified  correctly  in  the  original source
151        description.
152
153        Another error  that  does  not  cause  incorrect  compiled
154        files,  but will slow down the compilation time, is speci-
155        fying extra <B>use=</B> fields  that  are  superfluous.   <B>infocmp</B>
156        will  flag  any  other  <I>termname</I> <I>use=</I> fields that were not
157        needed.
158
159    <B>Changing</B> <B>Databases</B> <B>[-A</B> <I>directory</I>] [-B <I>directory</I>]
160        The location of the compiled <B>terminfo</B>  database  is  taken
161        from  the environment variable <B>TERMINFO</B> .  If the variable
162        is not defined, or the terminal is not found in that loca-
163        tion, the system <B>terminfo</B> database, in <B>@DATADIR@/terminfo</B>,
164        will be used.  The options <B>-A</B> and <B>-B</B> may be used to  over-
165        ride  this  location.  The <B>-A</B> option will set <B>TERMINFO</B> for
166        the first <I>termname</I> and the <B>-B</B> option will set <B>TERMINFO</B> for
167        the other <I>termnames</I>.  With this, it is possible to compare
168        descriptions for a terminal with the same name located  in
169        two  different  databases.   This  is useful for comparing
170        descriptions for the same terminal  created  by  different
171        people.
172
173    <B>Other</B>  <B>Options</B>  <B>[-s</B> <B>d|i|l|c]</B> <B>[-1FTVefip]</B> <B>[-Rsubset]</B> <B>[-v</B> <I>n</I>] [-w
174        <I>width</I>]
175        The <B>-s</B> option sorts the fields within each type  according
176        to the argument below:
177
178        <B>d</B>    leave fields in the order that they are stored in the
179             <I>terminfo</I> database.
180
181        <B>i</B>    sort by <I>terminfo</I> name.
182
183        <B>l</B>    sort by the long C variable name.
184
185        <B>c</B>    sort by the <I>termcap</I> name.
186
187             If the <B>-s</B> option is not given, the fields printed out
188             will  be  sorted  alphabetically by the <B>terminfo</B> name
189             within each type, except in the case of the <B>-C</B> or the
190             <B>-L</B> options, which cause the sorting to be done by the
191             <B>termcap</B> name or the long  C  variable  name,  respec-
192             tively.
193
194        <B>-1</B>   causes  the  fields  to be printed out one to a line.
195             Otherwise, the fields will be printed  several  to  a
196             line to a maximum width of 60 characters.
197
198        <B>-F</B>   compare  terminfo  files.  This assumes that two fol-
199             lowing  arguments  are  filenames.   The  files   are
200             searched  for  pairwise matches between entries, with
201             two entries considered to match if any of their names
202             do.   The  report  printed  to  standard output lists
203             entries with  no  matches  in  the  other  file,  and
204             entries  with  more than one match.  For entries with
205             exactly one match it includes  a  difference  report.
206             Normally,  to  reduce  the  volume of the report, use
207             references are not resolved before looking  for  dif-
208             ferences, but resolution can be forced by also speci-
209             fying <B>-r</B>.
210
211        <B>-G</B>   Display constant literals in decimal form rather than
212             their character equivalents.
213
214        <B>-a</B>   tells  <B>infocmp</B>  to  retain commented-out capabilities
215             rather than discarding them.  Capabilities  are  com-
216             mented by prefixing them with a period.
217
218        <B>-q</B>   Make  the comparison listing shorter by omitting sub-
219             headings, and using "-" for absent capabilities,  "@"
220             for canceled rather than "NULL".
221
222        <B>-R</B><I>subset</I>
223             Restrict  output  to  a given subset.  This option is
224             for use with archaic versions of terminfo like  those
225             on  SVr1,  Ultrix,  or  HP/UX that do not support the
226             full set of SVR4/XSI Curses  terminfo;  and  variants
227             such as AIX that have their own extensions incompati-
228             ble with SVr4/XSI.  Available  terminfo  subsets  are
229             "SVr1",  "Ultrix",  "HP",  and "AIX"; see <B><A HREF="terminfo.5.html">terminfo(5)</A></B>
230             for details.  You can also choose  the  subset  "BSD"
231             which  selects only capabilities with termcap equiva-
232             lents recognized by 4.4BSD.
233
234        <B>-T</B>   eliminates size-restrictions on the  generated  text.
235             This is mainly useful for testing and analysis, since
236             the compiled descriptions are limited (e.g., 1023 for
237             termcap, 4096 for terminfo).
238
239        <B>-V</B>   prints out the version of the program in use on stan-
240             dard error and exits.
241
242        <B>-e</B>   Dump the capabilities of the given terminal  as  a  C
243             initializer  for  a  TERMTYPE structure (the terminal
244             capability structure in the <B>&lt;term.h&gt;</B>).   This  option
245             is  useful  for  preparing  versions  of  the  curses
246             library hardwired for a given terminal type.
247
248        <B>-E</B>   Dump  the  capabilities  of  the  given  terminal  as
249             tables,  needed  in  the C initializer for a TERMTYPE
250             structure (the terminal capability structure  in  the
251             <B>&lt;term.h&gt;</B>).   This option is useful for preparing ver-
252             sions of the curses library  hardwired  for  a  given
253             terminal  type.   The tables are all declared static,
254             and are named according to the type and the  name  of
255             the corresponding terminal entry.
256
257             Before  ncurses  5.0, the split between the <B>-e</B> and <B>-E</B>
258             options was not  needed;  but  support  for  extended
259             names required making the arrays of terminal capabil-
260             ities separate from the TERMTYPE structure.
261
262        <B>-f</B>   Display  complex  terminfo  strings   which   contain
263             if/then/else/endif expressions indented for readabil-
264             ity.
265
266        <B>-g</B>   Display constant character literals  in  quoted  form
267             rather than their decimal equivalents.
268
269        <B>-i</B>   Analyze the initialization (<B>is1</B>, <B>is2</B>, <B>is3</B>), and reset
270             (<B>rs1</B>, <B>rs2</B>, <B>rs3</B>), strings  in  the  entry.   For  each
271             string,  the code tries to analyze it into actions in
272             terms of the other capabilities in the entry, certain
273             X3.64/ISO  6429/ECMA-48 capabilities, and certain DEC
274             VT-series private modes (the set of  recognized  spe-
275             cial  sequences  has  been  selected for completeness
276             over the existing terminfo  database).   Each  report
277             line  consists  of the capability name, followed by a
278             colon and space, followed by a printable expansion of
279             the  capability  string with sections matching recog-
280             nized   actions    translated    into    {}-bracketed
281             descriptions.  Here is a list of the DEC/ANSI special
282             sequences recognized:
283
284                   Action        Meaning
285                   -----------------------------------------
286                   RIS           full reset
287                   SC            save cursor
288                   RC            restore cursor
289                   LL            home-down
290                   RSR           reset scroll region
291
292                   ISO DEC G0    enable DEC graphics for G0
293                   ISO UK G0     enable UK chars for G0
294                   ISO US G0     enable US chars for G0
295                   ISO DEC G1    enable DEC graphics for G1
296                   ISO UK G1     enable UK chars for G1
297                   ISO US G1     enable US chars for G1
298
299                   DECPAM        application keypad mode
300                   DECPNM        normal keypad mode
301                   DECANSI       enter ANSI mode
302
303                   DEC[+-]CKM    application cursor keys
304                   DEC[+-]ANM    set VT52 mode
305                   DEC[+-]COLM   132-column mode
306                   DEC[+-]SCLM   smooth scroll
307                   DEC[+-]SCNM   reverse video mode
308                   DEC[+-]OM     origin mode
309                   DEC[+-]AWM    wraparound mode
310                   DEC[+-]ARM    auto-repeat mode
311
312             It also recognizes  a  SGR  action  corresponding  to
313             ANSI/ISO  6429/ECMA  Set Graphics Rendition, with the
314             values NORMAL, BOLD, UNDERLINE, BLINK,  and  REVERSE.
315             All  but NORMAL may be prefixed with `+' (turn on) or
316             `-' (turn off).
317
318             An  SGR0  designates  an  empty  highlight   sequence
319             (equivalent to {SGR:NORMAL}).
320
321        <B>-p</B>   Ignore padding specifications when comparing strings.
322
323        <B>-v</B> <I>n</I> prints out tracing information on standard  error  as
324             the  program runs.  Higher values of n induce greater
325             verbosity.
326
327        <B>-w</B> <I>width</I>
328             changes the output to <I>width</I> characters.
329
330
331 </PRE>
332 <H2>FILES</H2><PRE>
333        @DATADIR@/terminfo  Compiled     terminal      description
334                            database.
335
336
337
338 </PRE>
339 <H2>EXTENSIONS</H2><PRE>
340        The  <B>-E</B>,  <B>-F</B>,  <B>-G</B>,  <B>-R</B>, <B>-T</B>, <B>-a</B>, <B>-e</B>, <B>-f</B>, <B>-g</B>, <B>-i</B>, <B>-p</B>, and <B>-q</B>
341        options are not supported in SVr4 curses.
342
343        The <B>-r</B> option's notion of `termcap' capabilities is System
344        V  Release  4's.   Actual  BSD curses versions will have a
345        more restricted set.  To see only the 4.4BSD set,  use  -r
346        -RBSD.
347
348
349 </PRE>
350 <H2>BUGS</H2><PRE>
351        The -F option of <B><A HREF="infocmp.1m.html">infocmp(1m)</A></B> should be a <B><A HREF="toe.1m.html">toe(1m)</A></B> mode.
352
353
354 </PRE>
355 <H2>SEE ALSO</H2><PRE>
356        <B><A HREF="infocmp.1m.html">infocmp(1m)</A></B>,    <B><A HREF="captoinfo.1m.html">captoinfo(1m)</A></B>,   <B><A HREF="infotocap.1m.html">infotocap(1m)</A></B>,   <B><A HREF="tic.1m.html">tic(1m)</A></B>,
357        <B><A HREF="toe.1m.html">toe(1m)</A></B>, <B><A HREF="ncurses.3x.html">curses(3x)</A></B>, <B><A HREF="terminfo.5.html">terminfo(5)</A></B>.
358
359
360 </PRE>
361 <H2>AUTHOR</H2><PRE>
362        Eric S.  Raymond  &lt;esr@snark.thyrsus.com&gt;  and  Thomas  E.
363        Dickey &lt;dickey@herndon4.his.com&gt;
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399 </PRE>
400 <HR>
401 <ADDRESS>
402 Man(1) output converted with
403 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
404 </ADDRESS>
405 </BODY>
406 </HTML>