Debian Codegraph @

upstream/debian-unstable/man3/Term::Cap.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Term::Cap 3perl"
58 .TH Term::Cap 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Term::Cap \- Perl termcap interface
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 6
68 \& require Term::Cap;
69 \& $terminal = Term::Cap\->Tgetent({ TERM => undef, OSPEED => $ospeed });
70 \& $terminal\->Trequire(qw/ce ku kd/);
71 \& $terminal\->Tgoto(\*(Aqcm\*(Aq, $col, $row, $FH);
72 \& $terminal\->Tputs(\*(Aqdl\*(Aq, $count, $FH);
73 \& $terminal\->Tpad($string, $count, $FH);
74 .Ve
75 .SH DESCRIPTION
76 .IX Header "DESCRIPTION"
77 These are low-level functions to extract and use capabilities from
78 a terminal capability (termcap) database.
79 .PP
80 More information on the terminal capabilities will be found in the
81 termcap manpage on most Unix-like systems.
82 .SS METHODS
83 .IX Subsection "METHODS"
84 The output strings for \fBTputs\fR are cached for counts of 1 for performance.
85 \&\fBTgoto\fR and \fBTpad\fR do not cache. \f(CW\*(C`$self\->{_xx}\*(C'\fR is the raw termcap
86 data and \f(CW\*(C`$self\->{xx}\*(C'\fR is the cached version.
87 .PP
88 .Vb 1
89 \& print $terminal\->Tpad($self\->{_xx}, 1);
90 .Ve
91 .PP
92 \&\fBTgoto\fR, \fBTputs\fR, and \fBTpad\fR return the string and will also
93 output the string to \f(CW$FH\fR if specified.
94 .IP \fBTgetent\fR 4
95 .IX Item "Tgetent"
96 Returns a blessed object reference which the user can
97 then use to send the control strings to the terminal using \fBTputs\fR
98 and \fBTgoto\fR.
99 .Sp
100 The function extracts the entry of the specified terminal
101 type \fITERM\fR (defaults to the environment variable \fITERM\fR) from the
102 database.
103 .Sp
104 It will look in the environment for a \fITERMCAP\fR variable. If
105 found, and the value does not begin with a slash, and the terminal
106 type name is the same as the environment string \fITERM\fR, the
107 \&\fITERMCAP\fR string is used instead of reading a termcap file. If
108 it does begin with a slash, the string is used as a path name of
109 the termcap file to search. If \fITERMCAP\fR does not begin with a
110 slash and name is different from \fITERM\fR, \fBTgetent\fR searches the
111 files \fR\f(CI$HOME\fR\fI/.termcap\fR, \fI/etc/termcap\fR, and \fI/usr/share/misc/termcap\fR,
112 in that order, unless the environment variable \fITERMPATH\fR exists,
113 in which case it specifies a list of file pathnames (separated by
114 spaces or colons) to be searched \fBinstead\fR. Whenever multiple
115 files are searched and a tc field occurs in the requested entry,
116 the entry it names must be found in the same file or one of the
117 succeeding files. If there is a \f(CW\*(C`:tc=...:\*(C'\fR in the \fITERMCAP\fR
118 environment variable string it will continue the search in the
119 files as above.
120 .Sp
121 The extracted termcap entry is available in the object
122 as \f(CW\*(C`$self\->{TERMCAP}\*(C'\fR.
123 .Sp
124 It takes a hash reference as an argument with two optional keys:
125 .RS 4
126 .IP OSPEED 2
127 .IX Item "OSPEED"
128 The terminal output bit rate (often mistakenly called the baud rate)
129 for this terminal \- if not set a warning will be generated
130 and it will be defaulted to 9600. \fIOSPEED\fR can be specified as
131 either a POSIX termios/SYSV termio speeds (where 9600 equals 9600) or
132 an old DSD-style speed ( where 13 equals 9600).
133 .IP TERM 2
134 .IX Item "TERM"
135 The terminal type whose termcap entry will be used \- if not supplied it will
136 default to \f(CW$ENV\fR{TERM}: if that is not set then \fBTgetent\fR will croak.
137 .RE
138 .RS 4
139 .Sp
140 It calls \f(CW\*(C`croak\*(C'\fR on failure.
141 .RE
142 .IP \fBTpad\fR 4
143 .IX Item "Tpad"
144 Outputs a literal string with appropriate padding for the current terminal.
145 .Sp
146 It takes three arguments:
147 .RS 4
148 .ie n .IP \fR\fB$string\fR\fB\fR 2
149 .el .IP \fR\f(CB$string\fR\fB\fR 2
150 .IX Item "$string"
151 The literal string to be output. If it starts with a number and an optional
152 \&'*' then the padding will be increased by an amount relative to this number,
153 if the '*' is present then this amount will be multiplied by \f(CW$cnt\fR. This part
154 of \f(CW$string\fR is removed before output/
155 .ie n .IP \fR\fB$cnt\fR\fB\fR 2
156 .el .IP \fR\f(CB$cnt\fR\fB\fR 2
157 .IX Item "$cnt"
158 Will be used to modify the padding applied to string as described above.
159 .ie n .IP \fR\fB$FH\fR\fB\fR 2
160 .el .IP \fR\f(CB$FH\fR\fB\fR 2
161 .IX Item "$FH"
162 An optional filehandle (or IO::Handle ) that output will be printed to.
163 .RE
164 .RS 4
165 .Sp
166 The padded \f(CW$string\fR is returned.
167 .RE
168 .IP \fBTputs\fR 4
169 .IX Item "Tputs"
170 Output the string for the given capability padded as appropriate without
171 any parameter substitution.
172 .Sp
173 It takes three arguments:
174 .RS 4
175 .ie n .IP \fR\fB$cap\fR\fB\fR 2
176 .el .IP \fR\f(CB$cap\fR\fB\fR 2
177 .IX Item "$cap"
178 The capability whose string is to be output.
179 .ie n .IP \fR\fB$cnt\fR\fB\fR 2
180 .el .IP \fR\f(CB$cnt\fR\fB\fR 2
181 .IX Item "$cnt"
182 A count passed to Tpad to modify the padding applied to the output string.
183 If \f(CW$cnt\fR is zero or one then the resulting string will be cached.
184 .ie n .IP \fR\fB$FH\fR\fB\fR 2
185 .el .IP \fR\f(CB$FH\fR\fB\fR 2
186 .IX Item "$FH"
187 An optional filehandle (or IO::Handle ) that output will be printed to.
188 .RE
189 .RS 4
190 .Sp
191 The appropriate string for the capability will be returned.
192 .RE
193 .IP \fBTgoto\fR 4
194 .IX Item "Tgoto"
195 \&\fBTgoto\fR decodes a cursor addressing string with the given parameters.
196 .Sp
197 There are four arguments:
198 .RS 4
199 .ie n .IP \fR\fB$cap\fR\fB\fR 2
200 .el .IP \fR\f(CB$cap\fR\fB\fR 2
201 .IX Item "$cap"
202 The name of the capability to be output.
203 .ie n .IP \fR\fB$col\fR\fB\fR 2
204 .el .IP \fR\f(CB$col\fR\fB\fR 2
205 .IX Item "$col"
206 The first value to be substituted in the output string ( usually the column
207 in a cursor addressing capability )
208 .ie n .IP \fR\fB$row\fR\fB\fR 2
209 .el .IP \fR\f(CB$row\fR\fB\fR 2
210 .IX Item "$row"
211 The second value to be substituted in the output string (usually the row
212 in cursor addressing capabilities)
213 .ie n .IP \fR\fB$FH\fR\fB\fR 2
214 .el .IP \fR\f(CB$FH\fR\fB\fR 2
215 .IX Item "$FH"
216 An optional filehandle (or IO::Handle ) to which the output string will be
217 printed.
218 .RE
219 .RS 4
220 .Sp
221 Substitutions are made with \f(CW$col\fR and \f(CW$row\fR in the output string with the
222 following \fBsprintf()\fR line formats:
223 .Sp
224 .Vb 6
225 \& %% output \`%\*(Aq
226 \& %d output value as in printf %d
227 \& %2 output value as in printf %2d
228 \& %3 output value as in printf %3d
229 \& %. output value as in printf %c
230 \& %+x add x to value, then do %.
231 \&
232 \& %>xy if value > x then add y, no output
233 \& %r reverse order of two parameters, no output
234 \& %i increment by one, no output
235 \& %B BCD (16*(value/10)) + (value%10), no output
236 \&
237 \& %n exclusive\-or all parameters with 0140 (Datamedia 2500)
238 \& %D Reverse coding (value \- 2*(value%16)), no output (Delta Data)
239 .Ve
240 .Sp
241 The output string will be returned.
242 .RE
243 .IP \fBTrequire\fR 4
244 .IX Item "Trequire"
245 Takes a list of capabilities as an argument and will croak if one is not
246 found.
247 .SH EXAMPLES
248 .IX Header "EXAMPLES"
249 .Vb 1
250 \& use Term::Cap;
251 \&
252 \& # Get terminal output speed
253 \& require POSIX;
254 \& my $termios = POSIX::Termios\->new;
255 \& $termios\->getattr;
256 \& my $ospeed = $termios\->getospeed;
257 \&
258 \& # Old\-style ioctl code to get ospeed:
259 \& # require \*(Aqioctl.pl\*(Aq;
260 \& # ioctl(TTY,$TIOCGETP,$sgtty);
261 \& # ($ispeed,$ospeed) = unpack(\*(Aqcc\*(Aq,$sgtty);
262 \&
263 \& # allocate and initialize a terminal structure
264 \& my $terminal = Term::Cap\->Tgetent({ TERM => undef, OSPEED => $ospeed });
265 \&
266 \& # require certain capabilities to be available
267 \& $terminal\->Trequire(qw/ce ku kd/);
268 \&
269 \& # Output Routines, if $FH is undefined these just return the string
270 \&
271 \& # Tgoto does the % expansion stuff with the given args
272 \& $terminal\->Tgoto(\*(Aqcm\*(Aq, $col, $row, $FH);
273 \&
274 \& # Tputs doesn\*(Aqt do any % expansion.
275 \& $terminal\->Tputs(\*(Aqdl\*(Aq, $count = 1, $FH);
276 .Ve
277 .SH "COPYRIGHT AND LICENSE"
278 .IX Header "COPYRIGHT AND LICENSE"
279 Copyright 1995\-2015 (c) perl5 porters.
280 .PP
281 This software is free software and can be modified and distributed under
282 the same terms as Perl itself.
283 .PP
284 Please see the file README in the Perl source distribution for details of
285 the Perl license.
286 .SH AUTHOR
287 .IX Header "AUTHOR"
288 This module is part of the core Perl distribution and is also maintained
289 for CPAN by Jonathan Stowe <[email protected]>.
290 .PP
291 The code is hosted on Github: https://github.com/jonathanstowe/Term\-Cap
292 please feel free to fork, submit patches etc, etc there.
293 .SH "SEE ALSO"
294 .IX Header "SEE ALSO"
295 \&\fBtermcap\fR\|(5)