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