.\"	$NetBSD: capfile.5,v 1.3.18.1 2019/09/02 16:39:21 martin Exp $
.\"
.\" Copyright (c) 2012 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Roy Marples.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd March 27, 2012
.Dt CAPFILE 5
.Os
.Sh NAME
.Nm capfile
.Nd capability database files
.Sh DESCRIPTION
.Nm
descibes the format of capability database files,
made popular by
.Nm termcap .
.Nm termcap
itself has been superseded by
.Xr terminfo 5 ,
which contains equivalent
.Nm termcap
capabilities,
and this page exists solely to document the
.Nm termcap
format as it is still used by other programs such as
.Xr rtadvd.conf 5 .
.Pp
Entries in
.Nm
consist of a number of `:'-separated fields.
The first entry for each record gives the names that are known for the
record, separated by `|' characters.
By convention, the last name is usually a comment and is not intended as a
lookup tag.
The entry must be terminated by the `:' character.
.Ss A Sample Entry
The following entry describes the Teletype model 33.
.Pp
.Bd -literal
T3\||\|tty33\||\|33\||\|tty\||\|Teletype model 33:\e
	:bl=^G:co#72:.cr=9^M:cr=^M:do=^J:hc:os:am@:
.Ed
.Pp
Entries may continue onto multiple lines by giving a \e 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
.Dq # .
.Ss Types of Capabilities
Capabilities in
.Nm
are of three types: Boolean capabilities,
numeric capabilities,
and string capabilities.
.Pp
Boolean capabilities are just the name, to indicate the ability is present.
.Pp
Numeric capabilities are followed by the character `#' then the value.
In the example above
.Sy \&co
gives the value `72'.
.Pp
String capabilities are followed by the character `=' and then the string.
In the example above
.Sy \&bl
gives the value `^G'.
.Pp
Sometimes individual capabilities must be commented out.
To do this, put a period (`.') before the capability name.
For example, see the first
.Sy \&cr
in the example above.
.Pp
Sometimes individual capabilities must be marked as absent.
To do this, put a @ after the capability name.
For example, see the last
.Sy \&am
in the example above.
This is only useful when merging entries.
See the tc=name discussion below for more details.
.Ss Encoding
Numeric capability values may be given in one of three numeric bases.
If the number starts with either
.Ql 0x
or
.Ql 0X
it is interpreted as a hexadecimal number (both upper and lower case a-f
may be used to denote the extended hexadecimal digits).
Otherwise, if the number starts with a
.Ql 0
it is interpreted as an octal number.
Otherwise the number is interpreted as a decimal number.
.Pp
String capability values may contain any character.
Non-printable
.Dv ASCII
codes, new lines, and colons may be conveniently represented by the use
of escape sequences:
.Bl -column "\eX,X\eX" "(ASCII octal nnn)"
.It ^X	('\fIX\fP' & 037)	control-\fIX\fP
.It \eb, \eB	(ASCII 010)	backspace
.It \et, \eT	(ASCII 011)	tab
.It \en, \eN	(ASCII 012)	line feed (newline)
.It \ef, \eF	(ASCII 014)	form feed
.It \er, \eR	(ASCII 015)	carriage return
.It \ee, \eE	(ASCII 027)	escape
.It \ec, \eC	(:)	colon
.It \e\e	(\e\|)	back slash
.It \e^	(^)	caret
.It \e\fInnn\fP	(ASCII octal \fInnn\fP)
.El
.Pp
A
.Sq \e
followed by up to three octal digits directly specifies
the numeric code for a character.
The use of
.Tn ASCII
.Dv NUL Ns s ,
while easily
encoded, causes all sorts of problems and must be used with care since
.Dv NUL Ns s
are typically used to denote the end of strings; many applications
use
.Sq \e200
to represent a
.Dv NUL .
.Pp
A special capability,
.Qq tc=name ,
is used to indicate that the record specified by
.Fa name
should be substituted for the
.Qq tc
capability.
.Qq tc
capabilities may interpolate records which also contain
.Qq tc
capabilities and more than one
.Qq tc
capability may be used in a record.
A
.Qq tc
expansion scope (i.e. where the argument is searched for) contains the
file in which the
.Qq tc
is declared and all subsequent files in the file array.
.Sh SEE ALSO
.Xr cgetcap 3 ,
.Xr termcap 3 ,
.Xr terminfo 5
.Sh HISTORY
.Nm termcap
described the capabilities of terminals, used by programs such as
.Xr vi 1
and
.Xr hack 6 .
These programs still use
.Nm termcap
today, but their capability requests are mapped onto
.Xr terminfo 5
ones instead.
As such, the termcap database file is no longer shipped with
.Nx .
.Sh AUTHORS
.An Roy Marples Aq Mt roy@NetBSD.org