Initial commit of OpenSPARC T2 architecture model.

[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / man / man3 / Term::Cap.3

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Term::Cap 3"
.TH Term::Cap 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide"
.SH "NAME"
Term::Cap \- Perl termcap interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    require Term::Cap;
\&    $terminal = Tgetent Term::Cap { TERM => undef, OSPEED => $ospeed };
\&    $terminal->Trequire(qw/ce ku kd/);
\&    $terminal->Tgoto('cm', $col, $row, $FH);
\&    $terminal->Tputs('dl', $count, $FH);
\&    $terminal->Tpad($string, $count, $FH);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These are low-level functions to extract and use capabilities from
a terminal capability (termcap) database.
.PP
More information on the terminal capabilities will be found in the
termcap manpage on most Unix-like systems.
.Sh "\s-1METHODS\s0"
.IX Subsection "METHODS"
.RS 4
The output strings for \fBTputs\fR are cached for counts of 1 for performance.
\&\fBTgoto\fR and \fBTpad\fR do not cache.  \f(CW\*(C`$self\->{_xx}\*(C'\fR is the raw termcap
data and \f(CW\*(C`$self\->{xx}\*(C'\fR is the cached version.
.Sp
.Vb 1
\&    print $terminal->Tpad($self->{_xx}, 1);
.Ve
.Sp
\&\fBTgoto\fR, \fBTputs\fR, and \fBTpad\fR return the string and will also
output the string to \f(CW$FH\fR if specified.
.RE
.IP "\fBTgetent\fR" 4
.IX Item "Tgetent"
Returns a blessed object reference which the user can
then use to send the control strings to the terminal using \fBTputs\fR
and \fBTgoto\fR.
.Sp
The function extracts the entry of the specified terminal
type \fI\s-1TERM\s0\fR (defaults to the environment variable \fI\s-1TERM\s0\fR) from the
database.
.Sp
It will look in the environment for a \fI\s-1TERMCAP\s0\fR variable.  If
found, and the value does not begin with a slash, and the terminal
type name is the same as the environment string \fI\s-1TERM\s0\fR, the
\&\fI\s-1TERMCAP\s0\fR string is used instead of reading a termcap file.  If
it does begin with a slash, the string is used as a path name of
the termcap file to search.  If \fI\s-1TERMCAP\s0\fR does not begin with a
slash and name is different from \fI\s-1TERM\s0\fR, \fBTgetent\fR searches the
files \fI$HOME/.termcap\fR, \fI/etc/termcap\fR, and \fI/usr/share/misc/termcap\fR,
in that order, unless the environment variable \fI\s-1TERMPATH\s0\fR exists,
in which case it specifies a list of file pathnames (separated by
spaces or colons) to be searched \fBinstead\fR.  Whenever multiple
files are searched and a tc field occurs in the requested entry,
the entry it names must be found in the same file or one of the
succeeding files.  If there is a \f(CW\*(C`:tc=...:\*(C'\fR in the \fI\s-1TERMCAP\s0\fR
environment variable string it will continue the search in the
files as above.
.Sp
The extracted termcap entry is available in the object
as \f(CW\*(C`$self\->{TERMCAP}\*(C'\fR.
.Sp
It takes a hash reference as an argument with two optional keys:
.RS 4
.IP "\s-1OSPEED\s0" 2
.IX Item "OSPEED"
The terminal output bit rate (often mistakenly called the baud rate)
for this terminal \- if not set a warning will be generated
and it will be defaulted to 9600.  \fI\s-1OSPEED\s0\fR can be be specified as
either a \s-1POSIX\s0 termios/SYSV termio speeds (where 9600 equals 9600) or
an old DSD-style speed ( where 13 equals 9600).
.IP "\s-1TERM\s0" 2
.IX Item "TERM"
The terminal type whose termcap entry will be used \- if not supplied it will
default to \f(CW$ENV\fR{\s-1TERM\s0}: if that is not set then \fBTgetent\fR will croak.
.RE
.RS 4
.Sp
It calls \f(CW\*(C`croak\*(C'\fR on failure.
.RE
.IP "\fBTpad\fR" 4
.IX Item "Tpad"
Outputs a literal string with appropriate padding for the current terminal.
.Sp
It takes three arguments:
.RS 4
.IP "\fB$string\fR" 2
.IX Item "$string"
The literal string to be output.  If it starts with a number and an optional
\&'*' then the padding will be increased by an amount relative to this number,
if the '*' is present then this amount will me multiplied by \f(CW$cnt\fR.  This part
of \f(CW$string\fR is removed before output/
.IP "\fB$cnt\fR" 2
.IX Item "$cnt"
Will be used to modify the padding applied to string as described above.
.IP "\fB$FH\fR" 2
.IX Item "$FH"
An optional filehandle (or IO::Handle ) that output will be printed to.
.RE
.RS 4
.Sp
The padded \f(CW$string\fR is returned.
.RE
.IP "\fBTputs\fR" 4
.IX Item "Tputs"
Output the string for the given capability padded as appropriate without
any parameter substitution.
.Sp
It takes three arguments:
.RS 4
.IP "\fB$cap\fR" 2
.IX Item "$cap"
The capability whose string is to be output.
.IP "\fB$cnt\fR" 2
.IX Item "$cnt"
A count passed to Tpad to modify the padding applied to the output string.
If \f(CW$cnt\fR is zero or one then the resulting string will be cached.
.IP "\fB$FH\fR" 2
.IX Item "$FH"
An optional filehandle (or IO::Handle ) that output will be printed to.
.RE
.RS 4
.Sp
The appropriate string for the capability will be returned.
.RE
.IP "\fBTgoto\fR" 4
.IX Item "Tgoto"
\&\fBTgoto\fR decodes a cursor addressing string with the given parameters.
.Sp
There are four arguments:
.RS 4
.IP "\fB$cap\fR" 2
.IX Item "$cap"
The name of the capability to be output.
.IP "\fB$col\fR" 2
.IX Item "$col"
The first value to be substituted in the output string ( usually the column
in a cursor addressing capability )
.IP "\fB$row\fR" 2
.IX Item "$row"
The second value to be substituted in the output string (usually the row
in cursor addressing capabilities)
.IP "\fB$FH\fR" 2
.IX Item "$FH"
An optional filehandle (or IO::Handle ) to which the output string will be
printed.
.RE
.RS 4
.Sp
Substitutions are made with \f(CW$col\fR and \f(CW$row\fR in the output string with the
following \fIsprintf()\fR line formats:
.Sp
.Vb 6
\& %%   output `%'
\& %d   output value as in printf %d
\& %2   output value as in printf %2d
\& %3   output value as in printf %3d
\& %.   output value as in printf %c
\& %+x  add x to value, then do %.
.Ve
.Sp
.Vb 4
\& %>xy if value > x then add y, no output
\& %r   reverse order of two parameters, no output
\& %i   increment by one, no output
\& %B   BCD (16*(value/10)) + (value%10), no output
.Ve
.Sp
.Vb 2
\& %n   exclusive-or all parameters with 0140 (Datamedia 2500)
\& %D   Reverse coding (value - 2*(value%16)), no output (Delta Data)
.Ve
.Sp
The output string will be returned.
.RE
.IP "\fBTrequire\fR" 4
.IX Item "Trequire"
Takes a list of capabilities as an argument and will croak if one is not
found.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 1
\&    use Term::Cap;
.Ve
.PP
.Vb 5
\&    # Get terminal output speed
\&    require POSIX;
\&    my $termios = new POSIX::Termios;
\&    $termios->getattr;
\&    my $ospeed = $termios->getospeed;
.Ve
.PP
.Vb 4
\&    # Old-style ioctl code to get ospeed:
\&    #     require 'ioctl.pl';
\&    #     ioctl(TTY,$TIOCGETP,$sgtty);
\&    #     ($ispeed,$ospeed) = unpack('cc',$sgtty);
.Ve
.PP
.Vb 2
\&    # allocate and initialize a terminal structure
\&    $terminal = Tgetent Term::Cap { TERM => undef, OSPEED => $ospeed };
.Ve
.PP
.Vb 2
\&    # require certain capabilities to be available
\&    $terminal->Trequire(qw/ce ku kd/);
.Ve
.PP
.Vb 1
\&    # Output Routines, if $FH is undefined these just return the string
.Ve
.PP
.Vb 2
\&    # Tgoto does the % expansion stuff with the given args
\&    $terminal->Tgoto('cm', $col, $row, $FH);
.Ve
.PP
.Vb 2
\&    # Tputs doesn't do any % expansion.
\&    $terminal->Tputs('dl', $count = 1, $FH);
.Ve
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Please see the \s-1README\s0 file in distribution.
.SH "AUTHOR"
.IX Header "AUTHOR"
This module is part of the core Perl distribution and is also maintained
for \s-1CPAN\s0 by Jonathan Stowe <jns@gellyfish.com>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fItermcap\fR\|(5)