1.\" Copyright (c) 1980, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)termcap.3 6.6 (Berkeley) 4/19/91 33.\" 34.Dd April 19, 1991 35.Dt TERMCAP 3 36.Os BSD 4 37.Sh NAME 38.Nm tgetent , 39.Nm tgetnum , 40.Nm tgetflag , 41.Nm tgetstr , 42.Nm tgoto , 43.Nm tputs 44.Nd terminal independent operation routines 45.Sh SYNOPSIS 46.Vt char PC; 47.Vt char *BC; 48.Vt char *UP; 49.Vt short ospeed; 50.Fn tgetent "char *bp" "char *name" 51.Fn tgetnum "char *id" 52.Fn tgetflag "char *id" 53.Ft char * 54.Fn tgetstr "char *id" "char *area" 55.Ft char * 56.Fn tgoto "char *cm" destcol destline 57.Fn tputs "register char *cp" "int affcnt" "int (*outc)()" 58.Sh DESCRIPTION 59These functions extract and use capabilities from a terminal capability data 60base, usually 61.Pa /usr/share/misc/termcap , 62the format of which is described in 63.Xr termcap 5 . 64These are low level routines; 65see 66.Xr curses 3 67for a higher level package. 68.Pp 69The 70.Fn tgetent 71function 72extracts the entry for terminal 73.Fa name 74into the buffer at 75.Fa bp . 76The 77.Fa bp 78argument 79should be a character buffer of size 801024 and must be retained through all subsequent calls to 81.Fn tgetnum , 82.Fn tgetflag , 83and 84.Fn tgetstr . 85The 86.Fn tgetent 87function 88returns \-1 if none of the 89.Nm termcap 90data base files could be opened, 910 if the terminal name given does not have an entry, 92and 1 if all goes well. 93It will look in the environment for a 94.Ev TERMCAP 95variable. 96If found, and the value does not begin with a slash, 97and the terminal type 98.Fa name 99is the same as the environment string 100.Ev TERM , 101the 102.Ev TERMCAP 103string is used instead of reading a 104.Nm termcap 105file. 106If it does begin with a slash, the string is used as a path name 107of the 108.Nm termcap 109file to search. 110If 111.Ev TERMCAP 112does not begin with a slash and 113.Fa name 114is different from 115.Ev TERM , 116.Fn tgetent 117searches the files 118.Pa $HOME/.termcap 119and 120.Pa /usr/share/misc/termcap , 121in that order, unless the environment variable 122.Ev TERMPATH 123exists, 124in which case it specifies a list of file pathnames 125(separated by spaces or colons) to be searched instead. 126Whenever multiple files are searched and a 127.Sy tc 128field occurs in the requested entry, the entry it names must be found 129in the same file or one of the succeeding files. 130This can speed up entry into programs that call 131.Fn tgetent , 132as well as help debug new terminal descriptions 133or make one for your terminal if you can't write the file 134.Pa /usr/share/misc/termcap . 135.Pp 136The 137.Fn tgetnum 138function 139gets the numeric value of capability 140.Fa id , 141returning \-1 if is not given for the terminal. 142The 143.Fn tgetflag 144function 145returns 1 if the specified capability is present in 146the terminal's entry, 0 if it is not. 147The 148.Fn tgetstr 149function 150returns the string value of the capability 151.Fa id , 152places it in the buffer at 153.Fa area , 154and advances the 155.Fa area 156pointer. 157It decodes the abbreviations for this field described in 158.Xr termcap 5 , 159except for cursor addressing and padding information. 160The 161.Fn tgetstr 162function 163returns 164.Dv NULL 165if the capability was not found. 166.Pp 167The 168.Fn tgoto 169function 170returns a cursor addressing string decoded from 171.Fa cm 172to go to column 173.Fa destcol 174in line 175.Fa destline . 176It uses the external variables 177.Va UP 178(from the 179.Sy up 180capability) 181and 182.Va BC 183(if 184.Sy bc 185is given rather than 186.Sy bs ) 187if necessary to avoid placing 188.Sy \en , 189.Sy ^D 190or 191.Sy ^@ 192in 193the returned string. 194(Programs which call 195.Fn tgoto 196should be sure to turn off the 197.Dv XTABS 198bit(s), 199since 200.Fn tgoto 201may now output a tab. 202Note that programs using termcap should in general turn off 203.Dv XTABS 204anyway since some terminals use control-I for other functions, 205such as nondestructive space.) 206If a 207.Sy % 208sequence is given which is not understood, then 209.Fn tgoto 210returns 211.Pq Dv OOPS . 212.Pp 213The 214.Fn tputs 215function 216decodes the leading padding information of the string 217.Fa cp ; 218.Fa affcnt 219gives the number of lines affected by the operation, or 1 if this is 220not applicable, 221.Fa outc 222is a routine which is called with each character in turn. 223The external variable 224.Va ospeed 225should contain the output speed of the terminal as encoded by 226.Xr stty 3 . 227The external variable 228.Va PC 229should contain a pad character to be used (from the 230.SY pc 231capability) 232if a null 233.Pq Sy ^@ 234is inappropriate. 235.Sh FILES 236.Bl -tag -width /usr/share/misc/termcap -compact 237.It Pa /usr/lib/libtermcap.a 238.Fl l Ar ltermcap 239library (also known as 240.Fl l Ar ltermlib ) 241.It Pa /usr/share/misc/termcap 242standard terminal capability data base 243.It Pa $HOME/.termcap 244user's terminal capability data base 245.El 246.Sh SEE ALSO 247.Xr ex 1 , 248.Xr curses 3 , 249.Xr termcap 5 250.Sh HISTORY 251The 252.Nm 253functions appeared in 254.Bx 4.0 . 255