Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TERMCAP(5)							    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  that  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 that are  known  for  the
       terminal,  separated  by	 `|' characters.  The first name is always two
       characters long and is used by older systems which store	 the  terminal
       type  in	 a  16-bit  word  in a system-wide data	base.  The second name
       given is	the most common	abbreviation for the terminal, the  last  name
       given  should  be  a  long name fully identifying the terminal, and all
       others are understood as	synonyms for the terminal name.	 All names but
       the  first  and last should be in lower case and	contain	no blanks; the
       last name may well contain upper	case and blanks	for readability.

       Terminal	names (except for the last, verbose entry)  should  be	chosen
       using the following conventions.	 The particular	piece of hardware mak-
       ing up the terminal should have a  root	name  chosen,  thus  "hp2621".
       This  name  should not contain hyphens.	Modes that the hardware	can be
       in or user preferences should be	indicated by appending a hyphen	and an
       indicator  of  the mode.	 Therefore, a "vt100" in 132-column mode would
       be "vt100-w".  The following suffixes should be used where possible:

       Suffix	Meaning					  Example
       -w	Wide mode (more	than 80	columns)	  vt100-w
       -am	With automatic margins (usually	default)  vt100-am
       -nam	Without	automatic margins		  vt100-nam
       -n	Number of lines	on the screen		  aaa-60
       -na	No arrow keys (leave them in local)	  concept100-na
       -np	Number of pages	of memory		  concept100-4p
       -rv	Reverse	video				  concept100-rv

CAPABILITIES
       The characters in the Notes field in the	table have the following mean-
       ings (more than one may apply to	a capability):

       N   indicates numeric parameter(s)
       P   indicates that padding may be specified
       *   indicates that padding may be based on the number of	lines affected
       o   indicates capability	is obsolete

       "Obsolete"  capabilities	 have no terminfo equivalents, since they were
       considered useless, or are subsumed by other capabilities.   New	 soft-
       ware should not rely on them at all.

       Name  Type  Notes  Description
       ae    str   (P)	  End alternate	character set
       AL    str   (NP*)  Add n	new blank lines
       al    str   (P*)	  Add new blank	line
       am    bool	  Terminal has automatic margins
       as    str   (P)	  Start	alternate character set
       bc    str   (o)	  Backspace if not ^H
       bl    str   (P)	  Audible signal (bell)
       bs    bool  (o)	  Terminal can backspace with ^H
       bt    str   (P)	  Back tab
       bw    bool	  le (backspace) wraps from column 0 to	last column
       CC    str	  Terminal settable command character in prototype
       cd    str   (P*)	  Clear	to end of display
       ce    str   (P)	  Clear	to end of line
       ch    str   (NP)	  Set cursor column (horizontal	position)
       cl    str   (P*)	  Clear	screen and home	cursor
       CM    str   (NP)	  Memory-relative cursor addressing
       cm    str   (NP)	  Screen-relative cursor motion
       co    num	  Number of columns in a line (See BUGS	section	below)
       cr    str   (P)	  Carriage return
       cs    str   (NP)	  Change scrolling region (VT100)
       ct    str   (P)	  Clear	all tab	stops
       cv    str   (NP)	  Set cursor row (vertical position)
       da    bool	  Display may be retained above	the screen
       dB    num   (o)	  Milliseconds of bs delay needed (default 0)
       db    bool	  Display may be retained below	the screen
       DC    str   (NP*)  Delete n characters
       dC    num   (o)	  Milliseconds of cr delay needed (default 0)
       dc    str   (P*)	  Delete character
       dF    num   (o)	  Milliseconds of ff delay needed (default 0)
       DL    str   (NP*)  Delete n lines
       dl    str   (P*)	  Delete line
       dm    str	  Enter	delete mode
       dN    num   (o)	  Milliseconds of nl delay needed (default 0)
       DO    str   (NP*)  Move cursor down n lines
       do    str	  Down one line
       ds    str	  Disable status line
       dT    num   (o)	  Milliseconds of horizontal tab delay needed (default 0)
       dV    num   (o)	  Milliseconds of vertical tab delay needed (default 0)
       ec    str   (NP)	  Erase	n characters
       ed    str	  End delete mode
       ei    str	  End insert mode
       eo    bool	  Can erase overstrikes	with a blank
       EP    bool  (o)	  Even parity
       es    bool	  Escape can be	used on	the status line
       ff    str   (P*)	  Hardcopy terminal page eject
       fs    str	  Return from status line
       gn    bool	  Generic line type (e.g. dialup, switch)
       hc    bool	  Hardcopy terminal
       HD    bool  (o)	  Half-duplex
       hd    str	  Half-line down (forward 1/2 linefeed)
       ho    str   (P)	  Home cursor
       hs    bool	  Has extra "status line"
       hu    str	  Half-line up (reverse	1/2 linefeed)
       hz    bool	  Cannot print ~s (Hazeltine)
       i1-i3 str	  Terminal initialization strings (terminfo only)
       IC    str   (NP*)  Insert n blank characters
       ic    str   (P*)	  Insert character
       if    str	  Name of file containing initialization string
       im    str	  Enter	insert mode
       in    bool	  Insert mode distinguishes nulls
       iP    str	  Pathname of program for initialization (terminfo only)
       ip    str   (P*)	  Insert pad after character inserted
       is    str	  Terminal initialization string (termcap only)
       it    num	  Tabs initially every n positions
       K1    str	  Sent by keypad upper left
       K2    str	  Sent by keypad upper right
       K3    str	  Sent by keypad center
       K4    str	  Sent by keypad lower left
       K5    str	  Sent by keypad lower right
       k0-k9 str	  Sent by function keys	0-9
       kA    str	  Sent by insert-line key
       ka    str	  Sent by clear-all-tabs key
       kb    str	  Sent by backspace key
       kC    str	  Sent by clear-screen or erase	key
       kD    str	  Sent by delete-character key
       kd    str	  Sent by down-arrow key
       kE    str	  Sent by clear-to-end-of-line key
       ke    str	  Out of "keypad transmit" mode
       kF    str	  Sent by scroll-forward/down key
       kH    str	  Sent by home-down key
       kh    str	  Sent by home key
       kI    str	  Sent by insert-character or enter-insert-mode	key
       kL    str	  Sent by delete-line key
       kl    str	  Sent by left-arrow key
       kM    str	  Sent by insert key while in insert mode
       km    bool	  Has a	"meta" key (shift, sets	parity bit)
       kN    str	  Sent by next-page key
       kn    num   (o)	  Number of function (k0-k9) keys (default 0)
       ko    str   (o)	  Termcap entries for other non-function keys
       kP    str	  Sent by previous-page	key
       kR    str	  Sent by scroll-backward/up key
       kr    str	  Sent by right-arrow key
       kS    str	  Sent by clear-to-end-of-screen key
       ks    str	  Put terminal in "keypad transmit" mode
       kT    str	  Sent by set-tab key
       kt    str	  Sent by clear-tab key
       ku    str	  Sent by up-arrow key
       l0-l9 str	  Labels on function keys if not "fn"
       LC    bool  (o)	  Lower-case only
       LE    str   (NP)	  Move cursor left n positions
       le    str   (P)	  Move cursor left one position
       li    num	  Number of lines on screen or page (See BUGS section below)
       ll    str	  Last line, first column
       lm    num	  Lines	of memory if > li (0 means varies)
       ma    str   (o)	  Arrow	key map	(used by vi version 2 only)
       mb    str	  Turn on blinking attribute
       md    str	  Turn on bold (extra bright) attribute
       me    str	  Turn off all attributes
       mh    str	  Turn on half-bright attribute
       mi    bool	  Safe to move while in	insert mode
       mk    str	  Turn on blank	attribute (characters invisible)
       ml    str   (o)	  Memory lock on above cursor
       mm    str	  Turn on "meta	mode" (8th bit)
       mo    str	  Turn off "meta mode"
       mp    str	  Turn on protected attribute
       mr    str	  Turn on reverse-video	attibute
       ms    bool	  Safe to move in standout modes
       mu    str   (o)	  Memory unlock	(turn off memory lock)
       nc    bool  (o)	  No correctly-working cr (Datamedia 2500, Hazeltine 2000)
       nd    str	  Non-destructive space	(cursor	right)
       NL    bool  (o)	  \n is	newline, not line feed
       nl    str   (o)	  Newline character if not \n
       ns    bool  (o)	  Terminal is a	CRT but	doesn't	scroll
       nw    str   (P)	  Newline (behaves like	cr followed by do)
       OP    bool  (o)	  Odd parity
       os    bool	  Terminal overstrikes
       pb    num	  Lowest baud where delays are required
       pc    str	  Pad character	(default NUL)
       pf    str	  Turn off the printer
       pk    str	  Program function key n to type string	s (terminfo only)
       pl    str	  Program function key n to execute string s (terminfo only)
       pO    str   (N)	  Turn on the printer for n bytes
       po    str	  Turn on the printer
       ps    str	  Print	contents of the	screen
       pt    bool  (o)	  Has hardware tabs (may need to be set	with is)
       px    str	  Program function key n to transmit string s (terminfo	only)
       r1-r3 str	  Reset	terminal completely to sane modes (terminfo only)
       rc    str   (P)	  Restore cursor to position of	last sc
       rf    str	  Name of file containing reset	codes
       RI    str   (NP)	  Move cursor right n positions
       rp    str   (NP*)  Repeat character c n times
       rs    str	  Reset	terminal completely to sane modes (termcap only)
       sa    str   (NP)	  Define the video attributes
       sc    str   (P)	  Save cursor position
       se    str	  End standout mode
       SF    str   (NP*)  Scroll forward n lines
       sf    str   (P)	  Scroll text up
       sg    num	  Number of garbage chars left by so or	se (default 0)
       so    str	  Begin	standout mode
       SR    str   (NP*)  Scroll backward n lines
       sr    str   (P)	  Scroll text down
       st    str	  Set a	tab in all rows, current column
       ta    str   (P)	  Tab to next 8-position hardware tab stop
       tc    str	  Entry	of similar terminal - must be last
       te    str	  String to end	programs that use termcap
       ti    str	  String to begin programs that	use termcap
       ts    str   (N)	  Go to	status line, column n
       UC    bool  (o)	  Upper-case only
       uc    str	  Underscore one character and move past it
       ue    str	  End underscore mode
       ug    num	  Number of garbage chars left by us or	ue (default 0)
       ul    bool	  Underline character overstrikes
       UP    str   (NP*)  Move cursor up n lines
       up    str	  Upline (cursor up)
       us    str	  Start	underscore mode
       vb    str	  Visible bell (must not move cursor)
       ve    str	  Make cursor appear normal (undo vs/vi)
       vi    str	  Make cursor invisible
       vs    str	  Make cursor very visible
       vt    num	  Virtual terminal number (not supported on all	systems)
       wi    str   (N)	  Set current window
       ws    num	  Number of columns in status line
       xb    bool	  Beehive (f1=ESC, f2=^C)
       xn    bool	  Newline ignored after	80 cols	(Concept)
       xo    bool	  Terminal uses	xoff/xon (DC3/DC1) handshaking
       xr    bool  (o)	  Return acts like ce cr nl (Delta Data)
       xs    bool	  Standout not erased by overwriting (Hewlett-Packard)
       xt    bool	  Tabs ruin, magic so char (Teleray 1061)
       xx    bool  (o)	  Tektronix 4025 insert-line

       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.

       ca|concept100|c100|concept|c104|concept100-4p|HDS Concept-100:\
	       :al=3*\E^R:am:bl=^G:cd=16*\E^C:ce=16\E^U:cl=2*^L:cm=\Ea%+ %+ :\
	       :co#80:.cr=9^M:db:dc=16\E^A:dl=3*\E^B:do=^J:ei=\E\200:eo:im=\E^P:in:\
	       :ip=16*:is=\EU\Ef\E7\E5\E8\El\ENH\EK\E\200\Eo&\200\Eo\47\E:k1=\E5:\
	       :k2=\E6:k3=\E7:kb=^h:kd=\E<:ke=\Ex:kh=\E?:kl=\E>:kr=\E=:ks=\EX:\
	       :ku=\E;:le=^H:li#24:mb=\EC:me=\EN\200:mh=\EE:mi:mk=\EH:mp=\EI:\
	       :mr=\ED:nd=\E=:pb#9600:rp=0.2*\Er%.%+ :se=\Ed\Ee:sf=^J:so=\EE\ED:\
	       :.ta=8\t:te=\Ev	  \200\200\200\200\200\200\Ep\r\n:\
	       :ti=\EU\Ev  8p\Ep\r:ue=\Eg:ul:up=\E;:us=\EG:\
	       :vb=\Ek\200\200\200\200\200\200\200\200\200\200\200\200\200\200\EK:\
	       :ve=\Ew:vs=\EW:vt#8:xn:\
	       :bs:cr=^M:dC#9:dT#8:nl=^J:ta=^I:pt:

       Entries may continue onto multiple lines	by giving  a  \	 as  the  last
       character  of  a	line, and empty	fields may be included for readability
       (here between the last field on a line  and  the	 first	field  on  the
       next).  Comments	may be included	on lines beginning with	"#".

       Types of	Capabilities

       Capabilities in termcap are of three types: Boolean capabilities, which
       indicate	particular features that the terminal has;  numeric  capabili-
       ties,  giving  the size of the display or the size of other attributes;
       and string capabilities,	which give character  sequences	 that  can  be
       used  to	perform	particular terminal operations.	 All capabilities have
       two-letter codes.  For instance,	the fact that the  Concept  has	 auto-
       matic margins (i.e., an automatic return	and linefeed when the end of a
       line is reached)	is indicated by	the Boolean capability am.  Hence  the
       description of the Concept includes am.

       Numeric	capabilities are followed by the character `#' then the	value.
       In the example above co,	which indicates	the number of columns the dis-
       play 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-letter code, an `=', then	a string  end-
       ing  at	the  next  following  `:'.  A delay in milliseconds may	appear
       after the `=' in	such a capability, which causes	padding	characters  to
       be  supplied by tputs after the remainder of the	string is sent to pro-
       vide this delay.	 The delay can be either a number, e.g.	  `20',	 or  a
       number  followed	by an `*', i.e., `3*'.	An `*' indicates that the pad-
       ding required is	proportional to	the number of lines  affected  by  the
       operation,  and	the  amount  given  is	the  per-affected-line padding
       required.  (In the case of insert-character, the	factor	is  still  the
       number  of  lines affected; this	is always 1 unless the terminal	has in
       and the software	uses it.)  When	an `*' is specified, it	 is  sometimes
       useful to give a	delay of the form `3.5'	to specify a delay per line to
       tenths of milliseconds.	(Only one decimal place	is allowed.)

       A number	of escape sequences are	provided in the	string-valued capabil-
       ities for easy encoding of control characters there.  \E	maps to	an ESC
       character, ^X maps to a	control-X  for	any  appropriate  X,  and  the
       sequences  \n  \r \t \b \f map to linefeed, return, tab,	backspace, and
       formfeed, respectively.	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 NUL character
       in a string capability it must be encoded as \200.  (The	routines  that
       deal  with  termcap use C strings and strip the high bits of the	output
       very late, so that a \200 comes out as a	\000 would.)

       Sometimes individual capabilities must be commented out.	 To  do	 this,
       put a period before the capability name.	 For example, see the first cr
       and ta in the example above.

       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 vi 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
       vi.  To easily test a new terminal description you are working  on  you
       can  put	 it  in	your home directory in a file called .termcap and pro-
       grams will look there before looking in /etc/termcap.  You can also set
       the  environment	variable TERMPATH to a list of absolute	file pathnames
       (separated by spaces or colons),	one of which contains the  description
       you  are	working	on, and	programs will search them in the order listed,
       and nowhere else.  See termcap(3X).  The	TERMCAP	 environment  variable
       is  usually set to the termcap entry itself to avoid reading files when
       starting	up a program.

       To get the padding for insert-line right	(if the	terminal  manufacturer
       did not document	it), a severe test is to use vi	to edit	/etc/passwd at
       9600 baud, delete roughly 16 lines from the middle of the screen,  then
       hit  the	`u' key	several	times quickly.	If the display messes up, more
       padding is usually needed.  A similar test can be used for insert-char-
       acter.

       Basic Capabilities

       The  number  of	columns	on each	line of	the display is given by	the co
       numeric capability.  If the display is a	CRT, then the number of	 lines
       on  the	screen	is  given  by the li capability.  If the display wraps
       around to the beginning of the next line	when the  cursor  reaches  the
       right  margin,  then it should have the am capability.  If the terminal
       can clear its screen, the code to do this is given  by  the  cl	string
       capability.   If	 the  terminal	overstrikes  (rather than clearing the
       position	when a character is overwritten), it should have the os	 capa-
       bility.	 If  the  terminal  is	a printing terminal, with no soft copy
       unit, give it both hc and os.  (os applies to storage scope  terminals,
       such as the Tektronix 4010 series, as well as to	hard copy and APL ter-
       minals.)	 If there is a code to move the	cursor to the left edge	of the
       current	row, give this as cr.  (Normally this will be carriage-return,
       ^M.)  If	there is a code	to produce  an	audible	 signal	 (bell,	 beep,
       etc.), give this	as bl.

       If  there is a code (such as backspace) to move the cursor one position
       to the left, that capability should be given as le.   Similarly,	 codes
       to  move	 to the	right, up, and down should be given as nd, up, and do,
       respectively.  These local cursor motions should	 not  alter  the  text
       they  pass  over; for example, you would	not normally use "nd= "	unless
       the terminal has	the os capability, because the space would  erase  the
       character moved over.

       A very important	point here is that the local cursor motions encoded in
       termcap have undefined behavior at the left and top edges of a CRT dis-
       play.  Programs should never attempt to backspace around	the left edge,
       unless bw is given, and never attempt to	go up off the top using	 local
       cursor motions.

       In order	to scroll text up, a program goes to the bottom	left corner of
       the screen and sends the	sf (index) string.  To	scroll	text  down,  a
       program	goes  to  the  top  left corner	of the screen and sends	the sr
       (reverse	index) string.	The strings sf and sr have undefined  behavior
       when not	on their respective corners of the screen.  Parameterized ver-
       sions of	the scrolling sequences	are SF and SR,	which  have  the  same
       semantics  as  sf and sr	except that they take one parameter and	scroll
       that many lines.	 They also  have  undefined  behavior  except  at  the
       appropriate corner of the screen.

       The  am capability tells	whether	the cursor sticks at the right edge of
       the screen when text is output there, but  this	does  not  necessarily
       apply  to  nd  from  the	last column.  Leftward local motion is defined
       from the	left edge only when bw is given; then an le from the left edge
       will  move  to  the right edge of the previous row.  This is useful for
       drawing a box around the	edge of	the screen, for	example.  If the  ter-
       minal  has switch-selectable automatic margins, the termcap description
       usually assumes that this feature is on,	i.e., am.  If the terminal has
       a command that moves to the first column	of the next line, that command
       can be given as nw (newline).  It is permissible	for this to clear  the
       remainder  of  the  current  line, so if	the terminal has no correctly-
       working CR and LF it may	still be possible to craft a working nw	out of
       one or both of them.

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

	       T3|tty33|33|tty|Teletype	model 33:\
		       :bl=^G:co#72:cr=^M:do=^J:hc:os:

       and the Lear Siegler ADM-3 is described as

	       l3|adm3|3|LSI ADM-3:\
		       :am:bl=^G:cl=^Z:co#80:cr=^M:do=^J:le=^H:li#24:sf=^J:

       Parameterized Strings

       Cursor addressing and other strings requiring parameters	are  described
       by  a  parameterized string capability, with printf(3S)-like escapes %x
       in it, while other characters are passed	through	unchanged.  For	 exam-
       ple, to address the cursor the cm capability is given, using two	param-
       eters: the row and column to move to.  (Rows and	columns	 are  numbered
       from  zero and refer to the physical screen visible to the user,	not to
       any unseen memory.  If the terminal has memory-relative cursor address-
       ing, that can be	indicated by an	analogous CM capability.)

       The % encodings have the	following meanings:

	    %%	 output	`%'
	    %d	 output	value as in printf %d
	    %2	 output	value as in printf %2d
	    %3	 output	value as in printf %3d
	    %.	 output	value as in printf %c
	    %+x	 add x to value, then do %.
	    %>xy if value > x then add y, no output
	    %r	 reverse order of two parameters, no output
	    %i	 increment by one, no output
	    %n	 exclusive-or all parameters with 0140 (Datamedia 2500)
	    %B	 BCD (16*(value/10)) + (value%10), no output
	    %D	 Reverse coding	(value - 2*(value%16)),	no output (Delta Data)

       Consider	 the  Hewlett-Packard  2645, 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 row and column coordinates is	reversed here and that
       the row and column are sent as two-digit	integers.  Thus	its  cm	 capa-
       bility is "cm=6\E&%r%2c%2Y".

       The  Datamedia  2500  needs  the	current	row and	column sent encoded in
       binary using "%.".   Terminals  that  use  "%."	need  to  be  able  to
       backspace  the  cursor  (le)  and to move the cursor up one line	on the
       screen (up).  This is necessary because it is not always	safe to	trans-
       mit  \n,	 ^D,  and \r, as the system may	change or discard them.	 (Pro-
       grams using termcap must	set  terminal  modes  so  that	tabs  are  not
       expanded,  so  \t  is safe to send.  This turns out to be essential for
       the Ann Arbor 4080.)

       A final example is the Lear Siegler ADM-3a, which offsets row and  col-
       umn by a	blank character, thus "cm=\E=%+	%+ ".

       Row or column absolute cursor addressing	can be given as	single parame-
       ter capabilities	ch (horizontal position	 absolute)  and	 cv  (vertical
       position	 absolute).  Sometimes these are shorter than the more general
       two-parameter sequence (as with the Hewlett-Packard 2645)  and  can  be
       used  in	 preference  to	 cm.  If there are parameterized local motions
       (e.g., move n positions to the right) these can be given	as DO, LE, RI,
       and  UP	with a single parameter	indicating how many positions to move.
       These are primarily useful if the terminal does not have	 cm,  such  as
       the Tektronix 4025.

       Cursor Motions

       If  the	terminal  has a	fast way to home the cursor (to	the very upper
       left corner of the screen), 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  a  program
       should  never  do  this itself (unless ll does),	because	it can make no
       assumption about	the effect of moving up	from the home position.	  Note
       that  the home position is the same as cursor address (0,0): to the top
       left corner of the  screen,  not	 of  memory.   (Therefore,  the	 "\EH"
       sequence	on Hewlett-Packard terminals cannot be used for	ho.)

       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, this should be given as cd.  cd must only	be  invoked  from  the
       first  column  of a line.  (Therefore, it can be	simulated by a request
       to delete a large number	of lines, if a true cd is not available.)

       Insert/Delete Line

       If the terminal can open	a new blank line before	 the  line  containing
       the  cursor, this should	be given as al;	this must be invoked only from
       the first position of a line.  The cursor must then appear at the  left
       of  the newly blank line.  If the terminal can delete the line that the
       cursor is on, this should be given as dl; this must only	be  used  from
       the  first  position  on	the line to be deleted.	 Versions of al	and dl
       which take a single parameter and insert	or delete that many lines  can
       be given	as AL and DL.  If the terminal has a settable scrolling	region
       (like the VT100), the command to	set this can be	described with the  cs
       capability, which takes two parameters: the top and bottom lines	of the
       scrolling region.  The cursor position is, alas,	undefined after	 using
       this  command.	It  is	possible to get	the effect of insert or	delete
       line using this command -- the sc and rc	(save and restore cursor) com-
       mands  are  also	 useful.   Inserting lines at the top or bottom	of the
       screen can also be done using sr	or sf on many terminals	without	a true
       insert/delete  line,  and  is often faster even on terminals with those
       features.

       If the terminal has the ability to define a window as  part  of	memory
       which  all  commands  affect,  it  should be given as the parameterized
       string wi.  The four parameters are the starting	and  ending  lines  in
       memory  and  the	 starting and ending columns in	memory,	in that	order.
       (This  terminfo	capability  is	described  for	completeness.	It  is
       unlikely	that any termcap-using program will support it.)

       If the terminal can retain display memory above the screen, then	the da
       capability should be given; if display memory can  be  retained	below,
       then  db	 should	 be  given.   These  indicate  that deleting a line or
       scrolling may bring non-blank lines up from  below  or  that  scrolling
       back with sr may	bring down non-blank lines.

       Insert/Delete Character

       There  are  two	basic  kinds  of intelligent terminals with respect to
       insert/delete character that 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	deter-
       mine  the  kind of terminal you have by clearing	the screen 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 current  line  and
       onto  the next as you insert, then you have the second type of terminal
       and should give the capability in,  which  stands  for  "insert	null".
       While these are two logically separate attributes (one line vs.	multi-
       line insert mode, and special treatment of  untyped  spaces),  we  have
       seen no terminals whose insert mode cannot be described with the	single
       attribute.

       Termcap can describe both terminals that	have an	insert mode and	termi-
       nals  that  send	a simple sequence to open a blank position on the cur-
       rent line.  Give	as im the sequence to get into insert mode.   Give  as
       ei the sequence to leave	insert mode.  Now give as ic any sequence that
       needs to	be sent	just before each character to be inserted.  Most  ter-
       minals  with  a true insert mode	will not give ic; terminals that use a
       sequence	to open	a screen position should give it here.	(If your  ter-
       minal  has  both, insert	mode is	usually	preferable to ic.  Do not give
       both unless the terminal	actually requires both to be used in  combina-
       tion.)  If post-insert padding is needed, give this as a	number of mil-
       liseconds in ip (a string option).  Any other sequence that may need to
       be  sent	after insertion	of a single character can also be given	in ip.
       If your terminal	needs to be placed into	an `insert mode' and  needs  a
       special	code preceding each inserted character,	then both im/ei	and ic
       can be given, and both will be  used.   The  IC	capability,  with  one
       parameter n, will repeat	the effects of ic n times.

       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
       Datamedia's) must not have mi because of	 the  way  their  insert  mode
       works.

       Finally,	 you  can specify dc to	delete a single	character, DC with one
       parameter n to delete n characters, and delete mode by giving dm	and ed
       to  enter and exit delete mode (which is	any mode the terminal needs to
       be placed in for	dc to work).

       Highlighting, Underlining, and Visible Bells

       If your terminal	has one	or more	kinds of display attributes, these can
       be  represented	in  a number of	different ways.	 You should choose one
       display form as standout	mode, representing a good high-contrast, easy-
       on-the-eyes  format for highlighting error messages and other attention
       getters.	 (If you have a	choice,	 reverse  video	 plus  half-bright  is
       good,  or reverse video alone.)	The sequences to enter and exit	stand-
       out mode	are given as so	and se,	respectively.  If the code  to	change
       into  or	 out  of  standout mode	leaves one or even two blank spaces or
       garbage characters on the screen, as the	TVI 912	and Teleray  1061  do,
       then sg should be given to tell how many	characters are left.

       Codes  to  begin	underlining and	end underlining	can be given as	us and
       ue, respectively.  Underline mode change	garbage	is  specified  by  ug,
       similar	to  sg.	  If  the terminal has a code to underline the current
       character and move the cursor one position to the right,	 such  as  the
       Microterm Mime, this can	be given as uc.

       Other  capabilities  to	enter  various	highlighting  modes include mb
       (blinking), md (bold or extra bright),  mh  (dim	 or  half-bright),  mk
       (blanking  or  invisible	 text),	mp (protected),	mr (reverse video), me
       (turn off all attribute	modes),	 as  (enter  alternate	character  set
       mode),  and  ae (exit alternate character set mode).  Turning on	any of
       these modes singly may or may not turn off other	modes.

       If there	is a sequence to set  arbitrary	 combinations  of  mode,  this
       should  be  given  as  sa  (set attributes), taking 9 parameters.  Each
       parameter is either 0 or	1, as the corresponding	attributes  is	on  or
       off.   The  9  parameters  are, in order: standout, underline, reverse,
       blink, dim, bold, blank,	protect, and alternate character set.  Not all
       modes  need  be	supported  by  sa,  only those for which corresponding
       attribute commands exist.  (It is unlikely that a termcap-using program
       will  support  this capability, which is	defined	for compatibility with
       terminfo.)

       Terminals with the "magic cookie" glitches (sg  and  ug),  rather  than
       maintaining  extra  attribute  bits  for	 each  character cell, instead
       deposit special "cookies", or "garbage characters", when	 they  receive
       mode-setting sequences, which affect the	display	algorithm.

       Some  terminals,	 such as the Hewlett-Packard 2621, automatically leave
       standout	mode when they move to a  new  line  or	 when  the  cursor  is
       addressed.   Programs  using standout mode should exit standout mode on
       such terminals before moving the	cursor or sending a newline.  On  ter-
       minals where this is not	a problem, the ms capability should be present
       to say that this	overhead is unnecessary.

       If the terminal has a way of flashing the screen	to indicate  an	 error
       quietly (a bell replacement), this can be given as vb; it must not move
       the cursor.

       If the cursor needs to be made more visible than	normal when it is  not
       on  the	bottom	line (to change, for example, a	non-blinking underline
       into an easier-to-find block or blinking	underline), give this sequence
       as vs.  If there	is a way to make the cursor completely invisible, give
       that as vi.  The	capability ve, which undoes the	 effects  of  both  of
       these modes, should also	be given.

       If your terminal	correctly displays underlined characters (with no spe-
       cial codes needed) even though it does not overstrike, then you	should
       give the	capability ul.	If overstrikes are erasable with a blank, 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  mode	 (this
       applies,	 for example, to the unshifted Hewlett-Packard 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.
       The  codes  transmitted	by certain other special keys can be given: kH
       (home down), kb (backspace), ka (clear all tabs),  kt  (clear  the  tab
       stop  in	 this  column),	kC (clear screen or erase), kD (delete charac-
       ter), kL	(delete	line), kM (exit	insert mode),  kE  (clear  to  end  of
       line),  kS  (clear  to  end  of	screen), kI (insert character or enter
       insert mode), kA	(insert	line), kN (next	page), kP (previous page),  kF
       (scroll	forward/down), kR (scroll backward/up),	and kT (set a tab stop
       in this column).	 In addition, if the keypad has	a 3 by 3 array of keys
       including the four arrow	keys, then the other five keys can be given as
       K1, K2, K3, K4, and K5.	These keys are useful when the effects of a  3
       by  3  directional pad are needed.  The obsolete	ko capability formerly
       used to describe	"other"	function keys has been	completely  supplanted
       by the above capabilities.

       The ma entry is also used to indicate arrow keys	on terminals that have
       single-character	arrow keys.  It	is obsolete but	still in use  in  ver-
       sion 2 of vi which must be run on some minicomputers due	to memory lim-
       itations.  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, and the second character	is the	corre-
       sponding	 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	  have
       "ma=^Hh^Kj^Zk^Xl"  indicating arrow keys	left (^H), down	(^K), up (^Z),
       and right (^X).	(There is no home key on the Mime.)

       Tabs and	Initialization

       If the terminal needs to	be in a	special	mode when  running  a  program
       that uses these capabilities, 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  screen-sized  window must be fixed into the display for
       cursor addressing to work properly.  This is also  used	for  the  Tek-
       tronix  4025, where ti sets the command character to be the one used by
       termcap.

       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 set the terminal  into  modes  consistent
       with  the  rest	of the termcap description.  They are normally sent to
       the terminal by the tset	program	each time the user logs	in.  They will
       be  printed  in	the following order: is; setting tabs using ct and st;
       and finally if.	(Terminfo uses i1-i2 instead of	is and runs  the  pro-
       gram  iP	 and  prints  i3  after	the other initializations.)  A pair of
       sequences that does a harder reset from a totally unknown state can  be
       analogously  given as rs	and if.	 These strings are output by the reset
       program,	which is used when the terminal	 gets  into  a	wedged	state.
       (Terminfo  uses	r1-r3 instead of rs.)  Commands	are normally placed in
       rs and rf only if they produce annoying effects on the screen  and  are
       not  necessary  when  logging  in.  For example,	the command to set the
       VT100 into 80-column mode would normally	be part	of is, but  it	causes
       an  annoying  glitch of the screen and is not normally needed since the
       terminal	is usually already in 80-column	mode.

       If the terminal has hardware tabs, the command to advance to  the  next
       tab  stop  can  be given	as ta (usually ^I).  A "backtab" command which
       moves leftward to the previous tab stop can be given as bt.  By conven-
       tion,  if  the  terminal	driver modes indicate that tab stops are being
       expanded	by the computer	rather than being sent to the  terminal,  pro-
       grams  should not use ta	or bt even if they are present,	since the user
       may not have the	tab stops properly set.	 If the	terminal has  hardware
       tabs that are initially set every n positions when the terminal is pow-
       ered up,	then the numeric parameter it is given,	showing	the number  of
       positions between tab stops.  This is normally used by the tset command
       to determine whether to set the driver mode for hardware	tab expansion,
       and  whether  to	set the	tab stops.  If the terminal has	tab stops that
       can be saved in nonvolatile memory, the termcap description can	assume
       that they are properly set.

       If  there are commands to set and clear tab stops, they can be given as
       ct (clear all tab stops)	and st (set a tab stop in the  current	column
       of  every  row).	  If a more complex sequence is	needed to set the tabs
       than can	be described by	this, the sequence can be placed in is or  if.

       Delays

       Certain capabilities control padding in the terminal driver.  These are
       primarily needed	by hardcopy terminals and are used by the tset program
       to  set	terminal  driver  modes	appropriately.	Delays embedded	in the
       capabilities cr,	sf, le,	ff, and	ta will	cause  the  appropriate	 delay
       bits  to	 be  set in the	terminal driver.  If pb	(padding baud rate) is
       given, these values can be ignored at baud rates	below the value	of pb.
       For  4.2BSD  tset, the delays are given as numeric capabilities dC, dN,
       dB, dF, and dT instead.

       Miscellaneous

       If the terminal requires	other than a NUL (zero)	character  as  a  pad,
       this  can be given as pc.  Only the first character of the pc string is
       used.

       If the terminal has commands to save and	restore	the  position  of  the
       cursor, give them as sc and rc.

       If the terminal has an extra "status line" that is not normally used by
       software, this fact can be indicated.  If the status line is viewed  as
       an  extra  line below the bottom	line, then the capability hs should be
       given.  Special strings to go to	a position in the status line  and  to
       return  from the	status line can	be given as ts and fs.	(fs must leave
       the cursor position in the same place that it was before	ts.  If	neces-
       sary,  the  sc  and rc strings can be included in ts and	fs to get this
       effect.)	 The capability	ts takes one parameter,	which  is  the	column
       number  of  the	status	line  to  which	the cursor is to be moved.  If
       escape sequences	and other special commands such	as tab work  while  in
       the status line,	the flag es can	be given.  A string that turns off the
       status line (or otherwise erases	its contents) should be	given  as  ds.
       The status line is normally assumed to be the same width	as the rest of
       the screen, i.e., co.  If the status line is a different	width  (possi-
       bly  because  the terminal does not allow an entire line	to be loaded),
       then its	width in columns can be	indicated with the  numeric  parameter
       ws.

       If  the terminal	can move up or down half a line, this can be indicated
       with hu (half-line up) and hd (half-line	down).	This is	primarily use-
       ful  for	superscripts and subscripts on hardcopy	terminals.  If a hard-
       copy terminal can eject to the next page	(form feed), give this	as  ff
       (usually	^L).

       If  there  is  a	 command to repeat a given character a given number of
       times (to save time transmitting	a large	number	of  identical  charac-
       ters),  this  can  be  indicated	with the parameterized string rp.  The
       first parameter is the character	to be repeated and the second  is  the
       number  of  times  to  repeat  it.  (This is a terminfo feature that is
       unlikely	to be supported	by a program that uses termcap.)

       If the terminal has a settable command character, such as the Tektronix
       4025,  this can be indicated with CC.  A	prototype command character is
       chosen which is used in all capabilities.  This character is  given  in
       the  CC	capability  to	identify it.  The following convention is sup-
       ported on some UNIX systems: The	environment is to be searched for a CC
       variable,  and if found,	all occurrences	of the prototype character are
       replaced	by the character in the	environment variable.  This use	of the
       CC  environment	variable  is  a	 very  bad  idea, as it	conflicts with
       make(1).

       Terminal	descriptions that do not represent a specific  kind  of	 known
       terminal,  such	as  switch, dialup, patch, and network,	should include
       the gn (generic)	capability so that programs can	complain that they  do
       not  know how to	talk to	the terminal.  (This capability	does not apply
       to virtual terminal descriptions	for which  the	escape	sequences  are
       known.)

       If  the	terminal uses xoff/xon (DC3/DC1) handshaking for flow control,
       give xo.	 Padding information should still be included so that routines
       can  make  better decisions about costs,	but actual pad characters will
       not be transmitted.

       If the terminal has a "meta key"	which acts as a	shift key, setting the
       8th  bit	 of any	character transmitted, then this fact can be indicated
       with km.	 Otherwise, software will assume that the 8th  bit  is	parity
       and  it	will  usually be cleared.  If strings exist to turn this "meta
       mode" on	and off, they can be given as mm and mo.

       If the terminal has more	lines of memory	than will fit on the screen at
       once,  the  number  of  lines  of  memory can be	indicated with lm.  An
       explicit	value of 0 indicates that the number of	lines  is  not	fixed,
       but that	there is still more memory than	fits on	the screen.

       If  the	terminal  is one of those supported by the UNIX	system virtual
       terminal	protocol, the terminal number can be given as vt.

       Media copy strings which	control	an auxiliary printer connected to  the
       terminal	can be given as	ps: print the contents of the screen; pf: turn
       off the printer;	and po:	turn on	the printer.  When the printer is  on,
       all text	sent to	the terminal will be sent to the printer.  It is unde-
       fined whether the text is also displayed	on the	terminal  screen  when
       the  printer  is	on.  A variation pO takes one parameter	and leaves the
       printer on for as many characters as the	value of the  parameter,  then
       turns the printer off.  The parameter should not	exceed 255.  All text,
       including pf, is	transparently passed to	the printer  while  pO	is  in
       effect.

       Strings	to program function keys can be	given as pk, pl, and px.  Each
       of these	strings	takes two parameters: the function key number to  pro-
       gram  (from  0  to  9) and the string to	program	it with.  Function key
       numbers out of this range may program undefined	keys  in  a  terminal-
       dependent  manner.   The	differences among the capabilities are that pk
       causes pressing the given key to	be the same as	the  user  typing  the
       given  string;  pl  causes the string to	be executed by the terminal in
       local mode; and px causes the string to be transmitted to the computer.
       Unfortunately,  due  to	lack  of a definition for string parameters in
       termcap,	only terminfo supports these capabilities.

       Glitches	and Braindamage

       Hazeltine terminals, which do not allow `~' characters to be displayed,
       should indicate hz.

       The  nc	capability,  now obsolete, formerly indicated Datamedia	termi-
       nals, which echo	\r \n for carriage  return  then  ignore  a  following
       linefeed.

       Terminals  that ignore a	linefeed immediately after an am wrap, such as
       the Concept, should indicate xn.

       If ce is	required to get	rid of standout	 (instead  of  merely  writing
       normal text on top of it), xs should be given.

       Teleray terminals, where	tabs turn all characters moved over to blanks,
       should indicate xt (destructive tabs).  This glitch is  also  taken  to
       mean  that it is	not possible to	position the cursor on top of a	"magic
       cookie",	and that to erase standout mode	it is necessary	to use	delete
       and insert line.

       The  Beehive Superbee, which is unable to correctly transmit the	ESC or
       ^C characters, has xb, indicating that the "f1" key is used for ESC and
       "f2"  for  ^C.  (Only certain Superbees have this problem, depending on
       the ROM.)

       Other specific terminal problems	may be corrected by adding more	 capa-
       bilities	of the form xx.

       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 entries  must  not	exceed
       1024.   The capabilities	given before tc	override those in the terminal
       type invoked by tc.  A capability can be	canceled by placing xx@	to the
       left  of	 the  tc invocation, where xx is the capability.  For example,
       the entry

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

       defines a "2621-nl" that	does not have the ks or	ke capabilities, 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	 pref-
       erences.

AUTHOR
       William Joy
       Mark Horton added underlining and keypad	support

FILES
       /etc/termcap   file containing terminal descriptions

SEE ALSO
       ex(1),  more(1),	 tset(1),  ul(1), vi(1), curses(3X), printf(3S), term-
       cap(3X),	term(7)

CAVEATS	AND BUGS
       Note: termcap was replaced by terminfo in UNIX System  V	 Release  2.0.
       The  transition	will be	relatively painless if capabilities flagged as
       "obsolete" are avoided.

       Lines and columns are now stored	by the kernel as well as in the	 term-
       cap entry.  Most	programs now use the kernel information	primarily; the
       information in this file	is used	only if	the kernel does	not  have  any
       information.

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

       Not all programs	support	all entries.

3rd Berkeley Distribution	 June 23, 1990			    TERMCAP(5)

NAME | SYNOPSIS | DESCRIPTION | CAPABILITIES | AUTHOR | FILES | SEE ALSO | CAVEATS AND BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=termcap&sektion=5&manpath=4.3BSD+Reno>

home | help