1.\" $NetBSD: termcap.3,v 1.8 2014/03/18 18:20:38 riastradh Exp $ 2.\" 3.\" Copyright (c) 2009 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 14, 2011 31.Dt TERMCAP 3 32.Os 33.Sh NAME 34.Nm tgetent , 35.Nm tgetnum , 36.Nm tgetflag , 37.Nm tgetstr , 38.Nm tgoto , 39.Nm tputs 40.Nd terminal independent operation routines 41.Sh LIBRARY 42.Lb libtermcap 43.Sh SYNOPSIS 44.In termcap.h 45.Vt char PC ; 46.Vt char *BC ; 47.Vt char *UP ; 48.Ft int 49.Fn tgetent "char *bp" "const char *name" 50.Ft int 51.Fn tgetnum "const char *id" 52.Ft int 53.Fn tgetflag "const char *id" 54.Ft char * 55.Fn tgetstr "const char *id" "char **area" 56.Ft char * 57.Fn tgoto "const char *cm" "int destcol" "int destline" 58.Sh DESCRIPTION 59These functions extract and use capabilities from a terminal capability 60database. 61They exist as wrappers around equivalent 62.Xr terminfo 3 63functions, which new code should use. 64These are low level routines; see 65.Xr curses 3 66for a higher level package. 67.Pp 68The 69.Fn tgetent 70function calls 71.Fn setupterm 72and configures 73.Va PC , 74.Va UP 75and 76.Va BC . 77Only 78.Va PC 79is actually used internally. 80The 81.Fn tgetent 82function returns \-1 if none of the 83.Nm terminfo 84data base files could be opened, 850 if the terminal name given does not match an entry, 86and 1 if all goes well. 87The 88.Fa bp 89argument is not used. 90.Pp 91The 92.Fn tgetnum 93function gets the numeric value of the capability 94.Fa id , 95returning \-1 if it is not given for the terminal. 96The 97.Fn tgetflag 98function returns 1 if the specified capability is present in the terminal's 99entry, 0 if it is not. 100The 101.Fn tgetstr 102function returns the string value of the capability 103.Fa id . 104This is a 105.Xr terminfo 5 106string and not a 107.Nm termcap 108string; 109as such it should only be processed by 110.Fn tgoto . 111The 112.Fn tgetstr 113function returns 114.Dv NULL 115if the capability was not found. 116The 117.Fa area 118argument is unused. 119.Pp 120The 121.Fn tgoto 122function returns a cursor addressing string decoded from 123.Fa cm 124to go to column 125.Fa destcol 126in line 127.Fa destline , 128or 129.Dv NULL 130on error conditions such as out of memory. 131Please note that 132.Fn tgoto 133can return an incomplete value on a malformed input sequence. 134Historically 135.Fn tgoto 136used to return 137.Dq OOPS 138on those conditions, so newer programs should now be checking the return 139value. 140.Sh SEE ALSO 141.Xr terminfo 3 , 142.Xr terminfo 5 143.Sh HISTORY 144.Nm termcap 145first appeared in 4.0BSD. 146.Nx 1.5 147introduced some 148.Nm termcap 149.Fn t_* 150extensions which were removed in 151.Nx 6.0 152when 153.Xr terminfo 3 154was introduced. 155.Sh AUTHORS 156.An Roy Marples Aq Mt roy@NetBSD.org 157