ncurses 5.2
[ncurses.git] / doc / html / man / terminfo.5.html
1 <HTML>
2 <BODY>
3 <PRE>
4 <!-- Manpage converted by man2html 3.0.1 -->
5
6 </PRE>
7 <H2>NAME</H2><PRE>
8        terminfo - terminal capability data base
9
10
11 </PRE>
12 <H2>SYNOPSIS</H2><PRE>
13        /usr/share/terminfo/*/*
14
15
16 </PRE>
17 <H2>DESCRIPTION</H2><PRE>
18        <I>Terminfo</I>  is  a  data  base  describing terminals, used by
19        screen-oriented programs  such  as  <B><A HREF="nvi.1.html">nvi(1)</A></B>,  <B><A HREF="rogue.1.html">rogue(1)</A></B>  and
20        libraries  such  as <B><A HREF="ncurses.3x.html">curses(3x)</A></B>.  <I>Terminfo</I> describes termi-
21        nals by giving a set of capabilities which they  have,  by
22        specifying how to perform screen operations, and by speci-
23        fying padding requirements and initialization sequences.
24
25        Entries in <I>terminfo</I> consist of a sequence of `,' separated
26        fields  (embedded  commas may be escaped with a  backslash
27        or notated as \072).  White space after the `,'  separator
28        is  ignored.   The first entry for each terminal gives the
29        names which are known for the terminal, separated  by  `|'
30        characters.   The  first  name  given  is  the most common
31        abbreviation for the terminal, the last name given  should
32        be  a  long  name  fully identifying the terminal, and all
33        others are understood as synonyms for the  terminal  name.
34        All names but the last should be in lower case and contain
35        no blanks; the last name may well contain upper  case  and
36        blanks for readability.
37
38        Terminal names (except for the last, verbose entry) should
39        be chosen using the following conventions.  The particular
40        piece  of  hardware  making  up the terminal should have a
41        root name, thus ``hp2621''.  This name should not  contain
42        hyphens.  Modes that the hardware can be in, or user pref-
43        erences, should be indicated by appending a hyphen  and  a
44        mode  suffix.   Thus,  a vt100 in 132 column mode would be
45        vt100-w.  The following suffixes should be used where pos-
46        sible:
47
48       <B>Suffix</B>                  <B>Meaning</B>                   <B>Example</B>
49       -<I>nn</I>      Number of lines on the screen            aaa-60
50       -<I>n</I>p      Number of pages of memory                c100-4p
51       -am      With automargins (usually the default)   vt100-am
52       -m       Mono mode; suppress color                ansi-m
53       -mc      Magic cookie; spaces when highlighting   wy30-mc
54       -na      No arrow keys (leave them in local)      c100-na
55       -nam     Without automatic margins                vt100-nam
56       -nl      No status line                           att4415-nl
57       -ns      No status line                           hp2626-ns
58       -rv      Reverse video                            c100-rv
59       -s       Enable status line                       vt100-s
60       -vb      Use visible bell instead of beep         wy370-vb
61       -w       Wide mode (&gt; 80 columns, usually 132)    vt100-w
62
63        For  more  on terminal naming conventions, see the <B>term(7)</B>
64        manual page.
65
66    <B>Capabilities</B>
67        The following is a  complete  table  of  the  capabilities
68        included  in a terminfo description block and available to
69        terminfo-using code.  In each line of the table,
70
71        The <B>variable</B> is the name by which the programmer  (at  the
72        terminfo level) accesses the capability.
73
74        The  <B>capname</B>  is  the  short  name used in the text of the
75        database, and is used by a person updating  the  database.
76        Whenever  possible,  capnames are chosen to be the same as
77        or similar to the ANSI X3.64-1979 standard (now superseded
78        by  ECMA-48,  which uses identical or very similar names).
79        Semantics are also intended to match those of the specifi-
80        cation.
81
82        The  termcap code is the old <B>termcap</B> capability name (some
83        capabilities are new, and have names which termcap did not
84        originate).
85
86        Capability  names have no hard length limit, but an infor-
87        mal limit of 5 characters has been adopted  to  keep  them
88        short  and  to  allow  the tabs in the source file <B>Caps</B> to
89        line up nicely.
90
91        Finally, the description  field  attempts  to  convey  the
92        semantics  of  the capability.  You may find some codes in
93        the description field:
94
95        (P)    indicates that padding may be specified
96
97        #[1-9] in the description field indicates that the  string
98               is passed through tparm with parms as given (#<I>i</I>).
99
100        (P*)   indicates  that  padding  may vary in proportion to
101               the number of lines affected
102
103        (#<I>i</I>)   indicates the <I>i</I>th parameter.
104
105
106        These are the boolean capabilities:
107
108                <B>Variable</B>          <B>Cap-</B>  <B>TCap</B>      <B>Description</B>
109                <B>Booleans</B>          <B>name</B>  <B>Code</B>
110        auto_left_margin          bw    bw    cub1 wraps from col-
111                                              umn 0 to last column
112        auto_right_margin         am    am    terminal has auto-
113                                              matic margins
114        back_color_erase          bce   ut    screen erased with
115                                              background color
116        can_change                ccc   cc    terminal can re-
117                                              define existing col-
118                                              ors
119
120        ceol_standout_glitch      xhp   xs    standout not erased
121                                              by overwriting (hp)
122        col_addr_glitch           xhpa  YA    only positive motion
123                                              for hpa/mhpa caps
124        cpi_changes_res           cpix  YF    changing character
125                                              pitch changes reso-
126                                              lution
127        cr_cancels_micro_mode     crxm  YB    using cr turns off
128                                              micro mode
129        dest_tabs_magic_smso      xt    xt    tabs destructive,
130                                              magic so char
131                                              (t1061)
132        eat_newline_glitch        xenl  xn    newline ignored
133                                              after 80 cols (con-
134                                              cept)
135        erase_overstrike          eo    eo    can erase over-
136                                              strikes with a blank
137        generic_type              gn    gn    generic line type
138        hard_copy                 hc    hc    hardcopy terminal
139        hard_cursor               chts  HC    cursor is hard to
140                                              see
141        has_meta_key              km    km    Has a meta key
142                                              (i.e., sets 8th-bit)
143        has_print_wheel           daisy YC    printer needs opera-
144                                              tor to change char-
145                                              acter set
146        has_status_line           hs    hs    has extra status
147                                              line
148        hue_lightness_saturation  hls   hl    terminal uses only
149                                              HLS color notation
150                                              (Tektronix)
151        insert_null_glitch        in    in    insert mode distin-
152                                              guishes nulls
153        lpi_changes_res           lpix  YG    changing line pitch
154                                              changes resolution
155        memory_above              da    da    display may be
156                                              retained above the
157                                              screen
158        memory_below              db    db    display may be
159                                              retained below the
160                                              screen
161        move_insert_mode          mir   mi    safe to move while
162                                              in insert mode
163        move_standout_mode        msgr  ms    safe to move while
164                                              in standout mode
165        needs_xon_xoff            nxon  nx    padding won't work,
166                                              xon/xoff required
167        no_esc_ctlc               xsb   xb    beehive (f1=escape,
168                                              f2=ctrl C)
169        no_pad_char               npc   NP    pad character does
170                                              not exist
171        non_dest_scroll_region    ndscr ND    scrolling region is
172                                              non-destructive
173
174        non_rev_rmcup             nrrmc NR    smcup does not
175                                              reverse rmcup
176        over_strike               os    os    terminal can over-
177                                              strike
178        prtr_silent               mc5i  5i    printer won't echo
179                                              on screen
180        row_addr_glitch           xvpa  YD    only positive motion
181                                              for vpa/mvpa caps
182        semi_auto_right_margin    sam   YE    printing in last
183                                              column causes cr
184        status_line_esc_ok        eslok es    escape can be used
185                                              on the status line
186        tilde_glitch              hz    hz    can't print ~'s
187                                              (hazeltine)
188        transparent_underline     ul    ul    underline character
189                                              overstrikes
190        xon_xoff                  xon   xo    terminal uses
191                                              xon/xoff handshaking
192
193        These are the numeric capabilities:
194
195             <B>Variable</B>         <B>Cap-</B>     <B>TCap</B>       <B>Description</B>
196              <B>Numeric</B>         <B>name</B>     <B>Code</B>
197        columns               cols     co     number of columns in
198                                              a line
199        init_tabs             it       it     tabs initially every
200                                              # spaces
201        label_height          lh       lh     rows in each label
202        label_width           lw       lw     columns in each
203                                              label
204        lines                 lines    li     number of lines on
205                                              screen or page
206        lines_of_memory       lm       lm     lines of memory if &gt;
207                                              line. 0 means varies
208        magic_cookie_glitch   xmc      sg     number of blank
209                                              characters left by
210                                              smso or rmso
211        max_attributes        ma       ma     maximum combined
212                                              attributes terminal
213                                              can handle
214        max_colors            colors   Co     maximum number of
215                                              colors on screen
216        max_pairs             pairs    pa     maximum number of
217                                              color-pairs on the
218                                              screen
219        maximum_windows       wnum     MW     maximum number of
220                                              defineable windows
221        no_color_video        ncv      NC     video attributes
222                                              that can't be used
223                                              with colors
224        num_labels            nlab     Nl     number of labels on
225                                              screen
226
227
228        padding_baud_rate     pb       pb     lowest baud rate
229                                              where padding needed
230        virtual_terminal      vt       vt     virtual terminal
231                                              number (CB/unix)
232        width_status_line     wsl      ws     number of columns in
233                                              status line
234
235        The following numeric  capabilities  are  present  in  the
236        SVr4.0  term  structure, but are not yet documented in the
237        man page.  They came in with SVr4's printer support.
238
239              <B>Variable</B>         <B>Cap-</B>    <B>TCap</B>       <B>Description</B>
240              <B>Numeric</B>          <B>name</B>    <B>Code</B>
241        bit_image_entwining    bitwin  Yo     number of passes for
242                                              each bit-image row
243        bit_image_type         bitype  Yp     type of bit-image
244                                              device
245        buffer_capacity        bufsz   Ya     numbers of bytes
246                                              buffered before
247                                              printing
248        buttons                btns    BT     number of buttons on
249                                              mouse
250        dot_horz_spacing       spinh   Yc     spacing of dots hor-
251                                              izontally in dots
252                                              per inch
253        dot_vert_spacing       spinv   Yb     spacing of pins ver-
254                                              tically in pins per
255                                              inch
256        max_micro_address      maddr   Yd     maximum value in
257                                              micro_..._address
258        max_micro_jump         mjump   Ye     maximum value in
259                                              parm_..._micro
260        micro_col_size         mcs     Yf     character step size
261                                              when in micro mode
262        micro_line_size        mls     Yg     line step size when
263                                              in micro mode
264        number_of_pins         npins   Yh     numbers of pins in
265                                              print-head
266        output_res_char        orc     Yi     horizontal resolu-
267                                              tion in units per
268                                              line
269        output_res_horz_inch   orhi    Yk     horizontal resolu-
270                                              tion in units per
271                                              inch
272        output_res_line        orl     Yj     vertical resolution
273                                              in units per line
274        output_res_vert_inch   orvi    Yl     vertical resolution
275                                              in units per inch
276        print_rate             cps     Ym     print rate in char-
277                                              acters per second
278        wide_char_size         widcs   Yn     character step size
279                                              when in double wide
280                                              mode
281
282        These are the string capabilities:
283
284                <B>Variable</B>          <B>Cap-</B>   <B>TCap</B>     <B>Description</B>
285                 <B>String</B>           <B>name</B>   <B>Code</B>
286        acs_chars                 acsc   ac   graphics charset
287                                              pairs, based on
288                                              vt100
289        back_tab                  cbt    bt   back tab (P)
290        bell                      bel    bl   audible signal
291                                              (bell) (P)
292        carriage_return           cr     cr   carriage return (P*)
293                                              (P*)
294        change_char_pitch         cpi    ZA   Change number of
295                                              characters per inch
296                                              to #1
297        change_line_pitch         lpi    ZB   Change number of
298                                              lines per inch to #1
299        change_res_horz           chr    ZC   Change horizontal
300                                              resolution to #1
301        change_res_vert           cvr    ZD   Change vertical res-
302                                              olution to #1
303        change_scroll_region      csr    cs   change region to
304                                              line #1 to line #2
305                                              (P)
306        char_padding              rmp    rP   like ip but when in
307                                              insert mode
308        clear_all_tabs            tbc    ct   clear all tab stops
309                                              (P)
310        clear_margins             mgc    MC   clear right and left
311                                              soft margins
312        clear_screen              clear  cl   clear screen and
313                                              home cursor (P*)
314        clr_bol                   el1    cb   Clear to beginning
315                                              of line
316        clr_eol                   el     ce   clear to end of line
317                                              (P)
318        clr_eos                   ed     cd   clear to end of
319                                              screen (P*)
320        column_address            hpa    ch   horizontal position
321                                              #1, absolute (P)
322        command_character         cmdch  CC   terminal settable
323                                              cmd character in
324                                              prototype !?
325        create_window             cwin   CW   define a window #1
326                                              from #2,#3 to #4,#5
327        cursor_address            cup    cm   move to row #1
328                                              columns #2
329        cursor_down               cud1   do   down one line
330        cursor_home               home   ho   home cursor (if no
331                                              cup)
332        cursor_invisible          civis  vi   make cursor invisi-
333                                              ble
334        cursor_left               cub1   le   move left one space
335
336        cursor_mem_address        mrcup  CM   memory relative cur-
337                                              sor addressing, move
338                                              to row #1 columns #2
339        cursor_normal             cnorm  ve   make cursor appear
340                                              normal (undo
341                                              civis/cvvis)
342        cursor_right              cuf1   nd   non-destructive
343                                              space (move right
344                                              one space)
345        cursor_to_ll              ll     ll   last line, first
346                                              column (if no cup)
347        cursor_up                 cuu1   up   up one line
348        cursor_visible            cvvis  vs   make cursor very
349                                              visible
350        define_char               defc   ZE   Define a character
351                                              #1, #2 dots wide,
352                                              descender #3
353        delete_character          dch1   dc   delete character
354                                              (P*)
355        delete_line               dl1    dl   delete line (P*)
356        dial_phone                dial   DI   dial number #1
357        dis_status_line           dsl    ds   disable status line
358        display_clock             dclk   DK   display clock
359        down_half_line            hd     hd   half a line down
360        ena_acs                   enacs  eA   enable alternate
361                                              char set
362        enter_alt_charset_mode    smacs  as   start alternate
363                                              character set (P)
364        enter_am_mode             smam   SA   turn on automatic
365                                              margins
366        enter_blink_mode          blink  mb   turn on blinking
367        enter_bold_mode           bold   md   turn on bold (extra
368                                              bright) mode
369        enter_ca_mode             smcup  ti   string to start pro-
370                                              grams using cup
371        enter_delete_mode         smdc   dm   enter delete mode
372        enter_dim_mode            dim    mh   turn on half-bright
373                                              mode
374        enter_doublewide_mode     swidm  ZF   Enter double-wide
375                                              mode
376        enter_draft_quality       sdrfq  ZG   Enter draft-quality
377                                              mode
378        enter_insert_mode         smir   im   enter insert mode
379        enter_italics_mode        sitm   ZH   Enter italic mode
380        enter_leftward_mode       slm    ZI   Start leftward car-
381                                              riage motion
382        enter_micro_mode          smicm  ZJ   Start micro-motion
383                                              mode
384        enter_near_letter_quality snlq   ZK   Enter NLQ mode
385        enter_normal_quality      snrmq  ZL   Enter normal-quality
386                                              mode
387        enter_protected_mode      prot   mp   turn on protected
388                                              mode
389
390        enter_reverse_mode        rev    mr   turn on reverse
391                                              video mode
392        enter_secure_mode         invis  mk   turn on blank mode
393                                              (characters invisi-
394                                              ble)
395        enter_shadow_mode         sshm   ZM   Enter shadow-print
396                                              mode
397        enter_standout_mode       smso   so   begin standout mode
398        enter_subscript_mode      ssubm  ZN   Enter subscript mode
399        enter_superscript_mode    ssupm  ZO   Enter superscript
400                                              mode
401        enter_underline_mode      smul   us   begin underline mode
402        enter_upward_mode         sum    ZP   Start upward car-
403                                              riage motion
404        enter_xon_mode            smxon  SX   turn on xon/xoff
405                                              handshaking
406        erase_chars               ech    ec   erase #1 characters
407                                              (P)
408        exit_alt_charset_mode     rmacs  ae   end alternate char-
409                                              acter set (P)
410        exit_am_mode              rmam   RA   turn off automatic
411                                              margins
412        exit_attribute_mode       sgr0   me   turn off all
413                                              attributes
414        exit_ca_mode              rmcup  te   strings to end pro-
415                                              grams using cup
416        exit_delete_mode          rmdc   ed   end delete mode
417        exit_doublewide_mode      rwidm  ZQ   End double-wide mode
418        exit_insert_mode          rmir   ei   exit insert mode
419        exit_italics_mode         ritm   ZR   End italic mode
420        exit_leftward_mode        rlm    ZS   End left-motion mode
421        exit_micro_mode           rmicm  ZT   End micro-motion
422                                              mode
423        exit_shadow_mode          rshm   ZU   End shadow-print
424                                              mode
425        exit_standout_mode        rmso   se   exit standout mode
426        exit_subscript_mode       rsubm  ZV   End subscript mode
427        exit_superscript_mode     rsupm  ZW   End superscript mode
428        exit_underline_mode       rmul   ue   exit underline mode
429        exit_upward_mode          rum    ZX   End reverse charac-
430                                              ter motion
431        exit_xon_mode             rmxon  RX   turn off xon/xoff
432                                              handshaking
433        fixed_pause               pause  PA   pause for 2-3 sec-
434                                              onds
435        flash_hook                hook   fh   flash switch hook
436        flash_screen              flash  vb   visible bell (may
437                                              not move cursor)
438        form_feed                 ff     ff   hardcopy terminal
439                                              page eject (P*)
440        from_status_line          fsl    fs   return from status
441                                              line
442        goto_window               wingo  WG   go to window #1
443
444        hangup                    hup    HU   hang-up phone
445        init_1string              is1    i1   initialization
446                                              string
447        init_2string              is2    is   initialization
448                                              string
449        init_3string              is3    i3   initialization
450                                              string
451        init_file                 if     if   name of initializa-
452                                              tion file
453        init_prog                 iprog  iP   path name of program
454                                              for initialization
455        initialize_color          initc  Ic   initialize color #1
456                                              to (#2,#3,#4)
457        initialize_pair           initp  Ip   Initialize color
458                                              pair #1 to
459                                              fg=(#2,#3,#4),
460                                              bg=(#5,#6,#7)
461        insert_character          ich1   ic   insert character (P)
462        insert_line               il1    al   insert line (P*)
463        insert_padding            ip     ip   insert padding after
464                                              inserted character
465        key_a1                    ka1    K1   upper left of keypad
466        key_a3                    ka3    K3   upper right of key-
467                                              pad
468        key_b2                    kb2    K2   center of keypad
469        key_backspace             kbs    kb   backspace key
470        key_beg                   kbeg   @1   begin key
471        key_btab                  kcbt   kB   back-tab key
472        key_c1                    kc1    K4   lower left of keypad
473        key_c3                    kc3    K5   lower right of key-
474                                              pad
475        key_cancel                kcan   @2   cancel key
476        key_catab                 ktbc   ka   clear-all-tabs key
477        key_clear                 kclr   kC   clear-screen or
478                                              erase key
479        key_close                 kclo   @3   close key
480        key_command               kcmd   @4   command key
481        key_copy                  kcpy   @5   copy key
482        key_create                kcrt   @6   create key
483        key_ctab                  kctab  kt   clear-tab key
484        key_dc                    kdch1  kD   delete-character key
485        key_dl                    kdl1   kL   delete-line key
486        key_down                  kcud1  kd   down-arrow key
487        key_eic                   krmir  kM   sent by rmir or smir
488                                              in insert mode
489        key_end                   kend   @7   end key
490        key_enter                 kent   @8   enter/send key
491        key_eol                   kel    kE   clear-to-end-of-line
492                                              key
493        key_eos                   ked    kS   clear-to-end-of-
494                                              screen key
495        key_exit                  kext   @9   exit key
496        key_f0                    kf0    k0   F0 function key
497
498        key_f1                    kf1    k1   F1 function key
499        key_f10                   kf10   k;   F10 function key
500        key_f11                   kf11   F1   F11 function key
501        key_f12                   kf12   F2   F12 function key
502        key_f13                   kf13   F3   F13 function key
503        key_f14                   kf14   F4   F14 function key
504        key_f15                   kf15   F5   F15 function key
505        key_f16                   kf16   F6   F16 function key
506        key_f17                   kf17   F7   F17 function key
507        key_f18                   kf18   F8   F18 function key
508        key_f19                   kf19   F9   F19 function key
509        key_f2                    kf2    k2   F2 function key
510        key_f20                   kf20   FA   F20 function key
511        key_f21                   kf21   FB   F21 function key
512        key_f22                   kf22   FC   F22 function key
513        key_f23                   kf23   FD   F23 function key
514        key_f24                   kf24   FE   F24 function key
515        key_f25                   kf25   FF   F25 function key
516        key_f26                   kf26   FG   F26 function key
517        key_f27                   kf27   FH   F27 function key
518        key_f28                   kf28   FI   F28 function key
519        key_f29                   kf29   FJ   F29 function key
520        key_f3                    kf3    k3   F3 function key
521        key_f30                   kf30   FK   F30 function key
522        key_f31                   kf31   FL   F31 function key
523        key_f32                   kf32   FM   F32 function key
524        key_f33                   kf33   FN   F33 function key
525        key_f34                   kf34   FO   F34 function key
526        key_f35                   kf35   FP   F35 function key
527        key_f36                   kf36   FQ   F36 function key
528        key_f37                   kf37   FR   F37 function key
529        key_f38                   kf38   FS   F38 function key
530        key_f39                   kf39   FT   F39 function key
531        key_f4                    kf4    k4   F4 function key
532        key_f40                   kf40   FU   F40 function key
533        key_f41                   kf41   FV   F41 function key
534        key_f42                   kf42   FW   F42 function key
535        key_f43                   kf43   FX   F43 function key
536        key_f44                   kf44   FY   F44 function key
537        key_f45                   kf45   FZ   F45 function key
538        key_f46                   kf46   Fa   F46 function key
539        key_f47                   kf47   Fb   F47 function key
540        key_f48                   kf48   Fc   F48 function key
541        key_f49                   kf49   Fd   F49 function key
542        key_f5                    kf5    k5   F5 function key
543        key_f50                   kf50   Fe   F50 function key
544        key_f51                   kf51   Ff   F51 function key
545        key_f52                   kf52   Fg   F52 function key
546        key_f53                   kf53   Fh   F53 function key
547        key_f54                   kf54   Fi   F54 function key
548        key_f55                   kf55   Fj   F55 function key
549        key_f56                   kf56   Fk   F56 function key
550        key_f57                   kf57   Fl   F57 function key
551
552        key_f58                   kf58   Fm   F58 function key
553        key_f59                   kf59   Fn   F59 function key
554        key_f6                    kf6    k6   F6 function key
555        key_f60                   kf60   Fo   F60 function key
556        key_f61                   kf61   Fp   F61 function key
557        key_f62                   kf62   Fq   F62 function key
558        key_f63                   kf63   Fr   F63 function key
559        key_f7                    kf7    k7   F7 function key
560        key_f8                    kf8    k8   F8 function key
561        key_f9                    kf9    k9   F9 function key
562        key_find                  kfnd   @0   find key
563        key_help                  khlp   %1   help key
564        key_home                  khome  kh   home key
565        key_ic                    kich1  kI   insert-character key
566        key_il                    kil1   kA   insert-line key
567        key_left                  kcub1  kl   left-arrow key
568        key_ll                    kll    kH   lower-left key (home
569                                              down)
570        key_mark                  kmrk   %2   mark key
571        key_message               kmsg   %3   message key
572        key_move                  kmov   %4   move key
573        key_next                  knxt   %5   next key
574        key_npage                 knp    kN   next-page key
575        key_open                  kopn   %6   open key
576        key_options               kopt   %7   options key
577        key_ppage                 kpp    kP   previous-page key
578        key_previous              kprv   %8   previous key
579        key_print                 kprt   %9   print key
580        key_redo                  krdo   %0   redo key
581        key_reference             kref   &amp;1   reference key
582        key_refresh               krfr   &amp;2   refresh key
583        key_replace               krpl   &amp;3   replace key
584        key_restart               krst   &amp;4   restart key
585        key_resume                kres   &amp;5   resume key
586        key_right                 kcuf1  kr   right-arrow key
587        key_save                  ksav   &amp;6   save key
588        key_sbeg                  kBEG   &amp;9   shifted begin key
589        key_scancel               kCAN   &amp;0   shifted cancel key
590        key_scommand              kCMD   *1   shifted command key
591        key_scopy                 kCPY   *2   shifted copy key
592        key_screate               kCRT   *3   shifted create key
593        key_sdc                   kDC    *4   shifted delete-char-
594                                              acter key
595        key_sdl                   kDL    *5   shifted delete-line
596                                              key
597        key_select                kslt   *6   select key
598        key_send                  kEND   *7   shifted end key
599        key_seol                  kEOL   *8   shifted clear-to-
600                                              end-of-line key
601        key_sexit                 kEXT   *9   shifted exit key
602        key_sf                    kind   kF   scroll-forward key
603        key_sfind                 kFND   *0   shifted find key
604        key_shelp                 kHLP   #1   shifted help key
605
606        key_shome                 kHOM   #2   shifted home key
607        key_sic                   kIC    #3   shifted insert-char-
608                                              acter key
609        key_sleft                 kLFT   #4   shifted left-arrow
610                                              key
611        key_smessage              kMSG   %a   shifted message key
612        key_smove                 kMOV   %b   shifted move key
613        key_snext                 kNXT   %c   shifted next key
614        key_soptions              kOPT   %d   shifted options key
615        key_sprevious             kPRV   %e   shifted previous key
616        key_sprint                kPRT   %f   shifted print key
617        key_sr                    kri    kR   scroll-backward key
618        key_sredo                 kRDO   %g   shifted redo key
619        key_sreplace              kRPL   %h   shifted replace key
620        key_sright                kRIT   %i   shifted right-arrow
621                                              key
622        key_srsume                kRES   %j   shifted resume key
623        key_ssave                 kSAV   !1   shifted save key
624        key_ssuspend              kSPD   !2   shifted suspend key
625        key_stab                  khts   kT   set-tab key
626        key_sundo                 kUND   !3   shifted undo key
627        key_suspend               kspd   &amp;7   suspend key
628        key_undo                  kund   &amp;8   undo key
629        key_up                    kcuu1  ku   up-arrow key
630        keypad_local              rmkx   ke   leave 'key-
631                                              board_transmit' mode
632        keypad_xmit               smkx   ks   enter 'key-
633                                              board_transmit' mode
634        lab_f0                    lf0    l0   label on function
635                                              key f0 if not f0
636        lab_f1                    lf1    l1   label on function
637                                              key f1 if not f1
638        lab_f10                   lf10   la   label on function
639                                              key f10 if not f10
640        lab_f2                    lf2    l2   label on function
641                                              key f2 if not f2
642        lab_f3                    lf3    l3   label on function
643                                              key f3 if not f3
644        lab_f4                    lf4    l4   label on function
645                                              key f4 if not f4
646        lab_f5                    lf5    l5   label on function
647                                              key f5 if not f5
648        lab_f6                    lf6    l6   label on function
649                                              key f6 if not f6
650        lab_f7                    lf7    l7   label on function
651                                              key f7 if not f7
652        lab_f8                    lf8    l8   label on function
653                                              key f8 if not f8
654        lab_f9                    lf9    l9   label on function
655                                              key f9 if not f9
656        label_format              fln    Lf   label format
657        label_off                 rmln   LF   turn off soft labels
658        label_on                  smln   LO   turn on soft labels
659
660        meta_off                  rmm    mo   turn off meta mode
661        meta_on                   smm    mm   turn on meta mode
662                                              (8th-bit on)
663        micro_column_address      mhpa   ZY   Like column_address
664                                              in micro mode
665        micro_down                mcud1  ZZ   Like cursor_down in
666                                              micro mode
667        micro_left                mcub1  Za   Like cursor_left in
668                                              micro mode
669        micro_right               mcuf1  Zb   Like cursor_right in
670                                              micro mode
671        micro_row_address         mvpa   Zc   Like row_address #1
672                                              in micro mode
673        micro_up                  mcuu1  Zd   Like cursor_up in
674                                              micro mode
675        newline                   nel    nw   newline (behave like
676                                              cr followed by lf)
677        order_of_pins             porder Ze   Match software bits
678                                              to print-head pins
679        orig_colors               oc     oc   Set all color pairs
680                                              to the original ones
681        orig_pair                 op     op   Set default pair to
682                                              its original value
683        pad_char                  pad    pc   padding char
684                                              (instead of null)
685        parm_dch                  dch    DC   delete #1 characters
686                                              (P*)
687        parm_delete_line          dl     DL   delete #1 lines (P*)
688        parm_down_cursor          cud    DO   down #1 lines (P*)
689        parm_down_micro           mcud   Zf   Like parm_down_cur-
690                                              sor in micro mode
691        parm_ich                  ich    IC   insert #1 characters
692                                              (P*)
693        parm_index                indn   SF   scroll forward #1
694                                              lines (P)
695        parm_insert_line          il     AL   insert #1 lines (P*)
696        parm_left_cursor          cub    LE   move #1 characters
697                                              to the left (P)
698        parm_left_micro           mcub   Zg   Like parm_left_cur-
699                                              sor in micro mode
700        parm_right_cursor         cuf    RI   move #1 characters
701                                              to the right (P*)
702        parm_right_micro          mcuf   Zh   Like parm_right_cur-
703                                              sor in micro mode
704        parm_rindex               rin    SR   scroll back #1 lines
705                                              (P)
706        parm_up_cursor            cuu    UP   up #1 lines (P*)
707        parm_up_micro             mcuu   Zi   Like parm_up_cursor
708                                              in micro mode
709        pkey_key                  pfkey  pk   program function key
710                                              #1 to type string #2
711
712
713
714        pkey_local                pfloc  pl   program function key
715                                              #1 to execute string
716                                              #2
717        pkey_xmit                 pfx    px   program function key
718                                              #1 to transmit
719                                              string #2
720        plab_norm                 pln    pn   program label #1 to
721                                              show string #2
722        print_screen              mc0    ps   print contents of
723                                              screen
724        prtr_non                  mc5p   pO   turn on printer for
725                                              #1 bytes
726        prtr_off                  mc4    pf   turn off printer
727        prtr_on                   mc5    po   turn on printer
728        pulse                     pulse  PU   select pulse dialing
729        quick_dial                qdial  QD   dial number #1 with-
730                                              out checking
731        remove_clock              rmclk  RC   remove clock
732        repeat_char               rep    rp   repeat char #1 #2
733                                              times (P*)
734        req_for_input             rfi    RF   send next input char
735                                              (for ptys)
736        reset_1string             rs1    r1   reset string
737        reset_2string             rs2    r2   reset string
738        reset_3string             rs3    r3   reset string
739        reset_file                rf     rf   name of reset file
740        restore_cursor            rc     rc   restore cursor to
741                                              position of last
742                                              save_cursor
743        row_address               vpa    cv   vertical position #1
744                                              absolute (P)
745        save_cursor               sc     sc   save current cursor
746                                              position (P)
747        scroll_forward            ind    sf   scroll text up (P)
748        scroll_reverse            ri     sr   scroll text down (P)
749        select_char_set           scs    Zj   Select character
750                                              set, #1
751        set_attributes            sgr    sa   define video
752                                              attributes #1-#9
753                                              (PG9)
754        set_background            setb   Sb   Set background color
755                                              #1
756        set_bottom_margin         smgb   Zk   Set bottom margin at
757                                              current line
758        set_bottom_margin_parm    smgbp  Zl   Set bottom margin at
759                                              line #1 or (if smgtp
760                                              is not given) #2
761                                              lines from bottom
762        set_clock                 sclk   SC   set clock, #1 hrs #2
763                                              mins #3 secs
764        set_color_pair            scp    sp   Set current color
765                                              pair to #1
766
767
768        set_foreground            setf   Sf   Set foreground color
769                                              #1
770        set_left_margin           smgl   ML   set left soft margin
771                                              at current column.
772                                              See smgl. (ML is not
773                                              in BSD termcap).
774        set_left_margin_parm      smglp  Zm   Set left (right)
775                                              margin at column #1
776        set_right_margin          smgr   MR   set right soft mar-
777                                              gin at current col-
778                                              umn
779        set_right_margin_parm     smgrp  Zn   Set right margin at
780                                              column #1
781        set_tab                   hts    st   set a tab in every
782                                              row, current columns
783        set_top_margin            smgt   Zo   Set top margin at
784                                              current line
785        set_top_margin_parm       smgtp  Zp   Set top (bottom)
786                                              margin at row #1
787        set_window                wind   wi   current window is
788                                              lines #1-#2 cols
789                                              #3-#4
790        start_bit_image           sbim   Zq   Start printing bit
791                                              image graphics
792        start_char_set_def        scsd   Zr   Start character set
793                                              definition #1, with
794                                              #2 characters in the
795                                              set
796        stop_bit_image            rbim   Zs   Stop printing bit
797                                              image graphics
798        stop_char_set_def         rcsd   Zt   End definition of
799                                              character set #1
800        subscript_characters      subcs  Zu   List of subscript-
801                                              able characters
802        superscript_characters    supcs  Zv   List of superscript-
803                                              able characters
804        tab                       ht     ta   tab to next 8-space
805                                              hardware tab stop
806        these_cause_cr            docr   Zw   Printing any of
807                                              these characters
808                                              causes CR
809        to_status_line            tsl    ts   move to status line,
810                                              column #1
811        tone                      tone   TO   select touch tone
812                                              dialing
813        underline_char            uc     uc   underline char and
814                                              move past it
815        up_half_line              hu     hu   half a line up
816        user0                     u0     u0   User string #0
817        user1                     u1     u1   User string #1
818        user2                     u2     u2   User string #2
819        user3                     u3     u3   User string #3
820        user4                     u4     u4   User string #4
821
822        user5                     u5     u5   User string #5
823        user6                     u6     u6   User string #6
824        user7                     u7     u7   User string #7
825        user8                     u8     u8   User string #8
826        user9                     u9     u9   User string #9
827        wait_tone                 wait   WA   wait for dial-tone
828        xoff_character            xoffc  XF   XOFF character
829        xon_character             xonc   XN   XON character
830        zero_motion               zerom  Zx   No motion for subse-
831                                              quent character
832
833        The  following  string  capabilities  are  present  in the
834        SVr4.0 term structure, but were originally not  documented
835        in the man page.
836
837                <B>Variable</B>          <B>Cap-</B>     <B>TCap</B>    <B>Description</B>
838                 <B>String</B>           <B>name</B>     <B>Code</B>
839        alt_scancode_esc          scesa    S8   Alternate escape
840                                                for scancode emu-
841                                                lation
842        bit_image_carriage_return bicr     Yv   Move to beginning
843                                                of same row
844        bit_image_newline         binel    Zz   Move to next row
845                                                of the bit image
846        bit_image_repeat          birep    Xy   Repeat bit image
847                                                cell #1 #2 times
848        char_set_names            csnm     Zy   Produce #1'th item
849                                                from list of char-
850                                                acter set names
851        code_set_init             csin     ci   Init sequence for
852                                                multiple codesets
853        color_names               colornm  Yw   Give name for
854                                                color #1
855        define_bit_image_region   defbi    Yx   Define rectan-
856                                                gualar bit image
857                                                region
858        device_type               devt     dv   Indicate lan-
859                                                guage/codeset sup-
860                                                port
861        display_pc_char           dispc    S1   Display PC charac-
862                                                ter #1
863        end_bit_image_region      endbi    Yy   End a bit-image
864                                                region
865        enter_pc_charset_mode     smpch    S2   Enter PC character
866                                                display mode
867        enter_scancode_mode       smsc     S4   Enter PC scancode
868                                                mode
869        exit_pc_charset_mode      rmpch    S3   Exit PC character
870                                                display mode
871        exit_scancode_mode        rmsc     S5   Exit PC scancode
872                                                mode
873
874
875
876        get_mouse                 getm     Gm   Curses should get
877                                                button events,
878                                                parameter #1 not
879                                                documented.
880        key_mouse                 kmous    Km   Mouse event has
881                                                occurred
882        mouse_info                minfo    Mi   Mouse status
883                                                information
884        pc_term_options           pctrm    S6   PC terminal
885                                                options
886        pkey_plab                 pfxl     xl   Program function
887                                                key #1 to type
888                                                string #2 and show
889                                                string #3
890        req_mouse_pos             reqmp    RQ   Request mouse
891                                                position
892        scancode_escape           scesc    S7   Escape for scan-
893                                                code emulation
894        set0_des_seq              s0ds     s0   Shift to code set
895                                                0 (EUC set 0,
896                                                ASCII)
897        set1_des_seq              s1ds     s1   Shift to code set
898                                                1
899        set2_des_seq              s2ds     s2   Shift to code set
900                                                2
901        set3_des_seq              s3ds     s3   Shift to code set
902                                                3
903        set_a_background          setab    AB   Set background
904                                                color to #1, using
905                                                ANSI escape
906        set_a_foreground          setaf    AF   Set foreground
907                                                color to #1, using
908                                                ANSI escape
909        set_color_band            setcolor Yz   Change to ribbon
910                                                color #1
911        set_lr_margin             smglr    ML   Set both left and
912                                                right margins to
913                                                #1, #2.  (ML is
914                                                not in BSD term-
915                                                cap).
916        set_page_length           slines   YZ   Set page length to
917                                                #1 lines
918        set_tb_margin             smgtb    MT   Sets both top and
919                                                bottom margins to
920                                                #1, #2
921
922         The XSI Curses  standard  added  these.   They  are  some
923         post-4.1  versions  of System V curses, e.g., Solaris 2.5
924         and IRIX 6.x.  The <B>ncurses</B> termcap  names  for  them  are
925         invented; according to the XSI Curses standard, they have
926         no termcap names.  If your compiled terminfo entries  use
927         these,  they  may  not be binary-compatible with System V
928         terminfo entries after SVr4.1; beware!
929
930                 <B>Variable</B>         <B>Cap-</B>   <B>TCap</B>     <B>Description</B>
931                  <B>String</B>          <B>name</B>   <B>Code</B>
932         enter_horizontal_hl_mode ehhlm  Xh   Enter horizontal
933                                              highlight mode
934         enter_left_hl_mode       elhlm  Xl   Enter left highlight
935                                              mode
936         enter_low_hl_mode        elohlm Xo   Enter low highlight
937                                              mode
938         enter_right_hl_mode      erhlm  Xr   Enter right high-
939                                              light mode
940         enter_top_hl_mode        ethlm  Xt   Enter top highlight
941                                              mode
942         enter_vertical_hl_mode   evhlm  Xv   Enter vertical high-
943                                              light mode
944         set_a_attributes         sgr1   sA   Define second set of
945                                              video attributes
946                                              #1-#6
947         set_pglen_inch           slengthsL   YI Set page length
948                                              to #1 hundredth of
949                                              an inch
950
951
952    <B>A</B> <B>Sample</B> <B>Entry</B>
953        The following entry, describing an ANSI-standard terminal,
954        is  representative  of  what a <B>terminfo</B> entry for a modern
955        terminal typically looks like.
956
957      ansi|ansi/pc-term compatible with color,
958              mc5i,
959              colors#8, ncv#3, pairs#64,
960              cub=\E[%p1%dD, cud=\E[%p1%dB, cuf=\E[%p1%dC,
961              cuu=\E[%p1%dA, dch=\E[%p1%dP, dl=\E[%p1%dM,
962              ech=\E[%p1%dX, el1=\E[1K, hpa=\E[%p1%dG, ht=\E[I,
963              ich=\E[%p1%d@, il=\E[%p1%dL, indn=\E[%p1%dS, .indn=\E[%p1%dT,
964              kbs=^H, kcbt=\E[Z, kcub1=\E[D, kcud1=\E[B,
965              kcuf1=\E[C, kcuu1=\E[A, kf1=\E[M, kf10=\E[V,
966              kf11=\E[W, kf12=\E[X, kf2=\E[N, kf3=\E[O, kf4=\E[P,
967              kf5=\E[Q, kf6=\E[R, kf7=\E[S, kf8=\E[T, kf9=\E[U,
968              kich1=\E[L, mc4=\E[4i, mc5=\E[5i, nel=\r\E[S,
969              op=\E[37;40m, rep=%p1%c\E[%p2%{1}%-%db,
970              rin=\E[%p1%dT, s0ds=\E(B, s1ds=\E)B, s2ds=\E*B,
971              s3ds=\E+B, setab=\E[4%p1%dm, setaf=\E[3%p1%dm,
972              setb=\E[4%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m,
973              setf=\E[3%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m,
974              sgr=\E[0;10%?%p1%t;7%;%?%p2%t;4%;%?%p3%t;7%;%?%p4%t;5%;%?%p6%t;1%;%?%p7%t;8%;%?%p8%t;11%;%?%p9%t;12%;m,
975              sgr0=\E[0;10m, tbc=\E[2g, u6=\E[%d;%dR, u7=\E[6n,
976              u8=\E[?%[;0123456789]c, u9=\E[c, vpa=\E[%p1%dd,
977
978        Entries may continue onto multiple lines by placing  white
979        space  at  the  beginning  of  each line except the first.
980        Comments may be included on lines  beginning  with  ``#''.
981        Capabilities in <I>terminfo</I> are of three types: Boolean capa-
982        bilities which indicate that the terminal has some partic-
983        ular  feature, numeric capabilities giving the size of the
984        terminal or the size  of  particular  delays,  and  string
985        capabilities,  which  give a sequence which can be used to
986        perform particular terminal operations.
987
988
989    <B>Types</B> <B>of</B> <B>Capabilities</B>
990        All capabilities have names.  For instance, the fact  that
991        ANSI-standard  terminals  have <I>automatic</I> <I>margins</I> (i.e., an
992        automatic return and line-feed when the end of a  line  is
993        reached)  is  indicated  by  the capability <B>am</B>.  Hence the
994        description of ansi includes <B>am</B>.  Numeric capabilities are
995        followed  by  the character `#' and then a positive value.
996        Thus <B>cols</B>, which indicates the number of columns the  ter-
997        minal  has,  gives  the  value  `80' for ansi.  Values for
998        numeric capabilities may be specified in decimal, octal or
999        hexadecimal,  using the C programming language conventions
1000        (e.g., 255, 0377 and 0xff or 0xFF).
1001
1002        Finally, string valued capabilities, such as <B>el</B> (clear  to
1003        end of line sequence) are given by the two-character code,
1004        an `=', and then a string ending  at  the  next  following
1005        `,'.
1006
1007        A  number  of  escape sequences are provided in the string
1008        valued capabilities for easy encoding of characters there.
1009        Both  <B>\E</B>  and  <B>\e</B> map to an ESCAPE character, <B>^x</B> maps to a
1010        control-x for any appropriate x, and the sequences  <B>\n</B>  <B>\l</B>
1011        <B>\r</B>  <B>\t</B>  <B>\b</B>  <B>\f</B>  <B>\s</B> give a newline, line-feed, return, tab,
1012        backspace, form-feed, and space.  Other escapes include <B>\^</B>
1013        for  <B>^</B>, <B>\\</B> for <B>\</B>, <B>\</B>, for comma, <B>\:</B> for <B>:</B>, and <B>\0</B> for null.
1014        (<B>\0</B> will produce \200, which does not terminate  a  string
1015        but behaves as a null character on most terminals, provid-
1016        ing CS7 is specified.  See <B><A HREF="stty.1.html">stty(1)</A></B>.)  Finally,  characters
1017        may be given as three octal digits after a <B>\</B>.
1018
1019        A  delay  in  milliseconds may appear anywhere in a string
1020        capability, enclosed in $&lt;..&gt; brackets, as in  <B>el</B>=\EK$&lt;5&gt;,
1021        and  padding  characters  are supplied by <I>tputs</I> to provide
1022        this delay.  The delay must be a number with at  most  one
1023        decimal place of precision; it may be followed by suffixes
1024        `*' or '/' or both.  A  `*'  indicates  that  the  padding
1025        required  is  proportional to the number of lines affected
1026        by the  operation,  and  the  amount  given  is  the  per-
1027        affected-unit  padding  required.   (In the case of insert
1028        character,  the  factor  is  still  the  number  of  <I>lines</I>
1029        affected.)   Normally,  padding  is advisory if the device
1030        has the <B>xon</B> capability; it is used  for  cost  computation
1031        but  does not trigger delays.  A `/' suffix indicates that
1032        the padding is mandatory and forces a delay of  the  given
1033        number  of  milliseconds  even on devices for which <B>xon</B> is
1034        present to indicate flow control.
1035
1036        Sometimes individual capabilities must be  commented  out.
1037        To  do this, put a period before the capability name.  For
1038        example, see the second <B>ind</B> in the example above.
1039
1040
1041    <B>Fetching</B> <B>Compiled</B> <B>Descriptions</B>
1042        If the environment variable TERMINFO is set, it is  inter-
1043        preted  as the pathname of a directory containing the com-
1044        piled description you are working on.  Only that directory
1045        is searched.
1046
1047        If  TERMINFO  is  not set, the <B>ncurses</B> version of the ter-
1048        minfo reader code  will  instead  look  in  the  directory
1049        <B>$HOME/.terminfo</B>  for  a compiled description.  If it fails
1050        to find one  there,  and  the  environment  variable  TER-
1051        MINFO_DIRS  is set, it will interpret the contents of that
1052        variable as a list of colon- separated directories  to  be
1053        searched  (an  empty  entry is interpreted as a command to
1054        search <I>/usr/share/terminfo</I>).  If no description  is  found
1055        in  any of the TERMINFO_DIRS directories, the fetch fails.
1056
1057        If neither TERMINFO nor TERMINFO_DIRS  is  set,  the  last
1058        place   tried  will  be  the  system  terminfo  directory,
1059        <I>/usr/share/terminfo</I>.
1060
1061        (Neither the  <B>$HOME/.terminfo</B>  lookups  nor  TERMINFO_DIRS
1062        extensions   are  supported  under  stock  System  V  ter-
1063        minfo/curses.)
1064
1065
1066    <B>Preparing</B> <B>Descriptions</B>
1067        We now outline how to prepare descriptions  of  terminals.
1068        The  most  effective way to prepare a terminal description
1069        is by imitating the description of a similar  terminal  in
1070        <I>terminfo</I>  and  to  build up a description gradually, using
1071        partial descriptions with <I>vi</I> or some other screen-oriented
1072        program  to  check that they are correct.  Be aware that a
1073        very unusual terminal may expose deficiencies in the abil-
1074        ity  of  the  <I>terminfo</I>  file to describe it or bugs in the
1075        screen-handling code of the test program.
1076
1077        To get the padding for insert line right (if the  terminal
1078        manufacturer did not document it) a severe test is to edit
1079        a large file at 9600 baud, delete 16 or so lines from  the
1080        middle  of  the screen, then hit the `u' key several times
1081        quickly.  If the terminal messes up, more padding is  usu-
1082        ally  needed.  A similar test can be used for insert char-
1083        acter.
1084
1085
1086    <B>Basic</B> <B>Capabilities</B>
1087        The number of columns on each line  for  the  terminal  is
1088        given  by the <B>cols</B> numeric capability.  If the terminal is
1089        a CRT, then the number of lines on the screen is given  by
1090        the <B>lines</B> capability.  If the terminal wraps around to the
1091        beginning of the next  line  when  it  reaches  the  right
1092        margin,  then  it  should  have the <B>am</B> capability.  If the
1093        terminal can clear its screen, leaving the cursor  in  the
1094        home  position,  then  this  is  given by the <B>clear</B> string
1095        capability.  If  the  terminal  overstrikes  (rather  than
1096        clearing  a position when a character is struck over) then
1097        it should have the <B>os</B> capability.  If the  terminal  is  a
1098        printing terminal, with no soft copy unit, give it both <B>hc</B>
1099        and <B>os</B>.  (<B>os</B> applies to storage scope terminals,  such  as
1100        TEKTRONIX 4010 series, as well as hard copy and APL termi-
1101        nals.)  If there is a code to move the cursor to the  left
1102        edge  of the current row, give this as <B>cr</B>.  (Normally this
1103        will be carriage return, control M.)  If there is  a  code
1104        to  produce  an audible signal (bell, beep, etc) give this
1105        as <B>bel</B>.
1106
1107        If there is a code to move the cursor one position to  the
1108        left  (such  as backspace) that capability should be given
1109        as <B>cub1</B>.  Similarly, codes to move to the right,  up,  and
1110        down should be given as <B>cuf1</B>, <B>cuu1</B>, and <B>cud1</B>.  These local
1111        cursor motions should not alter the text they  pass  over,
1112        for  example,  you would not normally use `<B>cuf1</B>= ' because
1113        the space would erase the character moved over.
1114
1115        A very important point  here  is  that  the  local  cursor
1116        motions  encoded in <I>terminfo</I> are undefined at the left and
1117        top edges  of  a  CRT  terminal.   Programs  should  never
1118        attempt  to  backspace  around the left edge, unless <B>bw</B> is
1119        given, and never attempt to go up locally off the top.  In
1120        order  to  scroll text up, a program will go to the bottom
1121        left corner of the screen and send the <B>ind</B> (index) string.
1122
1123        To scroll text down, a program goes to the top left corner
1124        of the screen and sends the  <B>ri</B>  (reverse  index)  string.
1125        The  strings  <B>ind</B>  and  <B>ri</B> are undefined when not on their
1126        respective corners of the screen.
1127
1128        Parameterized versions of the scrolling sequences are <B>indn</B>
1129        and <B>rin</B> which have the same semantics as <B>ind</B> and <B>ri</B> except
1130        that they take one parameter, and scroll that many  lines.
1131        They  are also undefined except at the appropriate edge of
1132        the screen.
1133
1134        The <B>am</B> capability tells whether the cursor sticks  at  the
1135        right  edge  of  the  screen when text is output, but this
1136        does not necessarily apply to a <B>cuf1</B> from the last column.
1137        The  only local motion which is defined from the left edge
1138        is if <B>bw</B> is given, then a <B>cub1</B> from  the  left  edge  will
1139        move  to the right edge of the previous row.  If <B>bw</B> is not
1140        given, the effect is undefined.  This is useful for  draw-
1141        ing  a box around the edge of the screen, for example.  If
1142        the terminal has switch selectable automatic margins,  the
1143        <I>terminfo</I>  file  usually assumes that this is on; i.e., <B>am</B>.
1144        If the terminal has a command which  moves  to  the  first
1145        column  of the next line, that command can be given as <B>nel</B>
1146        (newline).  It does not matter if the command  clears  the
1147        remainder  of  the current line, so if the terminal has no
1148        <B>cr</B> and <B>lf</B> it may still be possible to craft a working  <B>nel</B>
1149        out of one or both of them.
1150
1151        These  capabilities  suffice  to  describe  hard-copy  and
1152        "glass-tty" terminals.  Thus  the  model  33  teletype  is
1153        described as
1154
1155      33|tty33|tty|model 33 teletype,
1156      bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,
1157
1158        while the Lear Siegler ADM-3 is described as
1159
1160      adm3|3|lsi adm3,
1161      am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J,
1162      ind=^J, lines#24,
1163
1164
1165    <B>Parameterized</B> <B>Strings</B>
1166        Cursor  addressing  and other strings requiring parameters
1167        in the terminal are described by  a  parameterized  string
1168        capability,  with  <B><A HREF="printf.3S.html">printf(3S)</A></B>  like escapes <B>%x</B> in it.  For
1169        example, to address the  cursor,  the  <B>cup</B>  capability  is
1170        given, using two parameters: the row and column to address
1171        to.  (Rows and columns are numbered from zero and refer to
1172        the physical screen visible to the user, not to any unseen
1173        memory.)  If  the  terminal  has  memory  relative  cursor
1174        addressing, that can be indicated by <B>mrcup</B>.
1175
1176        The  parameter  mechanism uses a stack and special <B>%</B> codes
1177        to manipulate it.  Typically a sequence will push  one  of
1178        the  parameters  onto  the stack and then print it in some
1179        format.  Often more complex operations are necessary.
1180
1181        The <B>%</B> encodings have the following meanings:
1182
1183             %%        outputs `%'
1184             %<I>[[</I>:<I>]flags][width[.precision]][</I>doxXs<I>]</I>
1185                       as in <B>printf</B>, flags are [-+#] and space
1186             %c        print pop() like %c in printf()
1187             %s        print pop() like %s in printf()
1188
1189             %p[1-9]   push <I>i</I>'th parm
1190             %P[a-z]   set dynamic variable [a-z] to pop()
1191             %g[a-z]   get dynamic variable [a-z] and push it
1192             %P[A-Z]   set static variable [a-z] to pop()
1193             %g[A-Z]   get static variable [a-z] and push it
1194             %'<I>c</I>'      char constant <I>c</I>
1195             %{<I>nn</I>}     integer constant <I>nn</I>
1196             %l        push strlen(pop)
1197
1198             %+ %- %* %/ %m
1199                       arithmetic (%m is mod): push(pop() op pop())
1200
1201             %&amp; %| %^  bit operations: push(pop() op pop())
1202             %= %&gt; %&lt;  logical operations: push(pop() op pop())
1203             %A, %O    logical and &amp; or operations (for conditionals)
1204             %! %~     unary operations push(op pop())
1205             %i        add 1 to first two parameters (for ANSI terminals)
1206
1207             %? expr %t thenpart %e elsepart %;
1208                       if-then-else, %e elsepart is optional.
1209                       else-if's are possible a la Algol 68:
1210                       %? c1 %t b1 %e c2 %t b2 %e c3 %t b3 %e c4 %t b4 %e %;
1211                       ci are conditions, bi are bodies.
1212
1213        Binary operations are in postfix form with the operands in
1214        the  usual  order.   That  is,  to  get  x-5 one would use
1215        "%gx%{5}%-".  %P and %g variables  are  persistent  across
1216        escape-string evaluations.
1217
1218        Consider the HP2645, which, to get to row 3 and column 12,
1219        needs to be sent \E&amp;a12c03Y  padded  for  6  milliseconds.
1220        Note  that  the  order of the rows and columns is inverted
1221        here, and that the row and column are printed as two  dig-
1222        its.  Thus its <B>cup</B> capability is "cup=6\E&amp;%p2%2dc%p1%2dY".
1223
1224        The Microterm ACT-IV needs the current row and column sent
1225        preceded  by  a <B>^T</B>, with the row and column simply encoded
1226        in binary, "cup=^T%p1%c%p2%c".  Terminals which  use  "%c"
1227        need  to  be  able  to backspace the cursor (<B>cub1</B>), and to
1228        move the cursor up one line on the screen (<B>cuu1</B>).  This is
1229        necessary  because it is not always safe to transmit <B>\n</B> <B>^D</B>
1230        and <B>\r</B>, as the system may change or  discard  them.   (The
1231        library  routines  dealing  with terminfo set tty modes so
1232        that tabs are never expanded, so \t is safe to send.  This
1233        turns out to be essential for the Ann Arbor 4080.)
1234
1235        A final example is the LSI ADM-3a, which uses row and col-
1236        umn  offset  by  a  blank  character,  thus  "cup=\E=%p1%'
1237        '%+%c%p2%'  '%+%c".   After sending `\E=', this pushes the
1238        first parameter, pushes the ASCII value for a space  (32),
1239        adds  them  (pushing  the sum on the stack in place of the
1240        two previous values) and outputs that value as  a  charac-
1241        ter.   Then  the  same  is  done for the second parameter.
1242        More complex arithmetic is possible using the stack.
1243
1244
1245    <B>Cursor</B> <B>Motions</B>
1246        If the terminal has a fast way to home the cursor (to very
1247        upper  left  corner  of  screen) then this can be given as
1248        <B>home</B>; similarly a fast way of getting to the  lower  left-
1249        hand  corner can be given as <B>ll</B>; this may involve going up
1250        with <B>cuu1</B> from the home position,  but  a  program  should
1251        never  do this itself (unless <B>ll</B> does) because it can make
1252        no assumption about the effect of moving up from the  home
1253        position.   Note  that  the  home  position is the same as
1254        addressing to (0,0): to the top left corner of the screen,
1255        not  of  memory.   (Thus, the \EH sequence on HP terminals
1256        cannot be used for <B>home</B>.)
1257
1258        If the terminal has row or column absolute cursor address-
1259        ing,  these  can be given as single parameter capabilities
1260        <B>hpa</B> (horizontal position absolute) and <B>vpa</B> (vertical posi-
1261        tion absolute).  Sometimes these are shorter than the more
1262        general two parameter sequence (as with  the  hp2645)  and
1263        can be used in preference to <B>cup</B>.  If there are parameter-
1264        ized local motions (e.g., move  <I>n</I>  spaces  to  the  right)
1265        these can be given as <B>cud</B>, <B>cub</B>, <B>cuf</B>, and <B>cuu</B> with a single
1266        parameter indicating how many spaces to move.   These  are
1267        primarily  useful  if the terminal does not have <B>cup</B>, such
1268        as the TEKTRONIX 4025.
1269
1270        If the terminal needs to be in a special mode when running
1271        a program that uses these capabilities, the codes to enter
1272        and exit this mode can be given as <B>smcup</B> and <B>rmcup</B>.   This
1273        arises,  for example, from terminals like the Concept with
1274        more than one page of memory.  If the  terminal  has  only
1275        memory  relative cursor addressing and not screen relative
1276        cursor addressing, a one screen-sized window must be fixed
1277        into  the terminal for cursor addressing to work properly.
1278        This is also used for the TEKTRONIX 4025, where <B>smcup</B> sets
1279        the  command character to be the one used by terminfo.  If
1280        the <B>smcup</B> sequence will not restore the  screen  after  an
1281        <B>rmcup</B> sequence is output (to the state prior to outputting
1282        <B>rmcup</B>), specify <B>nrrmc</B>.
1283
1284
1285    <B>Area</B> <B>Clears</B>
1286        If the terminal can clear from the current position to the
1287        end  of  the  line,  leaving  the cursor where it is, this
1288        should be given as <B>el</B>.  If the terminal can clear from the
1289        beginning  of  the line to the current position inclusive,
1290        leaving the cursor where it is, this should  be  given  as
1291        <B>el1</B>.   If the terminal can clear from the current position
1292        to the end of the display, then this should  be  given  as
1293        <B>ed</B>.   <B>Ed</B>  is only defined from the first column of a line.
1294        (Thus, it can be simulated by a request to delete a  large
1295        number of lines, if a true <B>ed</B> is not available.)
1296
1297
1298    <B>Insert/delete</B> <B>line</B> <B>and</B> <B>vertical</B> <B>motions</B>
1299        If  the terminal can open a new blank line before the line
1300        where the cursor is, this should be given as <B>il1</B>; this  is
1301        done  only  from the first position of a line.  The cursor
1302        must then appear on the newly blank line.  If the terminal
1303        can  delete  the  line  which  the cursor is on, then this
1304        should be given as <B>dl1</B>; this is done only from  the  first
1305        position  on  the line to be deleted.  Versions of <B>il1</B> and
1306        <B>dl1</B> which take a single parameter  and  insert  or  delete
1307        that many lines can be given as <B>il</B> and <B>dl</B>.
1308
1309        If  the terminal has a settable scrolling region (like the
1310        vt100) the command to set this can be described  with  the
1311        <B>csr</B>  capability,  which  takes two parameters: the top and
1312        bottom lines of the scrolling region.  The cursor position
1313        is, alas, undefined after using this command.
1314
1315        It  is possible to get the effect of insert or delete line
1316        using <B>csr</B> on a properly chosen region; the <B>sc</B> and <B>rc</B> (save
1317        and  restore  cursor)  commands may be useful for ensuring
1318        that your synthesized insert/delete string does  not  move
1319        the  cursor.  (Note that the <B><A HREF="ncurses.3x.html">ncurses(3x)</A></B> library does this
1320        synthesis  automatically,  so   you   need   not   compose
1321        insert/delete strings for an entry with <B>csr</B>).
1322
1323        Yet another way to construct insert and delete might be to
1324        use a combination of index with  the  memory-lock  feature
1325        found  on some terminals (like the HP-700/90 series, which
1326        however also has insert/delete).
1327
1328        Inserting lines at the top or bottom  of  the  screen  can
1329        also  be  done using <B>ri</B> or <B>ind</B> on many terminals without a
1330        true insert/delete line, and is often faster even on  ter-
1331        minals with those features.
1332
1333        The  boolean  <B>non_dest_scroll_region</B> should be set if each
1334        scrolling window is effectively a view port on  a  screen-
1335        sized  canvas.   To  test  for  this  capability, create a
1336        scrolling region in the middle of the screen, write  some-
1337        thing  to  the  bottom line, move the cursor to the top of
1338        the region, and do <B>ri</B> followed by <B>dl1</B> or <B>ind</B>.  If the data
1339        scrolled  off  the  bottom  of  the  region  by the <B>ri</B> re-
1340        appears, then scrolling is non-destructive.  System V  and
1341        XSI  Curses  expect that <B>ind</B>, <B>ri</B>, <B>indn</B>, and <B>rin</B> will simu-
1342        late destructive scrolling; their  documentation  cautions
1343        you  not  to  define <B>csr</B> unless this is true.  This <B>curses</B>
1344        implementation is more liberal and will do explicit erases
1345        after scrolling if <B>ndstr</B> is defined.
1346
1347        If the terminal has the ability to define a window as part
1348        of memory, which all commands affect, it should  be  given
1349        as the parameterized string <B>wind</B>.  The four parameters are
1350        the starting and ending lines in memory and  the  starting
1351        and ending columns in memory, in that order.
1352
1353        If  the terminal can retain display memory above, then the
1354        <B>da</B> capability should be given; if display  memory  can  be
1355        retained  below,  then <B>db</B> should be given.  These indicate
1356        that deleting a line  or  scrolling  may  bring  non-blank
1357        lines  up  from  below  or that scrolling back with <B>ri</B> may
1358        bring down non-blank lines.
1359
1360
1361    <B>Insert/Delete</B> <B>Character</B>
1362        There are two basic kinds of  intelligent  terminals  with
1363        respect  to insert/delete character which can be described
1364        using <I>terminfo.</I>  The most common  insert/delete  character
1365        operations  affect only the characters on the current line
1366        and shift characters off the  end  of  the  line  rigidly.
1367        Other  terminals,  such  as the Concept 100 and the Perkin
1368        Elmer Owl, make a distinction between  typed  and  untyped
1369        blanks  on  the  screen, shifting upon an insert or delete
1370        only to an untyped blank on the  screen  which  is  either
1371        eliminated,  or  expanded  to two untyped blanks.  You can
1372        determine the kind of terminal you have  by  clearing  the
1373        screen  and  then typing text separated by cursor motions.
1374        Type "abc    def" using local cursor motions (not  spaces)
1375        between the "abc" and the "def".  Then position the cursor
1376        before the "abc" and put the terminal in insert mode.   If
1377        typing  characters  causes  the  rest of the line to shift
1378        rigidly and characters to fall off the end, then your ter-
1379        minal  does  not  distinguish  between  blanks and untyped
1380        positions.  If the "abc" shifts over to  the  "def"  which
1381        then  move together around the end of the current line and
1382        onto the next as you insert, you have the second  type  of
1383        terminal,  and should give the capability <B>in</B>, which stands
1384        for "insert null".  While these are two logically separate
1385        attributes  (one line vs. multi-line insert mode, and spe-
1386        cial treatment of untyped spaces) we have seen  no  termi-
1387        nals whose insert mode cannot be described with the single
1388        attribute.
1389
1390        Terminfo can describe both terminals which have an  insert
1391        mode, and terminals which send a simple sequence to open a
1392        blank position on the current  line.   Give  as  <B>smir</B>  the
1393        sequence  to  get  into  insert  mode.   Give  as <B>rmir</B> the
1394        sequence to leave insert  mode.   Now  give  as  <B>ich1</B>  any
1395        sequence needed to be sent just before sending the charac-
1396        ter to be inserted.  Most terminals  with  a  true  insert
1397        mode  will  not give <B>ich1</B>; terminals which send a sequence
1398        to open a screen position should give it here.
1399
1400        If your terminal has both, insert mode is usually  prefer-
1401        able  to  <B>ich1</B>.   Technically,  you  should  not give both
1402        unless the terminal actually requires both to be  used  in
1403        combination.   Accordingly,  some  non-curses applications
1404        get confused if both are present; the symptom  is  doubled
1405        characters in an update using insert.  This requirement is
1406        now rare; most <B>ich</B> sequences do not require previous smir,
1407        and most smir insert modes do not require <B>ich1</B> before each
1408        character.  Therefore, the  new  <B>curses</B>  actually  assumes
1409        this  is the case and uses either <B>rmir</B>/<B>smir</B> or <B>ich</B>/<B>ich1</B> as
1410        appropriate (but not both).  If you have to write an entry
1411        to  be  used under new curses for a terminal old enough to
1412        need both, include the <B>rmir</B>/<B>smir</B> sequences in <B>ich1</B>.
1413
1414        If post insert padding is needed, give this as a number of
1415        milliseconds  in <B>ip</B> (a string option).  Any other sequence
1416        which may need to be sent after  an  insert  of  a  single
1417        character may also be given in <B>ip</B>.  If your terminal needs
1418        both to be placed into an `insert mode' and a special code
1419        to  precede  each  inserted character, then both <B>smir</B>/<B>rmir</B>
1420        and <B>ich1</B> can be given, and both will  be  used.   The  <B>ich</B>
1421        capability, with one parameter, <I>n</I>, will repeat the effects
1422        of <B>ich1</B> <I>n</I> times.
1423
1424        If padding is necessary between characters typed while not
1425        in  insert  mode,  give  this  as a number of milliseconds
1426        padding in <B>rmp</B>.
1427
1428        It is occasionally  necessary  to  move  around  while  in
1429        insert  mode  to delete characters on the same line (e.g.,
1430        if there is a tab after the insertion position).  If  your
1431        terminal  allows  motion while in insert mode you can give
1432        the capability <B>mir</B> to speed up  inserting  in  this  case.
1433        Omitting  <B>mir</B>  will  affect  only  speed.   Some terminals
1434        (notably Datamedia's) must not have <B>mir</B> because of the way
1435        their insert mode works.
1436
1437        Finally,  you  can specify <B>dch1</B> to delete a single charac-
1438        ter, <B>dch</B> with one parameter, <I>n</I>, to  delete  <I>n</I>  <I>characters,</I>
1439        and  delete mode by giving <B>smdc</B> and <B>rmdc</B> to enter and exit
1440        delete mode (any mode the terminal needs to be  placed  in
1441        for <B>dch1</B> to work).
1442
1443        A  command to erase <I>n</I> characters (equivalent to outputting
1444        <I>n</I> blanks without moving the cursor) can be  given  as  <B>ech</B>
1445        with one parameter.
1446
1447
1448    <B>Highlighting,</B> <B>Underlining,</B> <B>and</B> <B>Visible</B> <B>Bells</B>
1449        If  your  terminal  has  one  or  more  kinds  of  display
1450        attributes, these can be represented in a number  of  dif-
1451        ferent ways.  You should choose one display form as <I>stand-</I>
1452        <I>out</I> <I>mode</I>, representing a good, high contrast, easy-on-the-
1453        eyes,  format  for  highlighting  error messages and other
1454        attention getters.  (If you have a choice,  reverse  video
1455        plus  half-bright  is  good, or reverse video alone.)  The
1456        sequences to enter and exit standout  mode  are  given  as
1457        <B>smso</B>  and  <B>rmso</B>, respectively.  If the code to change into
1458        or out of standout mode  leaves  one  or  even  two  blank
1459        spaces  on the screen, as the TVI 912 and Teleray 1061 do,
1460        then <B>xmc</B> should be given to tell how many spaces are left.
1461
1462        Codes  to  begin  underlining  and  end underlining can be
1463        given as <B>smul</B> and <B>rmul</B> respectively.  If the terminal  has
1464        a  code  to  underline  the current character and move the
1465        cursor one space to the right, such as the Microterm Mime,
1466        this can be given as <B>uc</B>.
1467
1468        Other  capabilities  to  enter  various highlighting modes
1469        include <B>blink</B> (blinking) <B>bold</B> (bold or extra  bright)  <B>dim</B>
1470        (dim  or  half-bright)  <B>invis</B> (blanking or invisible text)
1471        <B>prot</B> (protected) <B>rev</B> (reverse video) <B>sgr0</B>  (turn  off  <I>all</I>
1472        attribute  modes)  <B>smacs</B>  (enter  alternate  character set
1473        mode) and  <B>rmacs</B>  (exit  alternate  character  set  mode).
1474        Turning  on  any of these modes singly may or may not turn
1475        off other modes.
1476
1477        If there is a sequence to set  arbitrary  combinations  of
1478        modes,  this should be given as <B>sgr</B> (set attributes), tak-
1479        ing 9 parameters.  Each parameter is either 0 or  nonzero,
1480        as the corresponding attribute is on or off.  The 9 param-
1481        eters are, in order: standout, underline, reverse,  blink,
1482        dim,  bold,  blank, protect, alternate character set.  Not
1483        all modes need be supported by <B>sgr</B>, only those  for  which
1484        corresponding separate attribute commands exist.
1485
1486        For example, the DEC vt220 supports most of the modes:
1487
1488            <B>tparm</B> <B>parameter</B>   <B>attribute</B>    <B>escape</B> <B>sequence</B>
1489
1490            none              none         \E[0m
1491            p1                standout     \E[0;1;7m
1492            p2                underline    \E[0;4m
1493            p3                reverse      \E[0;7m
1494            p4                blink        \E[0;5m
1495            p5                dim          not available
1496            p6                bold         \E[0;1m
1497            p7                invis        \E[0;8m
1498            p8                protect      not used
1499            p9                altcharset   ^O (off) ^N (on)
1500
1501        We  begin each escape sequence by turning off any existing
1502        modes, since there is no quick way  to  determine  whether
1503        they are active.  Standout is set up to be the combination
1504        of reverse and bold.  The vt220  terminal  has  a  protect
1505        mode,  though  it  is  not commonly used in sgr because it
1506        protects characters on the screen  from  the  host's  era-
1507        sures.   The  altcharset mode also is different in that it
1508        is either ^O or ^N, depending on whether it is off or  on.
1509        If  all  modes  are  turned  on, the resulting sequence is
1510        \E[0;1;4;5;7;8m^N.
1511
1512        Some sequences are common to different modes.   For  exam-
1513        ple,  ;7  is output when either p1 or p3 is true, that is,
1514        if either standout or reverse modes are turned on.
1515
1516        Writing out the above sequences, along with  their  depen-
1517        dencies yields
1518
1519          <B>sequence</B>    <B>when</B> <B>to</B> <B>output</B>     <B>terminfo</B> <B>translation</B>
1520
1521          \E[0       always              \E[0
1522          ;1         if p1 or p6         %?%p1%p6%|%t;1%;
1523          ;4         if p2               %?%p2%|%t;4%;
1524
1525          ;5         if p4               %?%p4%|%t;5%;
1526          ;7         if p1 or p3         %?%p1%p3%|%t;7%;
1527          ;8         if p7               %?%p7%|%t;8%;
1528          m          always              m
1529          ^N or ^O   if p9 ^N, else ^O   %?%p9%t^N%e^O%;
1530
1531        Putting this all together into the sgr sequence gives:
1532
1533            sgr=\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;7%;
1534                %?%p4%t;5%;%?%p7%t;8%;m%?%p9%t\016%e\017%;,
1535
1536        Remember  that  if  you specify sgr, you must also specify
1537        sgr0.
1538
1539        Terminals with the ``magic cookie'' glitch  (<B>xmc</B>)  deposit
1540        special   ``cookies''   when   they  receive  mode-setting
1541        sequences, which affect the display algorithm rather  than
1542        having  extra  bits  for  each character.  Some terminals,
1543        such as the HP 2621,  automatically  leave  standout  mode
1544        when  they  move to a new line or the cursor is addressed.
1545        Programs using standout mode  should  exit  standout  mode
1546        before  moving the cursor or sending a newline, unless the
1547        <B>msgr</B> capability, asserting that it  is  safe  to  move  in
1548        standout mode, is present.
1549
1550        If  the terminal has a way of flashing the screen to indi-
1551        cate an error quietly (a bell replacement) then  this  can
1552        be given as <B>flash</B>; it must not move the cursor.
1553
1554        If  the  cursor  needs to be made more visible than normal
1555        when it is not on the bottom line (to make, for example, a
1556        non-blinking  underline  into  an  easier to find block or
1557        blinking underline) give this sequence as <B>cvvis</B>.  If there
1558        is  a  way  to  make the cursor completely invisible, give
1559        that as <B>civis</B>.  The capability <B>cnorm</B> should be given which
1560        undoes the effects of both of these modes.
1561
1562        If your terminal correctly generates underlined characters
1563        (with no special codes needed) even  though  it  does  not
1564        overstrike,  then you should give the capability <B>ul</B>.  If a
1565        character overstriking another leaves both  characters  on
1566        the screen, specify the capability <B>os</B>.  If overstrikes are
1567        erasable with a blank, then this should  be  indicated  by
1568        giving <B>eo</B>.
1569
1570
1571    <B>Keypad</B> <B>and</B> <B>Function</B> <B>Keys</B>
1572        If the terminal has a keypad that transmits codes when the
1573        keys are pressed, this information can be given. Note that
1574        it  is  not  possible to handle terminals where the keypad
1575        only works in local (this applies,  for  example,  to  the
1576        unshifted  HP  2621  keys).   If  the keypad can be set to
1577        transmit or not transmit, give these  codes  as  <B>smkx</B>  and
1578        <B>rmkx</B>.  Otherwise the keypad is assumed to always transmit.
1579        The codes sent by the left arrow, right arrow,  up  arrow,
1580        down  arrow,  and  home keys can be given as <B>kcub1,</B> <B>kcuf1,</B>
1581        <B>kcuu1,</B> <B>kcud1,</B> and <B>khome</B> respectively.  If there are  func-
1582        tion  keys  such  as f0, f1, ..., f10, the codes they send
1583        can be given as <B>kf0,</B> <B>kf1,</B> <B>...,</B> <B>kf10</B>.  If these  keys  have
1584        labels  other  than the default f0 through f10, the labels
1585        can be given as <B>lf0,</B> <B>lf1,</B> <B>...,</B> <B>lf10</B>.  The codes  transmit-
1586        ted  by certain other special keys can be given: <B>kll</B> (home
1587        down), <B>kbs</B>  (backspace),  <B>ktbc</B>  (clear  all  tabs),  <B>kctab</B>
1588        (clear the tab stop in this column), <B>kclr</B> (clear screen or
1589        erase key), <B>kdch1</B> (delete character), <B>kdl1</B> (delete  line),
1590        <B>krmir</B>  (exit insert mode), <B>kel</B> (clear to end of line), <B>ked</B>
1591        (clear to end of screen), <B>kich1</B> (insert character or enter
1592        insert  mode),  <B>kil1</B>  (insert  line), <B>knp</B> (next page), <B>kpp</B>
1593        (previous page), <B>kind</B> (scroll forward/down),  <B>kri</B>  (scroll
1594        backward/up),  <B>khts</B>  (set  a tab stop in this column).  In
1595        addition, if the keypad has a 3 by 3 array of keys includ-
1596        ing  the four arrow keys, the other five keys can be given
1597        as <B>ka1</B>, <B>ka3</B>, <B>kb2</B>, <B>kc1</B>, and <B>kc3</B>.   These  keys  are  useful
1598        when the effects of a 3 by 3 directional pad are needed.
1599
1600        Strings  to  program  function keys can be given as <B>pfkey</B>,
1601        <B>pfloc</B>, and <B>pfx</B>.  A string to program screen labels  should
1602        be  specified  as  <B>pln</B>.   Each  of these strings takes two
1603        parameters: the function key number to program (from 0  to
1604        10)  and the string to program it with.  Function key num-
1605        bers out of this range may program  undefined  keys  in  a
1606        terminal  dependent  manner.   The  difference between the
1607        capabilities is that <B>pfkey</B> causes pressing the  given  key
1608        to  be the same as the user typing the given string; <B>pfloc</B>
1609        causes the string to be executed by the terminal in local;
1610        and  <B>pfx</B>  causes  the string to be transmitted to the com-
1611        puter.
1612
1613        The capabilities <B>nlab</B>, <B>lw</B> and <B>lh</B> define the number of pro-
1614        grammable  screen  labels  and their width and height.  If
1615        there are commands to turn the labels  on  and  off,  give
1616        them  in <B>smln</B> and <B>rmln</B>.  <B>smln</B> is normally output after one
1617        or more pln sequences to make sure that the change becomes
1618        visible.
1619
1620
1621    <B>Tabs</B> <B>and</B> <B>Initialization</B>
1622        If  the terminal has hardware tabs, the command to advance
1623        to the next tab stop can be given as <B>ht</B>  (usually  control
1624        I).   A  ``back-tab''  command which moves leftward to the
1625        preceding tab stop can be given as <B>cbt</B>.  By convention, if
1626        the  teletype  modes indicate that tabs are being expanded
1627        by the computer rather than being sent  to  the  terminal,
1628        programs  should  not  use <B>ht</B> or <B>cbt</B> even if they are pre-
1629        sent, since the user may not have the tab  stops  properly
1630        set.   If  the  terminal  has hardware tabs which are ini-
1631        tially set every <I>n</I> spaces when the terminal is powered up,
1632        the  numeric  parameter <B>it</B> is given, showing the number of
1633        spaces the tabs are set to.  This is normally used by  the
1634        <I>tset</I>  command  to  determine  whether  to set the mode for
1635        hardware tab expansion, and whether to set the tab  stops.
1636        If  the  terminal  has tab stops that can be saved in non-
1637        volatile memory, the terminfo description can assume  that
1638        they are properly set.
1639
1640        Other  capabilities include <B>is1</B>, <B>is2</B>, and <B>is3</B>, initializa-
1641        tion strings for the terminal, <B>iprog</B>, the path name  of  a
1642        program  to be run to initialize the terminal, and <B>if</B>, the
1643        name of a file  containing  long  initialization  strings.
1644        These  strings are expected to set the terminal into modes
1645        consistent with the  rest  of  the  terminfo  description.
1646        They are normally sent to the terminal, by the <I>init</I> option
1647        of the <I>tput</I> program, each time the  user  logs  in.   They
1648        will  be  printed  in the following order: run the program
1649        <B>iprog</B>; output <B>is1</B>; <B>is2</B>; set the margins  using  <B>mgc</B>,  <B>smgl</B>
1650        and  <B>smgr</B>;  set tabs using <B>tbc</B> and <B>hts</B>; print the file <B>if</B>;
1651        and finally output <B>is3</B>.
1652
1653        Most initialization is done with  <B>is2</B>.   Special  terminal
1654        modes can be set up without duplicating strings by putting
1655        the common sequences in <B>is2</B> and special cases in  <B>is1</B>  and
1656        <B>is3</B>.   A pair of sequences that does a harder reset from a
1657        totally unknown state can be  analogously  given  as  <B>rs1</B>,
1658        <B>rs2</B>,  <B>rf</B>, and <B>rs3</B>, analogous to <B>is2</B> and <B>if</B>.  These strings
1659        are output by the <I>reset</I> program, which is  used  when  the
1660        terminal  gets into a wedged state.  Commands are normally
1661        placed in <B>rs1</B>, <B>rs2</B> <B>rs3</B> and <B>rf</B> only if they produce  annoy-
1662        ing  effects on the screen and are not necessary when log-
1663        ging in.  For example, the command to set the  vt100  into
1664        80-column  mode  would  normally  be  part  of <B>is2</B>, but it
1665        causes an annoying glitch of the screen and  is  not  nor-
1666        mally  needed  since the terminal is usually already in 80
1667        column mode.
1668
1669        If there are commands to set and clear tab stops, they can
1670        be  given  as <B>tbc</B> (clear all tab stops) and <B>hts</B> (set a tab
1671        stop in the current column of every row).  If a more  com-
1672        plex  sequence  is  needed  to  set  the  tabs than can be
1673        described by this, the sequence can be placed  in  <B>is2</B>  or
1674        <B>if</B>.
1675
1676    <B>Delays</B> <B>and</B> <B>Padding</B>
1677        Many  older  and  slower  terminals  don't  support either
1678        XON/XOFF or DTR handshaking, including hard copy terminals
1679        and  some  very  archaic CRTs (including, for example, DEC
1680        VT100s).  These may require padding characters after  cer-
1681        tain cursor motions and screen changes.
1682
1683        If the terminal uses xon/xoff handshaking for flow control
1684        (that is, it automatically emits ^S back to the host  when
1685        its input buffers are close to full), set <B>xon</B>.  This capa-
1686        bility suppresses the emission of padding.  You  can  also
1687        set  it for memory-mapped console devices effectively that
1688        don't have a  speed  limit.   Padding  information  should
1689        still  be  included so that routines can make better deci-
1690        sions about relative costs, but actual pad characters will
1691        not be transmitted.
1692
1693        If  <B>pb</B> (padding baud rate) is given, padding is suppressed
1694        at baud rates below the value of <B>pb</B>.  If the entry has  no
1695        padding  baud rate, then whether padding is emitted or not
1696        is completely controlled by <B>xon</B>.
1697
1698        If the terminal requires other than a null (zero)  charac-
1699        ter  as  a  pad,  then this can be given as <B>pad</B>.  Only the
1700        first character of the <B>pad</B> string is used.
1701
1702
1703    <B>Status</B> <B>Lines</B>
1704        Some terminals have an extra `status line'  which  is  not
1705        normally  used  by  software  (and thus not counted in the
1706        terminal's <B>lines</B> capability).
1707
1708        The simplest case  is  a  status  line  which  is  cursor-
1709        addressable  but  not part of the main scrolling region on
1710        the screen; the Heathkit H19 has a  status  line  of  this
1711        kind,  as  would  a 24-line VT100 with a 23-line scrolling
1712        region set up on initialization.  This situation is  indi-
1713        cated by the <B>hs</B> capability.
1714
1715        Some terminals with status lines need special sequences to
1716        access the status line.   These  may  be  expressed  as  a
1717        string with single parameter <B>tsl</B> which takes the cursor to
1718        a given zero-origin column on the status line.  The  capa-
1719        bility <B>fsl</B> must return to the main-screen cursor positions
1720        before the last <B>tsl</B>.  You may need  to  embed  the  string
1721        values  of <B>sc</B> (save cursor) and <B>rc</B> (restore cursor) in <B>tsl</B>
1722        and <B>fsl</B> to accomplish this.
1723
1724        The status line is normally assumed to be the  same  width
1725        as  the width of the terminal.  If this is untrue, you can
1726        specify it with the numeric capability <B>wsl</B>.
1727
1728        A command to erase or blank the status line may be  speci-
1729        fied as <B>dsl</B>.
1730
1731        The   boolean   capability  <B>eslok</B>  specifies  that  escape
1732        sequences, tabs, etc. work ordinarily in the status  line.
1733
1734        The  <B>ncurses</B>  implementation does not yet use any of these
1735        capabilities.  They are documented here in case they  ever
1736        become important.
1737
1738
1739    <B>Line</B> <B>Graphics</B>
1740        Many  terminals  have  alternate character sets useful for
1741        forms-drawing.  Terminfo and <B>curses</B> build in  support  for
1742        the  drawing  characters supported by the VT100, with some
1743        characters from the AT&amp;T  4410v1  added.   This  alternate
1744        character set may be specified by the <B>acsc</B> capability.
1745
1746                 <B>Glyph</B>             <B>ACS</B>            <B>Ascii</B>      <B>VT100</B>
1747                  <B>Name</B>             <B>Name</B>           <B>Default</B>    <B>Name</B>
1748        UK pound sign              ACS_STERLING   f          }
1749        arrow pointing down        ACS_DARROW     v          .
1750        arrow pointing left        ACS_LARROW     &lt;          ,
1751        arrow pointing right       ACS_RARROW     &gt;          +
1752        arrow pointing up          ACS_UARROW     ^          -
1753        board of squares           ACS_BOARD      #          h
1754        bullet                     ACS_BULLET     o          ~
1755        checker board (stipple)    ACS_CKBOARD    :          a
1756        degree symbol              ACS_DEGREE     \          f
1757        diamond                    ACS_DIAMOND    +          `
1758        greater-than-or-equal-to   ACS_GEQUAL     &gt;          z
1759        greek pi                   ACS_PI         *          {
1760        horizontal line            ACS_HLINE      -          q
1761        lantern symbol             ACS_LANTERN    #          i
1762        large plus or crossover    ACS_PLUS       +          n
1763        less-than-or-equal-to      ACS_LEQUAL     &lt;          y
1764        lower left corner          ACS_LLCORNER   +          m
1765        lower right corner         ACS_LRCORNER   +          j
1766        not-equal                  ACS_NEQUAL     !          |
1767        plus/minus                 ACS_PLMINUS    #          g
1768        scan line 1                ACS_S1         ~          o
1769        scan line 3                ACS_S3         -          p
1770        scan line 7                ACS_S7         -          r
1771        scan line 9                ACS_S9         _          s
1772        solid square block         ACS_BLOCK      #          0
1773        tee pointing down          ACS_TTEE       +          w
1774        tee pointing left          ACS_RTEE       +          u
1775        tee pointing right         ACS_LTEE       +          t
1776        tee pointing up            ACS_BTEE       +          v
1777        upper left corner          ACS_ULCORNER   +          l
1778        upper right corner         ACS_URCORNER   +          k
1779        vertical line              ACS_VLINE      |          x
1780
1781        The  best  way to define a new device's graphics set is to
1782        add a column to a copy of this table  for  your  terminal,
1783        giving   the   character   which   (when  emitted  between
1784        <B>smacs</B>/<B>rmacs</B> switches) will be rendered as the  correspond-
1785        ing  graphic.  Then read off the VT100/your terminal char-
1786        acter pairs right to left in sequence;  these  become  the
1787        ACSC string.
1788
1789
1790    <B>Color</B> <B>Handling</B>
1791        Most  color  terminals are either `Tektronix-like' or `HP-
1792        like'.  Tektronix-like terminals have a predefined set  of
1793        N  colors  (where N usually 8), and can set character-cell
1794        foreground and background characters independently, mixing
1795        them  into  N  * N color-pairs.  On HP-like terminals, the
1796        use must set each color pair up separately (foreground and
1797        background  are  not  independently  settable).   Up  to M
1798        color-pairs may be  set  up  from  2*M  different  colors.
1799        ANSI-compatible terminals are Tektronix-like.
1800
1801        Some basic color capabilities are independent of the color
1802        method.  The numeric capabilities <B>colors</B> and <B>pairs</B> specify
1803        the  maximum numbers of colors and color-pairs that can be
1804        displayed simultaneously.  The <B>op</B> (original  pair)  string
1805        resets  foreground  and background colors to their default
1806        values for the terminal.  The <B>oc</B> string resets all  colors
1807        or  color-pairs  to their default values for the terminal.
1808        Some terminals  (including  many  PC  terminal  emulators)
1809        erase  screen  areas  with  the  current  background color
1810        rather than the power-up default background; these  should
1811        have the boolean capability <B>bce</B>.
1812
1813        To  change the current foreground or background color on a
1814        Tektronix-type terminal, use <B>setaf</B> (set  ANSI  foreground)
1815        and  <B>setab</B>  (set ANSI background) or <B>setf</B> (set foreground)
1816        and <B>setb</B> (set background).  These take one parameter,  the
1817        color  number.   The  SVr4  documentation  describes  only
1818        <B>setaf</B>/<B>setab</B>; the XPG4 draft says  that  "If  the  terminal
1819        supports ANSI escape sequences to set background and fore-
1820        ground, they should be coded as <B>setaf</B> and  <B>setab</B>,  respec-
1821        tively.   If  the terminal supports other escape sequences
1822        to set background and foreground, they should be coded  as
1823        <B>setf</B>  and  <B>setb</B>, respectively.  The <I>vidputs()</I> function and
1824        the refresh functions use <B>setaf</B>  and  <B>setab</B>  if  they  are
1825        defined."
1826
1827        The  <B>setaf</B>/<B>setab</B>  and <B>setf</B>/<B>setb</B> capabilities take a single
1828        numeric argument each.  Argument values 0-7  are  portably
1829        defined  as  follows  (the  middle  column is the symbolic
1830        #define available in the header for the <B>curses</B> or  <B>ncurses</B>
1831        libraries).  The terminal hardware is free to map these as
1832        it likes, but the RGB values indicate normal locations  in
1833        color space.
1834
1835              <B>Color</B>       <B>#define</B>       <B>Value</B>       <B>RGB</B>
1836              black     <B>COLOR_BLACK</B>       0     0, 0, 0
1837              red       <B>COLOR_RED</B>         1     max,0,0
1838              green     <B>COLOR_GREEN</B>       2     0,max,0
1839              yellow    <B>COLOR_YELLOW</B>      3     max,max,0
1840              blue      <B>COLOR_BLUE</B>        4     0,0,max
1841              magenta   <B>COLOR_MAGENTA</B>     5     max,0,max
1842              cyan      <B>COLOR_CYAN</B>        6     0,max,max
1843              white     <B>COLOR_WHITE</B>       7     max,max,max
1844
1845        On  an  HP-like terminal, use <B>scp</B> with a color-pair number
1846        parameter to set which color pair is current.
1847
1848        On a Tektronix-like terminal, the capability  <B>ccc</B>  may  be
1849        present  to  indicate that colors can be modified.  If so,
1850        the <B>initc</B> capability will take a color number (0 to <B>colors</B>
1851        -  1)and  three  more parameters which describe the color.
1852        These three parameters default to being interpreted as RGB
1853        (Red,  Green, Blue) values.  If the boolean capability <B>hls</B>
1854        is present, they are instead as HLS (Hue, Lightness, Satu-
1855        ration) indices.  The ranges are terminal-dependent.
1856
1857        On  an  HP-like  terminal, <B>initp</B> may give a capability for
1858        changing a color-pair value.  It will take  seven  parame-
1859        ters;  a  color-pair  number (0 to <B>max_pairs</B> - 1), and two
1860        triples describing first background  and  then  foreground
1861        colors.   These  parameters  must be (Red, Green, Blue) or
1862        (Hue, Lightness, Saturation) depending on <B>hls</B>.
1863
1864        On some color terminals, colors collide  with  highlights.
1865        You can register these collisions with the <B>ncv</B> capability.
1866        This is a bit-mask of attributes not to be used when  col-
1867        ors  are  enabled.  The correspondence with the attributes
1868        understood by <B>curses</B> is as follows:
1869
1870                       <B>Attribute</B>      <B>Bit</B>   <B>Decimal</B>
1871                       A_STANDOUT     0     1
1872                       A_UNDERLINE    1     2
1873                       A_REVERSE      2     4
1874                       A_BLINK        3     8
1875                       A_DIM          4     16
1876                       A_BOLD         5     32
1877                       A_INVIS        6     64
1878                       A_PROTECT      7     128
1879                       A_ALTCHARSET   8     256
1880
1881        For example,  on  many  IBM  PC  consoles,  the  underline
1882        attribute  collides  with the foreground color blue and is
1883        not available in color mode.  These  should  have  an  <B>ncv</B>
1884        capability of 2.
1885
1886        SVr4  curses  does nothing with <B>ncv</B>, ncurses recognizes it
1887        and optimizes the output in favor of colors.
1888
1889
1890    <B>Miscellaneous</B>
1891        If the terminal requires other than a null (zero)  charac-
1892        ter  as  a  pad,  then this can be given as pad.  Only the
1893        first character of the pad string is used.  If the  termi-
1894        nal does not have a pad character, specify npc.  Note that
1895        ncurses implements  the  termcap-compatible  <B>PC</B>  variable;
1896        though  the  application  may  set this value to something
1897        other than a null, ncurses will test  <B>npc</B>  first  and  use
1898        napms if the terminal has no pad character.
1899
1900        If  the terminal can move up or down half a line, this can
1901        be indicated with <B>hu</B>  (half-line  up)  and  <B>hd</B>  (half-line
1902        down).   This  is  primarily  useful  for superscripts and
1903        subscripts on hard-copy terminals.  If a hard-copy  termi-
1904        nal  can  eject to the next page (form feed), give this as
1905        <B>ff</B> (usually control L).
1906
1907        If there is a command to repeat a given character a  given
1908        number  of times (to save time transmitting a large number
1909        of identical characters) this can be  indicated  with  the
1910        parameterized  string  <B>rep</B>.   The  first  parameter is the
1911        character to be repeated and the second is the  number  of
1912        times  to repeat it.  Thus, tparm(repeat_char, 'x', 10) is
1913        the same as `xxxxxxxxxx'.
1914
1915        If the terminal has a settable command character, such  as
1916        the  TEKTRONIX  4025, this can be indicated with <B>cmdch</B>.  A
1917        prototype command character is chosen which is used in all
1918        capabilities.   This character is given in the <B>cmdch</B> capa-
1919        bility to identify it.  The following convention  is  sup-
1920        ported  on  some  UNIX  systems:  The environment is to be
1921        searched for a <B>CC</B> variable, and if found, all  occurrences
1922        of the prototype character are replaced with the character
1923        in the environment variable.
1924
1925        Terminal descriptions that do  not  represent  a  specific
1926        kind of known terminal, such as <I>switch</I>, <I>dialup</I>, <I>patch</I>, and
1927        <I>network</I>, should include the  <B>gn</B>  (generic)  capability  so
1928        that  programs  can  complain that they do not know how to
1929        talk to the terminal.  (This capability does not apply  to
1930        <I>virtual</I>   terminal   descriptions  for  which  the  escape
1931        sequences are known.)
1932
1933        If the terminal has a ``meta key'' which acts as  a  shift
1934        key,  setting  the  8th  bit of any character transmitted,
1935        this fact can be indicated with <B>km</B>.   Otherwise,  software
1936        will assume that the 8th bit is parity and it will usually
1937        be cleared.  If strings exist to turn this  ``meta  mode''
1938        on and off, they can be given as <B>smm</B> and <B>rmm</B>.
1939
1940        If  the terminal has more lines of memory than will fit on
1941        the screen at once, the number of lines of memory  can  be
1942        indicated  with  <B>lm</B>.   A  value of <B>lm</B>#0 indicates that the
1943        number of lines is not fixed, but that there is still more
1944        memory than fits on the screen.
1945
1946        If the terminal is one of those supported by the UNIX vir-
1947        tual terminal protocol, the terminal number can  be  given
1948        as <B>vt</B>.
1949
1950        Media copy strings which control an auxiliary printer con-
1951        nected to the terminal can be given as <B>mc0</B>: print the con-
1952        tents  of  the screen, <B>mc4</B>: turn off the printer, and <B>mc5</B>:
1953        turn on the printer.  When the printer  is  on,  all  text
1954        sent  to  the terminal will be sent to the printer.  It is
1955        undefined whether the text is also displayed on the termi-
1956        nal screen when the printer is on.  A variation <B>mc5p</B> takes
1957        one parameter, and leaves the printer on for as many char-
1958        acters  as  the  value  of  the  parameter, then turns the
1959        printer off.  The parameter should not  exceed  255.   All
1960        text,  including  <B>mc4</B>,  is  transparently  passed  to  the
1961        printer while an <B>mc5p</B> is in effect.
1962
1963
1964    <B>Glitches</B> <B>and</B> <B>Braindamage</B>
1965        Hazeltine terminals, which do not allow `~' characters  to
1966        be displayed should indicate <B>hz</B>.
1967
1968        Terminals which ignore a line-feed immediately after an <B>am</B>
1969        wrap, such as the Concept and vt100, should indicate <B>xenl</B>.
1970
1971        If  <B>el</B>  is  required  to  get  rid of standout (instead of
1972        merely writing normal text on top of it),  <B>xhp</B>  should  be
1973        given.
1974
1975        Teleray  terminals,  where  tabs turn all characters moved
1976        over to blanks, should  indicate  <B>xt</B>  (destructive  tabs).
1977        Note:    the    variable    indicating    this    is   now
1978        `dest_tabs_magic_smso'; in older  versions,  it  was  tel-
1979        eray_glitch.  This glitch is also taken to mean that it is
1980        not possible to position the cursor on top  of  a  ``magic
1981        cookie'', that to erase standout mode it is instead neces-
1982        sary to use delete and insert line.  The ncurses implemen-
1983        tation ignores this glitch.
1984
1985        The  Beehive Superbee, which is unable to correctly trans-
1986        mit the escape or control C characters, has <B>xsb</B>,  indicat-
1987        ing  that the f1 key is used for escape and f2 for control
1988        C.  (Only certain Superbees have this  problem,  depending
1989        on  the  ROM.)  Note that in older terminfo versions, this
1990        capability  was  called  `beehive_glitch';   it   is   now
1991        `no_esc_ctl_c'.
1992
1993        Other  specific  terminal  problems  may  be  corrected by
1994        adding more capabilities of the form <B>x</B><I>x</I>.
1995
1996
1997    <B>Similar</B> <B>Terminals</B>
1998        If there are two very similar terminals, one (the variant)
1999        can  be  defined  as  being just like the other (the base)
2000        with certain exceptions.  In the definition of  the  vari-
2001        ant,  the string capability <B>use</B> can be given with the name
2002        of the base terminal.  The capabilities given  before  <B>use</B>
2003        override  those  in  the base type named by <B>use</B>.  If there
2004        are multiple <B>use</B> capabilities, they are merged in  reverse
2005        order.   That is, the rightmost <B>use</B> reference is processed
2006        first, then the one to its left, and so forth.   Capabili-
2007        ties  given explicitly in the entry override those brought
2008        in by <B>use</B> references.
2009
2010        A capability can be canceled by placing <B>xx@</B> to the left of
2011        the  use  reference that imports it, where <I>xx</I> is the capa-
2012        bility.  For example, the entry
2013
2014                    2621-nl, smkx@, rmkx@, use=2621,
2015
2016        defines a 2621-nl that does not  have  the  <B>smkx</B>  or  <B>rmkx</B>
2017        capabilities,  and hence does not turn on the function key
2018        labels when in visual mode.  This is useful for  different
2019        modes for a terminal, or for different user preferences.
2020
2021
2022    <B>Pitfalls</B> <B>of</B> <B>Long</B> <B>Entries</B>
2023        Long  terminfo  entries  are  unlikely to be a problem; to
2024        date, no entry has even approached terminfo's  4K  string-
2025        table  maximum.   Unfortunately,  the termcap translations
2026        are much more  strictly  limited  (to  1K),  thus  termcap
2027        translations  of long terminfo entries can cause problems.
2028
2029        The man pages for 4.3BSD and older versions  of  tgetent()
2030        instruct  the user to allocate a 1K buffer for the termcap
2031        entry.  The entry  gets  null-terminated  by  the  termcap
2032        library, so that makes the maximum safe length for a term-
2033        cap entry 1k-1 (1023) bytes.  Depending on what the appli-
2034        cation  and the termcap library being used does, and where
2035        in the termcap file the terminal type  that  tgetent()  is
2036        searching for is, several bad things can happen.
2037
2038        Some  termcap libraries print a warning message or exit if
2039        they find an entry that's longer than 1023  bytes;  others
2040        don't;  others  truncate  the entries to 1023 bytes.  Some
2041        application programs allocate more than the recommended 1K
2042        for the termcap entry; others don't.
2043
2044        Each termcap entry has two important sizes associated with
2045        it: before "tc" expansion, and after "tc" expansion.  "tc"
2046        is  the  capability that tacks on another termcap entry to
2047        the end of the current one, to add  on  its  capabilities.
2048        If  a  termcap entry doesn't use the "tc" capability, then
2049        of course the two lengths are the same.
2050
2051        The "before tc expansion" length  is  the  most  important
2052        one,  because it affects more than just users of that par-
2053        ticular terminal.  This is the length of the entry  as  it
2054        exists in /etc/termcap, minus the backslash-newline pairs,
2055        which tgetent() strips out while reading it.  Some termcap
2056        libraries  strip  off  the final newline, too (GNU termcap
2057        does not).  Now suppose:
2058
2059        *    a termcap entry before expansion is  more  than  1023
2060             bytes long,
2061
2062        *    and the application has only allocated a 1k buffer,
2063
2064        *    and  the  termcap library (like the one in BSD/OS 1.1
2065             and GNU) reads the whole entry into  the  buffer,  no
2066             matter  what  its length, to see if it's the entry it
2067             wants,
2068
2069        *    and tgetent() is searching for a terminal  type  that
2070             either is the long entry, appears in the termcap file
2071             after the long entry, or doesn't appear in  the  file
2072             at  all  (so  that  tgetent() has to search the whole
2073             termcap file).
2074
2075        Then tgetent() will overwrite memory, perhaps  its  stack,
2076        and  probably core dump the program.  Programs like telnet
2077        are particularly vulnerable;  modern  telnets  pass  along
2078        values  like the terminal type automatically.  The results
2079        are almost as undesirable with  a  termcap  library,  like
2080        SunOS  4.1.3  and Ultrix 4.4, that prints warning messages
2081        when it reads an overly long termcap entry.  If a  termcap
2082        library  truncates  long  entries,  like  OSF/1 3.0, it is
2083        immune to dying here but will return  incorrect  data  for
2084        the terminal.
2085
2086        The "after tc expansion" length will have a similar effect
2087        to the above, but only for people who actually set TERM to
2088        that  terminal type, since tgetent() only does "tc" expan-
2089        sion once it's found the terminal type it was looking for,
2090        not while searching.
2091
2092        In summary, a termcap entry that is longer than 1023 bytes
2093        can cause, on various combinations  of  termcap  libraries
2094        and  applications,  a  core  dump,  warnings, or incorrect
2095        operation.  If it's too long even before  "tc"  expansion,
2096        it will have this effect even for users of some other ter-
2097        minal types and users whose TERM variable does not have  a
2098        termcap entry.
2099
2100        When in -C (translate to termcap) mode, the <B>ncurses</B> imple-
2101        mentation of <B><A HREF="tic.1.html">tic(1)</A></B> issues warning messages when the  pre-
2102        tc  length  of  a termcap translation is too long.  The -c
2103        (check) option also checks resolved (after  tc  expansion)
2104        lengths.
2105
2106    <B>Binary</B> <B>Compatibility</B>
2107        It  is not wise to count on portability of binary terminfo
2108        entries between commercial UNIX versions.  The problem  is
2109        that  there  are  at least two versions of terminfo (under
2110        HP-UX and AIX) which diverged from System V terminfo after
2111        SVr1,  and have added extension capabilities to the string
2112        table that (in the binary format) collide  with  System  V
2113        and XSI Curses extensions.
2114
2115
2116 </PRE>
2117 <H2>EXTENSIONS</H2><PRE>
2118        Some  SVr4  <B>curses</B>  implementations,  and  all previous to
2119        SVr4, don't interpret the %A and %O operators in parameter
2120        strings.
2121        SVr4/XPG4  do  not  specify whether <B>msgr</B> licenses movement
2122        while in an alternate-character-set mode (such modes  may,
2123        among other things, map CR and NL to characters that don't
2124        trigger  local  motions).   The   <B>ncurses</B>   implementation
2125        ignores  <B>msgr</B>  in <B>ALTCHARSET</B> mode.  This raises the possi-
2126        bility that an XPG4  implementation  making  the  opposite
2127        interpretation  may need terminfo entries made for <B>ncurses</B>
2128        to have <B>msgr</B> turned off.
2129
2130        The <B>ncurses</B> library handles insert-character  and  insert-
2131        character modes in a slightly non-standard way in order to
2132        get better update efficiency.  See the <B>Insert/Delete</B> <B>Char-</B>
2133        <B>acter</B> subsection above.
2134
2135        The   parameter   substitutions  for  <B>set_clock</B>  and  <B>dis-</B>
2136        <B>play_clock</B> are not documented in SVr4 or  the  XSI  Curses
2137        standard.  They are deduced from the documentation for the
2138        AT&amp;T 505 terminal.
2139
2140        Be careful assigning the <B>kmous</B>  capability.   The  <B>ncurses</B>
2141        wants  to  interpret it as <B>KEY_MOUSE</B>, for use by terminals
2142        and emulators like xterm that  can  return  mouse-tracking
2143        information in the keyboard-input stream.
2144
2145        Different  commercial ports of terminfo and curses support
2146        different subsets of the XSI Curses standard and (in  some
2147        cases) different extension sets.  Here is a summary, accu-
2148        rate as of October 1995:
2149
2150        <B>SVR4,</B> <B>Solaris,</B> <B>ncurses</B> -- These support all SVr4 capabili-
2151        ties.
2152
2153        <B>SGI</B>  --  Supports  the  SVr4  set,  adds  one undocumented
2154        extended string capability (<B>set_pglen</B>).
2155
2156        <B>SVr1,</B> <B>Ultrix</B> -- These support a restricted subset of  ter-
2157        minfo  capabilities.   The booleans end with <B>xon_xoff</B>; the
2158        numerics with  <B>width_status_line</B>;  and  the  strings  with
2159        <B>prtr_non</B>.
2160
2161        <B>HP/UX</B>  --  Supports  the  SVr1  subset,  plus the SVr[234]
2162        numerics <B>num_labels</B>, <B>label_height</B>, <B>label_width</B>, plus func-
2163        tion  keys  11  through  63, plus <B>plab_norm</B>, <B>label_on</B>, and
2164        <B>label_off</B>, plus some incompatible extensions in the string
2165        table.
2166
2167        <B>AIX</B>  --  Supports  the  SVr1 subset, plus function keys 11
2168        through 63, plus a number  of  incompatible  string  table
2169        extensions.
2170
2171        <B>OSF</B>  -- Supports both the SVr4 set and the AIX extensions.
2172
2173
2174 </PRE>
2175 <H2>FILES</H2><PRE>
2176        /usr/share/terminfo/?/*  files     containing     terminal
2177                                 descriptions
2178
2179
2180 </PRE>
2181 <H2>SEE ALSO</H2><PRE>
2182        <B><A HREF="tic.1m.html">tic(1m)</A></B>, <B><A HREF="ncurses.3x.html">curses(3x)</A></B>, <B><A HREF="printf.3S.html">printf(3S)</A></B>, <B><A HREF="term.5.html">term(5)</A></B>.
2183
2184
2185 </PRE>
2186 <H2>AUTHORS</H2><PRE>
2187        Zeyd  M.  Ben-Halim,  Eric  S.  Raymond, Thomas E. Dickey.
2188        Based on pcurses by Pavel Curtis.
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235 </PRE>
2236 <HR>
2237 <ADDRESS>
2238 Man(1) output converted with
2239 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
2240 </ADDRESS>
2241 </BODY>
2242 </HTML>