Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Term::Cap.3pm

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