Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 215 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/FileHandle.3perl b/upstream/debian-unstable/man3/FileHandle.3perl
new file mode 100644
index 00000000..ba405db1
--- /dev/null
+++ b/upstream/debian-unstable/man3/FileHandle.3perl
@@ -0,0 +1,215 @@
+.\" -*- 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 "FileHandle 3perl"
+.TH FileHandle 3perl 2024-01-12 "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
+FileHandle \- supply object methods for filehandles
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use FileHandle;
+\&
+\&    my $fh = FileHandle\->new;
+\&    if ($fh\->open("< file")) {
+\&        print <$fh>;
+\&        $fh\->close;
+\&    }
+\&
+\&    my $fh = FileHandle\->new("> FOO");
+\&    if (defined $fh) {
+\&        print $fh "bar\en";
+\&        $fh\->close;
+\&    }
+\&
+\&    my $fh = FileHandle\->new("file", "r");
+\&    if (defined $fh) {
+\&        print <$fh>;
+\&        undef $fh;       # automatically closes the file
+\&    }
+\&
+\&    my $fh = FileHandle\->new("file", O_WRONLY|O_APPEND);
+\&    if (defined $fh) {
+\&        print $fh "corge\en";
+\&        undef $fh;       # automatically closes the file
+\&    }
+\&
+\&    my $pos = $fh\->getpos;
+\&    $fh\->setpos($pos);
+\&
+\&    $fh\->setvbuf(my $buffer_var, _IOLBF, 1024);
+\&
+\&    my ($readfh, $writefh) = FileHandle::pipe;
+\&
+\&    autoflush STDOUT 1;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+NOTE: This class is now a front-end to the IO::* classes.
+.PP
+\&\f(CW\*(C`FileHandle::new\*(C'\fR creates a \f(CW\*(C`FileHandle\*(C'\fR, which is a reference to a
+newly created symbol (see the Symbol package).  If it receives any
+parameters, they are passed to \f(CW\*(C`FileHandle::open\*(C'\fR; if the open fails,
+the \f(CW\*(C`FileHandle\*(C'\fR object is destroyed.  Otherwise, it is returned to
+the caller.
+.PP
+\&\f(CW\*(C`FileHandle::new_from_fd\*(C'\fR creates a \f(CW\*(C`FileHandle\*(C'\fR like \f(CW\*(C`new\*(C'\fR does.
+It requires two parameters, which are passed to \f(CW\*(C`FileHandle::fdopen\*(C'\fR;
+if the fdopen fails, the \f(CW\*(C`FileHandle\*(C'\fR object is destroyed.
+Otherwise, it is returned to the caller.
+.PP
+\&\f(CW\*(C`FileHandle::open\*(C'\fR accepts one parameter or two.  With one parameter,
+it is just a front end for the built-in \f(CW\*(C`open\*(C'\fR function.  With two
+parameters, the first parameter is a filename that may include
+whitespace or other special characters, and the second parameter is
+the open mode, optionally followed by a file permission value.
+.PP
+If \f(CW\*(C`FileHandle::open\*(C'\fR receives a Perl mode string (">", "+<", etc.)
+or a POSIX \fBfopen()\fR mode string ("w", "r+", etc.), it uses the basic
+Perl \f(CW\*(C`open\*(C'\fR operator.
+.PP
+If \f(CW\*(C`FileHandle::open\*(C'\fR is given a numeric mode, it passes that mode
+and the optional permissions value to the Perl \f(CW\*(C`sysopen\*(C'\fR operator.
+For convenience, \f(CW\*(C`FileHandle::import\*(C'\fR tries to import the O_XXX
+constants from the Fcntl module.  If dynamic loading is not available,
+this may fail, but the rest of FileHandle will still work.
+.PP
+\&\f(CW\*(C`FileHandle::fdopen\*(C'\fR is like \f(CW\*(C`open\*(C'\fR except that its first parameter
+is not a filename but rather a file handle name, a FileHandle object,
+or a file descriptor number.
+.PP
+If the C functions \fBfgetpos()\fR and \fBfsetpos()\fR are available, then
+\&\f(CW\*(C`FileHandle::getpos\*(C'\fR returns an opaque value that represents the
+current position of the FileHandle, and \f(CW\*(C`FileHandle::setpos\*(C'\fR uses
+that value to return to a previously visited position.
+.PP
+If the C function \fBsetvbuf()\fR is available, then \f(CW\*(C`FileHandle::setvbuf\*(C'\fR
+sets the buffering policy for the FileHandle.  The calling sequence
+for the Perl function is the same as its C counterpart, including the
+macros \f(CW\*(C`_IOFBF\*(C'\fR, \f(CW\*(C`_IOLBF\*(C'\fR, and \f(CW\*(C`_IONBF\*(C'\fR, except that the buffer
+parameter specifies a scalar variable to use as a buffer.  WARNING: A
+variable used as a buffer by \f(CW\*(C`FileHandle::setvbuf\*(C'\fR must not be
+modified in any way until the FileHandle is closed or until
+\&\f(CW\*(C`FileHandle::setvbuf\*(C'\fR is called again, or memory corruption may
+result!
+.PP
+See perlfunc for complete descriptions of each of the following
+supported \f(CW\*(C`FileHandle\*(C'\fR methods, which are just front ends for the
+corresponding built-in functions:
+.PP
+.Vb 8
+\&    close
+\&    fileno
+\&    getc
+\&    gets
+\&    eof
+\&    clearerr
+\&    seek
+\&    tell
+.Ve
+.PP
+See perlvar for complete descriptions of each of the following
+supported \f(CW\*(C`FileHandle\*(C'\fR methods:
+.PP
+.Vb 12
+\&    autoflush
+\&    output_field_separator
+\&    output_record_separator
+\&    input_record_separator
+\&    input_line_number
+\&    format_page_number
+\&    format_lines_per_page
+\&    format_lines_left
+\&    format_name
+\&    format_top_name
+\&    format_line_break_characters
+\&    format_formfeed
+.Ve
+.PP
+Furthermore, for doing normal I/O you might need these:
+.ie n .IP $fh\->print 4
+.el .IP \f(CW$fh\fR\->print 4
+.IX Item "$fh->print"
+See "print" in perlfunc.
+.ie n .IP $fh\->printf 4
+.el .IP \f(CW$fh\fR\->printf 4
+.IX Item "$fh->printf"
+See "printf" in perlfunc.
+.ie n .IP $fh\->getline 4
+.el .IP \f(CW$fh\fR\->getline 4
+.IX Item "$fh->getline"
+This works like <$fh> described in "I/O Operators" in perlop
+except that it's more readable and can be safely called in a
+list context but still returns just one line.
+.ie n .IP $fh\->getlines 4
+.el .IP \f(CW$fh\fR\->getlines 4
+.IX Item "$fh->getlines"
+This works like <$fh> when called in a list context to
+read all the remaining lines in a file, except that it's more readable.
+It will also \fBcroak()\fR if accidentally called in a scalar context.
+.PP
+There are many other functions available since FileHandle is descended
+from IO::File, IO::Seekable, and IO::Handle.  Please see those
+respective pages for documentation on more functions.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fBIO\fR extension,
+perlfunc, 
+"I/O Operators" in perlop.