Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 295 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/Term::Cap.3pm b/upstream/mageia-cauldron/man3pm/Term::Cap.3pm
new file mode 100644
index 00000000..1788bf83
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Term::Cap.3pm
@@ -0,0 +1,295 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.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
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "Term::Cap 3pm"
+.TH Term::Cap 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+Term::Cap \- Perl termcap interface
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 6
+\&    require Term::Cap;
+\&    $terminal = Term::Cap\->Tgetent({ TERM => undef, OSPEED => $ospeed });
+\&    $terminal\->Trequire(qw/ce ku kd/);
+\&    $terminal\->Tgoto(\*(Aqcm\*(Aq, $col, $row, $FH);
+\&    $terminal\->Tputs(\*(Aqdl\*(Aq, $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.
+.SS METHODS
+.IX Subsection "METHODS"
+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.
+.PP
+.Vb 1
+\&    print $terminal\->Tpad($self\->{_xx}, 1);
+.Ve
+.PP
+\&\fBTgoto\fR, \fBTputs\fR, and \fBTpad\fR return the string and will also
+output the string to \f(CW$FH\fR if specified.
+.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 \fITERM\fR (defaults to the environment variable \fITERM\fR) from the
+database.
+.Sp
+It will look in the environment for a \fITERMCAP\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 \fITERM\fR, the
+\&\fITERMCAP\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 \fITERMCAP\fR does not begin with a
+slash and name is different from \fITERM\fR, \fBTgetent\fR searches the
+files \fR\f(CI$HOME\fR\fI/.termcap\fR, \fI/etc/termcap\fR, and \fI/usr/share/misc/termcap\fR,
+in that order, unless the environment variable \fITERMPATH\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 \fITERMCAP\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 OSPEED 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.  \fIOSPEED\fR can be specified as
+either a POSIX termios/SYSV termio speeds (where 9600 equals 9600) or
+an old DSD-style speed ( where 13 equals 9600).
+.IP TERM 2
+.IX Item "TERM"
+The terminal type whose termcap entry will be used \- if not supplied it will
+default to \f(CW$ENV\fR{TERM}: 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
+.ie n .IP \fR\fB$string\fR\fB\fR 2
+.el .IP \fR\f(CB$string\fR\fB\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 be multiplied by \f(CW$cnt\fR.  This part
+of \f(CW$string\fR is removed before output/
+.ie n .IP \fR\fB$cnt\fR\fB\fR 2
+.el .IP \fR\f(CB$cnt\fR\fB\fR 2
+.IX Item "$cnt"
+Will be used to modify the padding applied to string as described above.
+.ie n .IP \fR\fB$FH\fR\fB\fR 2
+.el .IP \fR\f(CB$FH\fR\fB\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
+.ie n .IP \fR\fB$cap\fR\fB\fR 2
+.el .IP \fR\f(CB$cap\fR\fB\fR 2
+.IX Item "$cap"
+The capability whose string is to be output.
+.ie n .IP \fR\fB$cnt\fR\fB\fR 2
+.el .IP \fR\f(CB$cnt\fR\fB\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.
+.ie n .IP \fR\fB$FH\fR\fB\fR 2
+.el .IP \fR\f(CB$FH\fR\fB\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
+.ie n .IP \fR\fB$cap\fR\fB\fR 2
+.el .IP \fR\f(CB$cap\fR\fB\fR 2
+.IX Item "$cap"
+The name of the capability to be output.
+.ie n .IP \fR\fB$col\fR\fB\fR 2
+.el .IP \fR\f(CB$col\fR\fB\fR 2
+.IX Item "$col"
+The first value to be substituted in the output string ( usually the column
+in a cursor addressing capability )
+.ie n .IP \fR\fB$row\fR\fB\fR 2
+.el .IP \fR\f(CB$row\fR\fB\fR 2
+.IX Item "$row"
+The second value to be substituted in the output string (usually the row
+in cursor addressing capabilities)
+.ie n .IP \fR\fB$FH\fR\fB\fR 2
+.el .IP \fR\f(CB$FH\fR\fB\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 \fBsprintf()\fR line formats:
+.Sp
+.Vb 6
+\& %%   output \`%\*(Aq
+\& %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 %.
+\&
+\& %>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
+\&
+\& %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;
+\&
+\&    # Get terminal output speed
+\&    require POSIX;
+\&    my $termios = POSIX::Termios\->new;
+\&    $termios\->getattr;
+\&    my $ospeed = $termios\->getospeed;
+\&
+\&    # Old\-style ioctl code to get ospeed:
+\&    #     require \*(Aqioctl.pl\*(Aq;
+\&    #     ioctl(TTY,$TIOCGETP,$sgtty);
+\&    #     ($ispeed,$ospeed) = unpack(\*(Aqcc\*(Aq,$sgtty);
+\&
+\&    # allocate and initialize a terminal structure
+\&    my $terminal = Term::Cap\->Tgetent({ TERM => undef, OSPEED => $ospeed });
+\&
+\&    # require certain capabilities to be available
+\&    $terminal\->Trequire(qw/ce ku kd/);
+\&
+\&    # Output Routines, if $FH is undefined these just return the string
+\&
+\&    # Tgoto does the % expansion stuff with the given args
+\&    $terminal\->Tgoto(\*(Aqcm\*(Aq, $col, $row, $FH);
+\&
+\&    # Tputs doesn\*(Aqt do any % expansion.
+\&    $terminal\->Tputs(\*(Aqdl\*(Aq, $count = 1, $FH);
+.Ve
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 1995\-2015 (c) perl5 porters.
+.PP
+This software is free software and can be modified and distributed under
+the same terms as Perl itself.
+.PP
+Please see the file README in the Perl source distribution for details of
+the Perl license.
+.SH AUTHOR
+.IX Header "AUTHOR"
+This module is part of the core Perl distribution and is also maintained
+for CPAN by Jonathan Stowe <jns@gellyfish.co.uk>.
+.PP
+The code is hosted on Github: https://github.com/jonathanstowe/Term\-Cap
+please feel free to fork, submit patches etc, etc there.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBtermcap\fR\|(5)