1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)termcap.3 8.1 (Berkeley) 06/04/93 7.\" 8.Dd 9.Dt TERMCAP 3 10.Os BSD 4 11.Sh NAME 12.Nm tgetent , 13.Nm tgetnum , 14.Nm tgetflag , 15.Nm tgetstr , 16.Nm tgoto , 17.Nm tputs 18.Nd terminal independent operation routines 19.Sh SYNOPSIS 20.Vt char PC; 21.Vt char *BC; 22.Vt char *UP; 23.Vt short ospeed; 24.Fn tgetent "char *bp" "char *name" 25.Fn tgetnum "char *id" 26.Fn tgetflag "char *id" 27.Ft char * 28.Fn tgetstr "char *id" "char **area" 29.Ft char * 30.Fn tgoto "char *cm" destcol destline 31.Fn tputs "register char *cp" "int affcnt" "int (*outc)()" 32.Sh DESCRIPTION 33These functions extract and use capabilities from a terminal capability data 34base, usually 35.Pa /usr/share/misc/termcap , 36the format of which is described in 37.Xr termcap 5 . 38These are low level routines; 39see 40.Xr curses 3 41for a higher level package. 42.Pp 43The 44.Fn tgetent 45function 46extracts the entry for terminal 47.Fa name 48into the buffer at 49.Fa bp . 50The 51.Fa bp 52argument 53should be a character buffer of size 541024 and must be retained through all subsequent calls to 55.Fn tgetnum , 56.Fn tgetflag , 57and 58.Fn tgetstr . 59The 60.Fn tgetent 61function 62returns \-1 if none of the 63.Nm termcap 64data base files could be opened, 650 if the terminal name given does not have an entry, 66and 1 if all goes well. 67It will look in the environment for a 68.Ev TERMCAP 69variable. 70If found, and the value does not begin with a slash, 71and the terminal type 72.Fa name 73is the same as the environment string 74.Ev TERM , 75the 76.Ev TERMCAP 77string is used instead of reading a 78.Nm termcap 79file. 80If it does begin with a slash, the string is used as a path name 81of the 82.Nm termcap 83file to search. 84If 85.Ev TERMCAP 86does not begin with a slash and 87.Fa name 88is different from 89.Ev TERM , 90.Fn tgetent 91searches the files 92.Pa $HOME/.termcap 93and 94.Pa /usr/share/misc/termcap , 95in that order, unless the environment variable 96.Ev TERMPATH 97exists, 98in which case it specifies a list of file pathnames 99(separated by spaces or colons) to be searched instead. 100Whenever multiple files are searched and a 101.Sy tc 102field occurs in the requested entry, the entry it names must be found 103in the same file or one of the succeeding files. 104This can speed up entry into programs that call 105.Fn tgetent , 106as well as help debug new terminal descriptions 107or make one for your terminal if you can't write the file 108.Pa /usr/share/misc/termcap . 109.Pp 110The 111.Fn tgetnum 112function 113gets the numeric value of capability 114.Fa id , 115returning \-1 if is not given for the terminal. 116The 117.Fn tgetflag 118function 119returns 1 if the specified capability is present in 120the terminal's entry, 0 if it is not. 121The 122.Fn tgetstr 123function 124returns the string value of the capability 125.Fa id , 126places it in the buffer at 127.Fa area , 128and advances the 129.Fa area 130pointer. 131It decodes the abbreviations for this field described in 132.Xr termcap 5 , 133except for cursor addressing and padding information. 134The 135.Fn tgetstr 136function 137returns 138.Dv NULL 139if the capability was not found. 140.Pp 141The 142.Fn tgoto 143function 144returns a cursor addressing string decoded from 145.Fa cm 146to go to column 147.Fa destcol 148in line 149.Fa destline . 150It uses the external variables 151.Va UP 152(from the 153.Sy up 154capability) 155and 156.Va BC 157(if 158.Sy bc 159is given rather than 160.Sy bs ) 161if necessary to avoid placing 162.Sy \en , 163.Sy ^D 164or 165.Sy ^@ 166in 167the returned string. 168(Programs which call 169.Fn tgoto 170should be sure to turn off the 171.Dv XTABS 172bit(s), 173since 174.Fn tgoto 175may now output a tab. 176Note that programs using termcap should in general turn off 177.Dv XTABS 178anyway since some terminals use control-I for other functions, 179such as nondestructive space.) 180If a 181.Sy % 182sequence is given which is not understood, then 183.Fn tgoto 184returns 185.Pq Dv OOPS . 186.Pp 187The 188.Fn tputs 189function 190decodes the leading padding information of the string 191.Fa cp ; 192.Fa affcnt 193gives the number of lines affected by the operation, or 1 if this is 194not applicable, 195.Fa outc 196is a routine which is called with each character in turn. 197The external variable 198.Va ospeed 199should contain the output speed of the terminal as encoded by 200.Xr stty 3 . 201The external variable 202.Va PC 203should contain a pad character to be used (from the 204.SY pc 205capability) 206if a null 207.Pq Sy ^@ 208is inappropriate. 209.Sh FILES 210.Bl -tag -width /usr/share/misc/termcap -compact 211.It Pa /usr/lib/libtermcap.a 212.Fl l Ar ltermcap 213library (also known as 214.Fl l Ar ltermlib ) 215.It Pa /usr/share/misc/termcap 216standard terminal capability data base 217.It Pa $HOME/.termcap 218user's terminal capability data base 219.El 220.Sh SEE ALSO 221.Xr ex 1 , 222.Xr curses 3 , 223.Xr termcap 5 224.Sh HISTORY 225The 226.Nm 227functions appeared in 228.Bx 4.0 . 229