unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (4.2BSD)
Page:
Section:
Apropos / Subsearch:
optional field

TERMCAP(5)                    File Formats Manual                   TERMCAP(5)



NAME
       termcap - terminal capability data base

SYNOPSIS
       /etc/termcap

DESCRIPTION
       Termcap  is  a data base describing terminals, used, e.g., by vi(1) and
       curses(3X).  Terminals are described in termcap  by  giving  a  set  of
       capabilities which they have, and by describing how operations are per-
       formed.  Padding requirements and initialization sequences are included
       in termcap.

       Entries  in  termcap  consist of a number of `:' separated fields.  The
       first entry for each terminal gives the names which are known  for  the
       terminal,  separated  by  `|'  characters.   The first name is always 2
       characters long and is used by older version 6 systems which store  the
       terminal  type  in a 16 bit word in a systemwide data base.  The second
       name given is the most common abbreviation for the  terminal,  and  the
       last  name  given should be a long name fully identifying the terminal.
       The second name should contain no blanks; the last name may  well  con-
       tain blanks for readability.

CAPABILITIES
       (P) indicates padding may be specified
       (P*) indicates that padding may be based on no. lines affected

       Name   Type  Pad?  Description
       ae     str   (P)   End alternate character set
       al     str   (P*)  Add new blank line
       am     bool        Terminal has automatic margins
       as     str   (P)   Start alternate character set
       bc     str         Backspace if not ^H
       bs     bool        Terminal can backspace with ^H
       bt     str   (P)   Back tab
       bw     bool        Backspace wraps from column 0 to last column
       CC     str         Command character in prototype if terminal settable
       cd     str   (P*)  Clear to end of display
       ce     str   (P)   Clear to end of line
       ch     str   (P)   Like cm but horizontal motion only, line stays same
       cl     str   (P*)  Clear screen
       cm     str   (P)   Cursor motion
       co     num         Number of columns in a line
       cr     str   (P*)  Carriage return, (default ^M)
       cs     str   (P)   Change scrolling region (vt100), like cm
       cv     str   (P)   Like ch but vertical only.
       da     bool        Display may be retained above
       dB     num         Number of millisec of bs delay needed
       db     bool        Display may be retained below
       dC     num         Number of millisec of cr delay needed
       dc     str   (P*)  Delete character
       dF     num         Number of millisec of ff delay needed
       dl     str   (P*)  Delete line
       dm     str         Delete mode (enter)
       dN     num         Number of millisec of nl delay needed
       do     str         Down one line
       dT     num         Number of millisec of tab delay needed
       ed     str         End delete mode
       ei     str         End insert mode; give ":ei=:" if ic
       eo     str         Can erase overstrikes with a blank
       ff     str   (P*)  Hardcopy terminal page eject (default ^L)
       hc     bool        Hardcopy terminal
       hd     str         Half-line down (forward 1/2 linefeed)
       ho     str         Home cursor (if no cm)
       hu     str         Half-line up (reverse 1/2 linefeed)
       hz     str         Hazeltine; can't print ~'s
       ic     str   (P)   Insert character
       if     str         Name of file containing is
       im     bool        Insert mode (enter); give ":im=:" if ic
       in     bool        Insert mode distinguishes nulls on display
       ip     str   (P*)  Insert pad after character inserted
       is     str         Terminal initialization string
       k0-k9  str         Sent by "other" function keys 0-9
       kb     str         Sent by backspace key
       kd     str         Sent by terminal down arrow key
       ke     str         Out of "keypad transmit" mode
       kh     str         Sent by home key
       kl     str         Sent by terminal left arrow key
       kn     num         Number of "other" keys
       ko     str         Termcap entries for other non-function keys
       kr     str         Sent by terminal right arrow key
       ks     str         Put terminal in "keypad transmit" mode
       ku     str         Sent by terminal up arrow key
       l0-l9  str         Labels on "other" function keys
       li     num         Number of lines on screen or page
       ll     str         Last line, first column (if no cm)
       ma     str         Arrow key map, used by vi version 2 only
       mi     bool        Safe to move while in insert mode
       ml     str         Memory lock on above cursor.
       ms     bool        Safe to move while in standout and underline mode
       mu     str         Memory unlock (turn off memory lock).
       nc     bool        No correctly working carriage return (DM2500,H2000)
       nd     str         Non-destructive space (cursor right)
       nl     str   (P*)  Newline character (default \n)
       ns     bool        Terminal is a CRT but doesn't scroll.
       os     bool        Terminal overstrikes
       pc     str         Pad character (rather than null)
       pt     bool        Has hardware tabs (may need to be set with is)
       se     str         End stand out mode
       sf     str   (P)   Scroll forwards
       sg     num         Number of blank chars left by so or se
       so     str         Begin stand out mode
       sr     str   (P)   Scroll reverse (backwards)
       ta     str   (P)   Tab (other than ^I or with padding)
       tc     str         Entry of similar terminal - must be last
       te     str         String to end programs that use cm
       ti     str         String to begin programs that use cm
       uc     str         Underscore one char and move past it
       ue     str         End underscore mode
       ug     num         Number of blank chars left by us or ue
       ul     bool        Terminal underlines even though it doesn't overstrike
       up     str         Upline (cursor up)
       us     str         Start underscore mode
       vb     str         Visible bell (may not move cursor)
       ve     str         Sequence to end open/visual mode
       vs     str         Sequence to start open/visual mode
       xb     bool        Beehive (f1=escape, f2=ctrl C)
       xn     bool        A newline is ignored after a wrap (Concept)
       xr     bool        Return acts like ce \r \n (Delta Data)
       xs     bool        Standout not erased by writing over it (HP 264?)
       xt     bool        Tabs are destructive, magic so char (Teleray 1061)

       A Sample Entry

       The following entry, which describes the Concept-100, is among the more
       complex entries in the termcap file as of this writing.  (This particu-
       lar concept entry is outdated, and is used as an example only.)

       c1|c100|concept100:is=\EU\Ef\E7\E5\E8\El\ENH\EK\E\200\Eo&\200:\
               :al=3*\E^R:am:bs:cd=16*\E^C:ce=16\E^S:cl=2*^L:cm=\Ea%+ %+ :co#80:\
               :dc=16\E^A:dl=3*\E^B:ei=\E\200:eo:im=\E^P:in:ip=16*:li#24:mi:nd=\E=:\
               :se=\Ed\Ee:so=\ED\EE:ta=8\t:ul:up=\E;:vb=\Ek\EK:xn:

       Entries  may  continue  onto  multiple  lines by giving a \ as the last
       character of a line, and that empty fields may be  included  for  read-
       ability  (here  between the last field on a line and the first field on
       the next).  Capabilities in termcap are of three types:  Boolean  capa-
       bilities  which indicate that the terminal has some particular feature,
       numeric capabilities giving the size of the terminal  or  the  size  of
       particular delays, and string capabilities, which give a sequence which
       can be used to perform particular terminal operations.

       Types of Capabilities

       All capabilities have two letter codes.  For instance,  the  fact  that
       the Concept has "automatic margins" (i.e. an automatic return and line-
       feed when the end of a line is reached) is indicated by the  capability
       am.   Hence  the description of the Concept includes am.  Numeric capa-
       bilities are followed by the character `#' and then the value.  Thus co
       which  indicates the number of columns the terminal has gives the value
       `80' for the Concept.

       Finally, string valued capabilities, such as ce (clear to end  of  line
       sequence)  are  given  by  the  two  character code, an `=', and then a
       string ending at the next following `:'.  A delay in  milliseconds  may
       appear  after  the `=' in such a capability, and padding characters are
       supplied by the editor after the remainder of the  string  is  sent  to
       provide  this  delay.  The delay can be either a integer, e.g. `20', or
       an integer followed by an `*', i.e. `3*'.  A  `*'  indicates  that  the
       padding required is proportional to the number of lines affected by the
       operation, and  the  amount  given  is  the  per-affected-unit  padding
       required.   When  a  `*' is specified, it is sometimes useful to give a
       delay of the form `3.5' specify a delay per unit to tenths of millisec-
       onds.

       A number of escape sequences are provided in the string valued capabil-
       ities for easy encoding of characters there.  A \E maps  to  an  ESCAPE
       character,  ^x  maps  to  a  control-x  for  any appropriate x, and the
       sequences \n \r \t \b \f give a newline,  return,  tab,  backspace  and
       formfeed.  Finally, characters may be given as three octal digits after
       a \, and the characters ^ and \ may be given as \^ and \\.   If  it  is
       necessary  to  place a : in a capability it must be escaped in octal as
       \072.  If it is necessary to place a null character in a  string  capa-
       bility  it must be encoded as \200.  The routines which deal with term-
       cap use C strings, and strip the high bits of the output very  late  so
       that a \200 comes out as a \000 would.

       Preparing Descriptions

       We  now  outline  how  to  prepare descriptions of terminals.  The most
       effective way to prepare a terminal description  is  by  imitating  the
       description of a similar terminal in termcap and to build up a descrip-
       tion gradually, using partial descriptions with ex to check  that  they
       are  correct.   Be  aware that a very unusual terminal may expose defi-
       ciencies in the ability of the termcap file to describe it or  bugs  in
       ex.  To easily test a new terminal description you can set the environ-
       ment variable TERMCAP to a pathname of a file containing  the  descrip-
       tion  you  are working on and the editor will look there rather than in
       /etc/termcap.  TERMCAP can also be set to the termcap entry  itself  to
       avoid  reading  the file when starting up the editor.  (This only works
       on version 7 systems.)

       Basic capabilities

       The number of columns on each line for the terminal is given by the  co
       numeric capability.  If the terminal is a CRT, then the number of lines
       on the screen is given by the li capability.   If  the  terminal  wraps
       around to the beginning of the next line when it reaches the right mar-
       gin, then it should have the am capability.  If the terminal can  clear
       its  screen,  then  this  is given by the cl string capability.  If the
       terminal can backspace, then it should have the bs capability, unless a
       backspace  is  accomplished by a character other than ^H (ugh) in which
       case you should give this character as the bc string capability.  If it
       overstrikes (rather than clearing a position when a character is struck
       over) then it should have the os capability.

       A very important point here is that the local cursor motions encoded in
       termcap are undefined at the left and top edges of a CRT terminal.  The
       editor will never attempt to backspace around the left edge,  nor  will
       it attempt to go up locally off the top.  The editor assumes that feed-
       ing off the bottom of the screen will cause the screen  to  scroll  up,
       and the am capability tells whether the cursor sticks at the right edge
       of the screen.  If the terminal has switch  selectable  automatic  mar-
       gins, the termcap file usually assumes that this is on, i.e. am.

       These  capabilities suffice to describe hardcopy and "glass-tty" termi-
       nals.  Thus the model 33 teletype is described as

            t3|33|tty33:co#72:os

       while the Lear Siegler ADM-3 is described as

            cl|adm3|3|lsi adm3:am:bs:cl=^Z:li#24:co#80

       Cursor addressing

       Cursor addressing in the terminal is described by a cm string  capabil-
       ity, with printf(3S) like escapes %x in it.  These substitute to encod-
       ings of the current line or column position, while other characters are
       passed  through  unchanged.   If the cm string is thought of as being a
       function, then its arguments are the line and then the column to  which
       motion is desired, and the % encodings have the following meanings:

            %d   as in printf, 0 origin
            %2   like %2d
            %3   like %3d
            %.   like %c
            %+x  adds x to value, then %.
            %>xy if value > x adds y, no output.
            %r   reverses order of line and column, no output
            %i   increments line/column (for 1 origin)
            %%   gives a single %
            %n   exclusive or row and column with 0140 (DM2500)
            %B   BCD (16*(x/10)) + (x%10), no output.
            %D   Reverse coding (x-2*(x%16)), no output. (Delta Data).

       Consider  the HP2645, which, to get to row 3 and column 12, needs to be
       sent \E&a12c03Y padded for 6 milliseconds.  Note that the order of  the
       rows  and  columns  is  inverted  here, and that the row and column are
       printed as two digits.  Thus its cm  capability  is  "cm=6\E&%r%2c%2Y".
       The  Microterm ACT-IV needs the current row and column sent preceded by
       a ^T, with the row and column simply encoded  in  binary,  "cm=^T%.%.".
       Terminals which use "%." need to be able to backspace the cursor (bs or
       bc), and to move the cursor up one line on the  screen  (up  introduced
       below).   This  is  necessary because it is not always safe to transmit
       \t, \n ^D and \r, as the system may change or discard them.

       A final example is the LSI ADM-3a, which uses row and column offset  by
       a blank character, thus "cm=\E=%+ %+ ".

       Cursor motions

       If  the terminal can move the cursor one position to the right, leaving
       the character at the current position  unchanged,  then  this  sequence
       should be given as nd (non-destructive space).  If it can move the cur-
       sor up a line on the screen in the same column, this should be given as
       up.   If the terminal has no cursor addressing capability, but can home
       the cursor (to very upper left corner of screen) then this can be given
       as  ho;  similarly  a fast way of getting to the lower left hand corner
       can be given as ll; this may involve going up with  up  from  the  home
       position,  but  the  editor  will never do this itself (unless ll does)
       because it makes no assumption about the effect of moving up  from  the
       home position.

       Area clears

       If  the  terminal can clear from the current position to the end of the
       line, leaving the cursor where it is, this should be given as  ce.   If
       the terminal can clear from the current position to the end of the dis-
       play, then this should be given as cd.  The editor only  uses  cd  from
       the first column of a line.

       Insert/delete line

       If  the  terminal  can  open a new blank line before the line where the
       cursor is, this should be given as al; this is done only from the first
       position  of  a  line.   The cursor must then appear on the newly blank
       line.  If the terminal can delete the line which the cursor is on, then
       this  should  be given as dl; this is done only from the first position
       on the line to be deleted.  If the terminal can scroll the screen back-
       wards, then this can be given as sb, but just al suffices.  If the ter-
       minal can retain display memory above then the da capability should  be
       given; if display memory can be retained below then db should be given.
       These let the editor understand that deleting a line on the screen  may
       bring  non-blank lines up from below or that scrolling back with sb may
       bring down non-blank lines.

       Insert/delete character

       There are two basic kinds of  intelligent  terminals  with  respect  to
       insert/delete character which can be described using termcap.  The most
       common insert/delete character operations affect only the characters on
       the  current line and shift characters off the end of the line rigidly.
       Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make
       a  distinction between typed and untyped blanks on the screen, shifting
       upon an insert or delete only to an untyped blank on the  screen  which
       is  either eliminated, or expanded to two untyped blanks.  You can find
       out which kind of terminal you have by clearing  the  screen  and  then
       typing text separated by cursor motions.  Type "abc    def" using local
       cursor motions (not spaces) between the  "abc"  and  the  "def".   Then
       position  the  cursor  before  the "abc" and put the terminal in insert
       mode.  If typing characters causes  the  rest  of  the  line  to  shift
       rigidly and characters to fall off the end, then your terminal does not
       distinguish between blanks and untyped positions.  If the "abc"  shifts
       over  to  the "def" which then move together around the end of the cur-
       rent line and onto the next as you insert, you have the second type  of
       terminal,  and  should give the capability in, which stands for "insert
       null".  If your terminal does something different and unusual then  you
       may  have  to  modify  the editor to get it to use the insert mode your
       terminal defines.  We have seen no terminals which have an insert  mode
       not not falling into one of these two classes.

       The  editor  can  handle  both terminals which have an insert mode, and
       terminals which send a simple sequence to open a blank position on  the
       current line.  Give as im the sequence to get into insert mode, or give
       it an empty value if your terminal uses a sequence to  insert  a  blank
       position.   Give  as  ei  the sequence to leave insert mode (give this,
       with an empty value also if you gave  im  so).   Now  give  as  ic  any
       sequence  needed  to  be  sent  just before sending the character to be
       inserted.  Most terminals with a true insert mode  will  not  give  ic,
       terminals  which  send a sequence to open a screen position should give
       it here.  (Insert mode is preferable to the sequence to open a position
       on  the  screen  if your terminal has both.)  If post insert padding is
       needed, give this as a number of milliseconds in ip (a string  option).
       Any  other sequence which may need to be sent after an insert of a sin-
       gle character may also be given in ip.

       It is occasionally necessary to move around while  in  insert  mode  to
       delete  characters  on  the same line (e.g. if there is a tab after the
       insertion position).  If your terminal allows motion  while  in  insert
       mode you can give the capability mi to speed up inserting in this case.
       Omitting mi will affect only speed.   Some terminals  (notably  Datame-
       dia's) must not have mi because of the way their insert mode works.

       Finally,  you  can specify delete mode by giving dm and ed to enter and
       exit delete mode, and dc to delete a single character while  in  delete
       mode.

       Highlighting, underlining, and visible bells

       If  your  terminal  has sequences to enter and exit standout mode these
       can be given as so and se respectively.  If there are  several  flavors
       of  standout  mode  (such  as inverse video, blinking, or underlining -
       half bright is not usually an acceptable  "standout"  mode  unless  the
       terminal  is  in  inverse  video mode constantly) the preferred mode is
       inverse video by itself.  If the code to change into or out of standout
       mode  leaves one or even two blank spaces on the screen, as the TVI 912
       and Teleray 1061 do, then ug should be given to tell  how  many  spaces
       are left.

       Codes  to  begin underlining and end underlining can be given as us and
       ue respectively.  If the terminal has a code to underline  the  current
       character  and  move  the  cursor  one  space to the right, such as the
       Microterm Mime, this can be given as uc.  (If the underline  code  does
       not  move  the  cursor to the right, give the code followed by a nonde-
       structive space.)

       Many terminals, such as the HP 2621, automatically leave standout  mode
       when  they  move  to  a  new line or the cursor is addressed.  Programs
       using standout mode should exit standout mode before moving the  cursor
       or sending a newline.

       If  the  terminal has a way of flashing the screen to indicate an error
       quietly (a bell replacement) then this can be given as vb; it must  not
       move  the cursor.  If the terminal should be placed in a different mode
       during open and visual modes of ex, this can be given  as  vs  and  ve,
       sent  at  the  start and end of these modes respectively.  These can be
       used to change, e.g., from a underline to a block cursor and back.

       If the terminal needs to be in a special mode when  running  a  program
       that addresses the cursor, the codes to enter and exit this mode can be
       given as ti and te.  This arises, for example, from terminals like  the
       Concept  with  more  than one page of memory.  If the terminal has only
       memory relative  cursor  addressing  and  not  screen  relative  cursor
       addressing,  a  one screen-sized window must be fixed into the terminal
       for cursor addressing to work properly.

       If your terminal correctly generates  underlined  characters  (with  no
       special  codes  needed)  even  though  it does not overstrike, then you
       should give the capability ul.  If  overstrikes  are  erasable  with  a
       blank, then this should be indicated by giving eo.

       Keypad

       If  the  terminal  has  a keypad that transmits codes when the keys are
       pressed, this information can be given. Note that it is not possible to
       handle  terminals  where  the keypad only works in local (this applies,
       for example, to the unshifted HP 2621 keys).  If the keypad can be  set
       to  transmit or not transmit, give these codes as ks and ke.  Otherwise
       the keypad is assumed to always transmit.  The codes sent by  the  left
       arrow, right arrow, up arrow, down arrow, and home keys can be given as
       kl, kr, ku, kd, and kh respectively.  If there are function  keys  such
       as  f0,  f1,  ..., f9, the codes they send can be given as k0, k1, ...,
       k9.  If these keys have labels other than the default  f0  through  f9,
       the  labels  can  be given as l0, l1, ..., l9.  If there are other keys
       that transmit the same code as the terminal expects for the correspond-
       ing  function,  such as clear screen, the termcap 2 letter codes can be
       given in the ko capability, for example, ":ko=cl,ll,sf,sb:", which says
       that the terminal has clear, home down, scroll down, and scroll up keys
       that transmit the same thing as the cl, ll, sf, and sb entries.

       The ma entry is also used to indicate arrow  keys  on  terminals  which
       have  single  character arrow keys.  It is obsolete but still in use in
       version 2 of vi, which must be run on some minicomputers due to  memory
       limitations.   This field is redundant with kl, kr, ku, kd, and kh.  It
       consists of groups of two characters.  In each group, the first charac-
       ter is what an arrow key sends, the second character is the correspond-
       ing vi command.  These commands are h for kl, j for kd, k for ku, l for
       kr,  and H for kh.  For example, the mime would be :ma=^Kj^Zk^Xl: indi-
       cating arrow keys left (^H),  down  (^K),  up  (^Z),  and  right  (^X).
       (There is no home key on the mime.)

       Miscellaneous

       If  the  terminal requires other than a null (zero) character as a pad,
       then this can be given as pc.

       If tabs on the terminal require padding, or  if  the  terminal  uses  a
       character other than ^I to tab, then this can be given as ta.

       Hazeltine  terminals,  which  don't  allow `~' characters to be printed
       should indicate hz.  Datamedia terminals,  which  echo  carriage-return
       linefeed  for  carriage  return  and  then  ignore a following linefeed
       should indicate nc.  Early Concept terminals, which ignore  a  linefeed
       immediately  after  an am wrap, should indicate xn.  If an erase-eol is
       required to get rid of standout (instead of merely writing  on  top  of
       it),  xs should be given.  Teleray terminals, where tabs turn all char-
       acters moved over to blanks, should indicate xt.  Other specific termi-
       nal  problems  may be corrected by adding more capabilities of the form
       xx.

       Other capabilities include is, an initialization string for the  termi-
       nal, and if, the name of a file containing long initialization strings.
       These strings are expected to properly clear and then set the  tabs  on
       the terminal, if the terminal has settable tabs.  If both are given, is
       will be printed before if.  This is useful where  if  is  /usr/lib/tab-
       set/std but is clears the tabs first.

       Similar Terminals

       If  there  are  two very similar terminals, one can be defined as being
       just like the other with certain exceptions.  The string capability  tc
       can  be  given  with the name of the similar terminal.  This capability
       must be last and the combined length of the two entries must not exceed
       1024.  Since  termlib routines search the entry from left to right, and
       since the tc capability is replaced by  the  corresponding  entry,  the
       capabilities  given at the left override the ones in the similar termi-
       nal.  A capability can be canceled with xx@ where xx is the capability.
       For example, the entry

            hn|2621nl:ks@:ke@:tc=2621:

       defines  a  2621nl  that  does  not have the ks or ke capabilities, and
       hence does not turn on the function key labels  when  in  visual  mode.
       This  is  useful  for  different modes for a terminal, or for different
       user preferences.

FILES
       /etc/termcap   file containing terminal descriptions

SEE ALSO
       ex(1), curses(3X), termcap(3X), tset(1), vi(1), ul(1), more(1)

AUTHOR
       William Joy
       Mark Horton added underlining and keypad support

BUGS
       Ex allows only 256 characters for string capabilities, and the routines
       in  termcap(3X)  do  not  check for overflow of this buffer.  The total
       length of a single entry (excluding  only  escaped  newlines)  may  not
       exceed 1024.

       The ma, vs, and ve entries are specific to the vi program.

       Not  all  programs support all entries.  There are entries that are not
       supported by any program.



3rd Berkeley Distribution         10 May 1980                       TERMCAP(5)