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