1.\" $NetBSD: capfile.5,v 1.5 2020/08/23 20:23:56 tpaul Exp $ 2.\" 3.\" Copyright (c) 2012 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Roy Marples. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd March 27, 2012 31.Dt CAPFILE 5 32.Os 33.Sh NAME 34.Nm capfile 35.Nd capability database files 36.Sh DESCRIPTION 37.Nm 38describes the format of capability database files, 39made popular by 40.Nm termcap . 41.Nm termcap 42itself has been superseded by 43.Xr terminfo 5 , 44which contains equivalent 45.Nm termcap 46capabilities, 47and this page exists solely to document the 48.Nm termcap 49format as it is still used by other programs such as 50.Xr rtadvd.conf 5 . 51.Pp 52Entries in 53.Nm 54consist of a number of `:'-separated fields. 55The first entry for each record gives the names that are known for the 56record, separated by `|' characters. 57By convention, the last name is usually a comment and is not intended as a 58lookup tag. 59The entry must be terminated by the `:' character. 60.Ss A Sample Entry 61The following entry describes the Teletype model 33. 62.Pp 63.Bd -literal 64T3\||\|tty33\||\|33\||\|tty\||\|Teletype model 33:\e 65 :bl=^G:co#72:.cr=9^M:cr=^M:do=^J:hc:os:am@: 66.Ed 67.Pp 68Entries may continue onto multiple lines by giving a \e as the last 69character of a line, and empty fields 70may be included for readability (here between the last field on a line 71and the first field on the next). 72Comments may be included on lines beginning with 73.Dq # . 74.Ss Types of Capabilities 75Capabilities in 76.Nm 77are of three types: Boolean capabilities, 78numeric capabilities, 79and string capabilities. 80.Pp 81Boolean capabilities are just the name, to indicate the ability is present. 82.Pp 83Numeric capabilities are followed by the character `#' then the value. 84In the example above 85.Sy \&co 86gives the value `72'. 87.Pp 88String capabilities are followed by the character `=' and then the string. 89In the example above 90.Sy \&bl 91gives the value `^G'. 92.Pp 93Sometimes individual capabilities must be commented out. 94To do this, put a period (`.') before the capability name. 95For example, see the first 96.Sy \&cr 97in the example above. 98.Pp 99Sometimes individual capabilities must be marked as absent. 100To do this, put a @ after the capability name. 101For example, see the last 102.Sy \&am 103in the example above. 104This is only useful when merging entries. 105See the tc=name discussion below for more details. 106.Ss Encoding 107Numeric capability values may be given in one of three numeric bases. 108If the number starts with either 109.Ql 0x 110or 111.Ql 0X 112it is interpreted as a hexadecimal number (both upper and lower case a-f 113may be used to denote the extended hexadecimal digits). 114Otherwise, if the number starts with a 115.Ql 0 116it is interpreted as an octal number. 117Otherwise the number is interpreted as a decimal number. 118.Pp 119String capability values may contain any character. 120Non-printable 121.Dv ASCII 122codes, new lines, and colons may be conveniently represented by the use 123of escape sequences: 124.Bl -column "\eX,X\eX" "(ASCII octal nnn)" 125.It ^X ('\fIX\fP' & 037) control-\fIX\fP 126.It \eb, \eB (ASCII 010) backspace 127.It \et, \eT (ASCII 011) tab 128.It \en, \eN (ASCII 012) line feed (newline) 129.It \ef, \eF (ASCII 014) form feed 130.It \er, \eR (ASCII 015) carriage return 131.It \ee, \eE (ASCII 027) escape 132.It \ec, \eC (:) colon 133.It \e\e (\e\|) back slash 134.It \e^ (^) caret 135.It \e\fInnn\fP (ASCII octal \fInnn\fP) 136.El 137.Pp 138A 139.Sq \e 140followed by up to three octal digits directly specifies 141the numeric code for a character. 142The use of 143.Tn ASCII 144.Dv NUL Ns s , 145while easily 146encoded, causes all sorts of problems and must be used with care since 147.Dv NUL Ns s 148are typically used to denote the end of strings; many applications 149use 150.Sq \e200 151to represent a 152.Dv NUL . 153.Pp 154A special capability, 155.Qq tc=name , 156is used to indicate that the record specified by 157.Fa name 158should be substituted for the 159.Qq tc 160capability. 161.Qq tc 162capabilities may interpolate records which also contain 163.Qq tc 164capabilities and more than one 165.Qq tc 166capability may be used in a record. 167A 168.Qq tc 169expansion scope (i.e. where the argument is searched for) contains the 170file in which the 171.Qq tc 172is declared and all subsequent files in the file array. 173.Sh SEE ALSO 174.Xr cgetcap 3 , 175.Xr termcap 3 , 176.Xr terminfo 5 177.Sh HISTORY 178.Nm termcap 179described the capabilities of terminals, used by programs such as 180.Xr vi 1 181and 182.Xr hack 6 . 183These programs still use 184.Nm termcap 185today, but their capability requests are mapped onto 186.Xr terminfo 5 187ones instead. 188As such, the termcap database file is no longer shipped with 189.Nx . 190.Sh AUTHORS 191.An Roy Marples Aq Mt roy@NetBSD.org 192