Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 405 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/autodie.3perl b/upstream/debian-unstable/man3/autodie.3perl
new file mode 100644
index 00000000..4a6f21c6
--- /dev/null
+++ b/upstream/debian-unstable/man3/autodie.3perl
@@ -0,0 +1,405 @@
+.\" -*- 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 "autodie 3perl"
+.TH autodie 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
+autodie \- Replace functions with ones that succeed or die with lexical scope
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use autodie;            # Recommended: implies \*(Aquse autodie qw(:default)\*(Aq
+\&
+\&    use autodie qw(:all);   # Recommended more: defaults and system/exec.
+\&
+\&    use autodie qw(open close);   # open/close succeed or die
+\&
+\&    open(my $fh, "<", $filename); # No need to check!
+\&
+\&    {
+\&        no autodie qw(open);          # open failures won\*(Aqt die
+\&        open(my $fh, "<", $filename); # Could fail silently!
+\&        no autodie;                   # disable all autodies
+\&    }
+\&    
+\&    print "Hello World" or die $!;    # autodie DOESN\*(AqT check print!
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.Vb 1
+\&        bIlujDI\*(Aq yIchegh()Qo\*(Aq; yIHegh()!
+\&
+\&        It is better to die() than to return() in failure.
+\&
+\&                \-\- Klingon programming proverb.
+.Ve
+.PP
+The \f(CW\*(C`autodie\*(C'\fR pragma provides a convenient way to replace functions
+that normally return false on failure with equivalents that throw
+an exception on failure.
+.PP
+The \f(CW\*(C`autodie\*(C'\fR pragma has \fIlexical scope\fR, meaning that functions
+and subroutines altered with \f(CW\*(C`autodie\*(C'\fR will only change their behaviour
+until the end of the enclosing block, file, or \f(CW\*(C`eval\*(C'\fR.
+.PP
+If \f(CW\*(C`system\*(C'\fR is specified as an argument to \f(CW\*(C`autodie\*(C'\fR, then it
+uses IPC::System::Simple to do the heavy lifting.  See the
+description of that module for more information.
+.SH EXCEPTIONS
+.IX Header "EXCEPTIONS"
+Exceptions produced by the \f(CW\*(C`autodie\*(C'\fR pragma are members of the
+autodie::exception class.  The preferred way to work with
+these exceptions under Perl 5.10 is as follows:
+.PP
+.Vb 2
+\&    eval {
+\&        use autodie;
+\&
+\&        open(my $fh, \*(Aq<\*(Aq, $some_file);
+\&
+\&        my @records = <$fh>;
+\&
+\&        # Do things with @records...
+\&
+\&        close($fh);
+\&    };
+\&
+\&    if ($@ and $@\->isa(\*(Aqautodie::exception\*(Aq)) {
+\&        if ($@\->matches(\*(Aqopen\*(Aq)) { print "Error from open\en";   }
+\&        if ($@\->matches(\*(Aq:io\*(Aq )) { print "Non\-open, IO error."; }
+\&    } elsif ($@) {
+\&        # A non\-autodie exception.
+\&    }
+.Ve
+.PP
+See autodie::exception for further information on interrogating
+exceptions.
+.SH CATEGORIES
+.IX Header "CATEGORIES"
+Autodie uses a simple set of categories to group together similar
+built-ins.  Requesting a category type (starting with a colon) will
+enable autodie for all built-ins beneath that category.  For example,
+requesting \f(CW\*(C`:file\*(C'\fR will enable autodie for \f(CW\*(C`close\*(C'\fR, \f(CW\*(C`fcntl\*(C'\fR,
+\&\f(CW\*(C`open\*(C'\fR and \f(CW\*(C`sysopen\*(C'\fR.
+.PP
+The categories are currently:
+.PP
+.Vb 10
+\&    :all
+\&        :default
+\&            :io
+\&                read
+\&                seek
+\&                sysread
+\&                sysseek
+\&                syswrite
+\&                :dbm
+\&                    dbmclose
+\&                    dbmopen
+\&                :file
+\&                    binmode
+\&                    close
+\&                    chmod
+\&                    chown
+\&                    fcntl
+\&                    flock
+\&                    ioctl
+\&                    open
+\&                    sysopen
+\&                    truncate
+\&                :filesys
+\&                    chdir
+\&                    closedir
+\&                    opendir
+\&                    link
+\&                    mkdir
+\&                    readlink
+\&                    rename
+\&                    rmdir
+\&                    symlink
+\&                    unlink
+\&                :ipc
+\&                    kill
+\&                    pipe
+\&                    :msg
+\&                        msgctl
+\&                        msgget
+\&                        msgrcv
+\&                        msgsnd
+\&                    :semaphore
+\&                        semctl
+\&                        semget
+\&                        semop
+\&                    :shm
+\&                        shmctl
+\&                        shmget
+\&                        shmread
+\&                :socket
+\&                    accept
+\&                    bind
+\&                    connect
+\&                    getsockopt
+\&                    listen
+\&                    recv
+\&                    send
+\&                    setsockopt
+\&                    shutdown
+\&                    socketpair
+\&            :threads
+\&                fork
+\&        :system
+\&            system
+\&            exec
+.Ve
+.PP
+Note that while the above category system is presently a strict
+hierarchy, this should not be assumed.
+.PP
+A plain \f(CW\*(C`use autodie\*(C'\fR implies \f(CW\*(C`use autodie qw(:default)\*(C'\fR.  Note that
+\&\f(CW\*(C`system\*(C'\fR and \f(CW\*(C`exec\*(C'\fR are not enabled by default.  \f(CW\*(C`system\*(C'\fR requires
+the optional IPC::System::Simple module to be installed, and enabling
+\&\f(CW\*(C`system\*(C'\fR or \f(CW\*(C`exec\*(C'\fR will invalidate their exotic forms.  See "BUGS"
+below for more details.
+.PP
+The syntax:
+.PP
+.Vb 1
+\&    use autodie qw(:1.994);
+.Ve
+.PP
+allows the \f(CW\*(C`:default\*(C'\fR list from a particular version to be used.  This
+provides the convenience of using the default methods, but the surety
+that no behavioral changes will occur if the \f(CW\*(C`autodie\*(C'\fR module is
+upgraded.
+.PP
+\&\f(CW\*(C`autodie\*(C'\fR can be enabled for all of Perl's built-ins, including
+\&\f(CW\*(C`system\*(C'\fR and \f(CW\*(C`exec\*(C'\fR with:
+.PP
+.Vb 1
+\&    use autodie qw(:all);
+.Ve
+.SH "FUNCTION SPECIFIC NOTES"
+.IX Header "FUNCTION SPECIFIC NOTES"
+.SS print
+.IX Subsection "print"
+The autodie pragma \fBdoes not check calls to \fR\f(CB\*(C`print\*(C'\fR.
+.SS flock
+.IX Subsection "flock"
+It is not considered an error for \f(CW\*(C`flock\*(C'\fR to return false if it fails
+due to an \f(CW\*(C`EWOULDBLOCK\*(C'\fR (or equivalent) condition.  This means one can
+still use the common convention of testing the return value of
+\&\f(CW\*(C`flock\*(C'\fR when called with the \f(CW\*(C`LOCK_NB\*(C'\fR option:
+.PP
+.Vb 1
+\&    use autodie;
+\&
+\&    if ( flock($fh, LOCK_EX | LOCK_NB) ) {
+\&        # We have a lock
+\&    }
+.Ve
+.PP
+Autodying \f(CW\*(C`flock\*(C'\fR will generate an exception if \f(CW\*(C`flock\*(C'\fR returns
+false with any other error.
+.SS system/exec
+.IX Subsection "system/exec"
+The \f(CW\*(C`system\*(C'\fR built-in is considered to have failed in the following
+circumstances:
+.IP \(bu 4
+The command does not start.
+.IP \(bu 4
+The command is killed by a signal.
+.IP \(bu 4
+The command returns a non-zero exit value (but see below).
+.PP
+On success, the autodying form of \f(CW\*(C`system\*(C'\fR returns the \fIexit value\fR
+rather than the contents of \f(CW$?\fR.
+.PP
+Additional allowable exit values can be supplied as an optional first
+argument to autodying \f(CW\*(C`system\*(C'\fR:
+.PP
+.Vb 1
+\&    system( [ 0, 1, 2 ], $cmd, @args);  # 0,1,2 are good exit values
+.Ve
+.PP
+\&\f(CW\*(C`autodie\*(C'\fR uses the IPC::System::Simple module to change \f(CW\*(C`system\*(C'\fR.
+See its documentation for further information.
+.PP
+Applying \f(CW\*(C`autodie\*(C'\fR to \f(CW\*(C`system\*(C'\fR or \f(CW\*(C`exec\*(C'\fR causes the exotic
+forms \f(CW\*(C`system { $cmd } @args \*(C'\fR or \f(CW\*(C`exec { $cmd } @args\*(C'\fR
+to be considered a syntax error until the end of the lexical scope.
+If you really need to use the exotic form, you can call \f(CW\*(C`CORE::system\*(C'\fR
+or \f(CW\*(C`CORE::exec\*(C'\fR instead, or use \f(CW\*(C`no autodie qw(system exec)\*(C'\fR before
+calling the exotic form.
+.SH GOTCHAS
+.IX Header "GOTCHAS"
+Functions called in list context are assumed to have failed if they
+return an empty list, or a list consisting only of a single undef
+element.
+.PP
+Some builtins (e.g. \f(CW\*(C`chdir\*(C'\fR or \f(CW\*(C`truncate\*(C'\fR) has a call signature that
+cannot completely be represented with a Perl prototype.  This means
+that some valid Perl code will be invalid under autodie.  As an example:
+.PP
+.Vb 1
+\&  chdir(BAREWORD);
+.Ve
+.PP
+Without autodie (and assuming BAREWORD is an open
+filehandle/dirhandle) this is a valid call to chdir.  But under
+autodie, \f(CW\*(C`chdir\*(C'\fR will behave like it had the prototype ";$" and thus
+BAREWORD will be a syntax error (under "use strict".  Without strict, it
+will interpreted as a filename).
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+.IP ":void cannot be used with lexical scope" 4
+.IX Item ":void cannot be used with lexical scope"
+The \f(CW\*(C`:void\*(C'\fR option is supported in Fatal, but not
+\&\f(CW\*(C`autodie\*(C'\fR.  To workaround this, \f(CW\*(C`autodie\*(C'\fR may be explicitly disabled until
+the end of the current block with \f(CW\*(C`no autodie\*(C'\fR.
+To disable autodie for only a single function (eg, open)
+use \f(CW\*(C`no autodie qw(open)\*(C'\fR.
+.Sp
+\&\f(CW\*(C`autodie\*(C'\fR performs no checking of called context to determine whether to throw
+an exception; the explicitness of error handling with \f(CW\*(C`autodie\*(C'\fR is a deliberate
+feature.
+.ie n .IP "No user hints defined for %s" 4
+.el .IP "No user hints defined for \f(CW%s\fR" 4
+.IX Item "No user hints defined for %s"
+You've insisted on hints for user-subroutines, either by pre-pending
+a \f(CW\*(C`!\*(C'\fR to the subroutine name itself, or earlier in the list of arguments
+to \f(CW\*(C`autodie\*(C'\fR.  However the subroutine in question does not have
+any hints available.
+.PP
+See also "DIAGNOSTICS" in Fatal.
+.SH "Tips and Tricks"
+.IX Header "Tips and Tricks"
+.SS "Importing autodie into another namespace than ""caller"""
+.IX Subsection "Importing autodie into another namespace than ""caller"""
+It is possible to import autodie into a different namespace by using
+Import::Into.  However, you have to pass a "caller depth" (rather
+than a package name) for this to work correctly.
+.SH BUGS
+.IX Header "BUGS"
+"Used only once" warnings can be generated when \f(CW\*(C`autodie\*(C'\fR or \f(CW\*(C`Fatal\*(C'\fR
+is used with package filehandles (eg, \f(CW\*(C`FILE\*(C'\fR).  Scalar filehandles are
+strongly recommended instead.
+.PP
+When using \f(CW\*(C`autodie\*(C'\fR or \f(CW\*(C`Fatal\*(C'\fR with user subroutines, the
+declaration of those subroutines must appear before the first use of
+\&\f(CW\*(C`Fatal\*(C'\fR or \f(CW\*(C`autodie\*(C'\fR, or have been exported from a module.
+Attempting to use \f(CW\*(C`Fatal\*(C'\fR or \f(CW\*(C`autodie\*(C'\fR on other user subroutines will
+result in a compile-time error.
+.PP
+Due to a bug in Perl, \f(CW\*(C`autodie\*(C'\fR may "lose" any format which has the
+same name as an autodying built-in or function.
+.PP
+\&\f(CW\*(C`autodie\*(C'\fR may not work correctly if used inside a file with a
+name that looks like a string eval, such as \fIeval (3)\fR.
+.SS "autodie and string eval"
+.IX Subsection "autodie and string eval"
+Due to the current implementation of \f(CW\*(C`autodie\*(C'\fR, unexpected results
+may be seen when used near or with the string version of eval.
+\&\fINone of these bugs exist when using block eval\fR.
+.PP
+Under Perl 5.8 only, \f(CW\*(C`autodie\*(C'\fR \fIdoes not\fR propagate into string \f(CW\*(C`eval\*(C'\fR
+statements, although it can be explicitly enabled inside a string
+\&\f(CW\*(C`eval\*(C'\fR.
+.PP
+Under Perl 5.10 only, using a string eval when \f(CW\*(C`autodie\*(C'\fR is in
+effect can cause the autodie behaviour to leak into the surrounding
+scope.  This can be worked around by using a \f(CW\*(C`no autodie\*(C'\fR at the
+end of the scope to explicitly remove autodie's effects, or by
+avoiding the use of string eval.
+.PP
+\&\fINone of these bugs exist when using block eval\fR.  The use of
+\&\f(CW\*(C`autodie\*(C'\fR with block eval is considered good practice.
+.SS "REPORTING BUGS"
+.IX Subsection "REPORTING BUGS"
+Please report bugs via the GitHub Issue Tracker at
+<https://github.com/pjf/autodie/issues>.
+.SH FEEDBACK
+.IX Header "FEEDBACK"
+If you find this module useful, please consider rating it on the
+CPAN Ratings service at
+<http://cpanratings.perl.org/rate?distribution=autodie> .
+.PP
+The module author loves to hear how \f(CW\*(C`autodie\*(C'\fR has made your life
+better (or worse).  Feedback can be sent to
+<pjf@perltraining.com.au>.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Copyright 2008\-2009, Paul Fenwick <pjf@perltraining.com.au>
+.SH LICENSE
+.IX Header "LICENSE"
+This module is free software.  You may distribute it under the
+same terms as Perl itself.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Fatal, autodie::exception, autodie::hints, IPC::System::Simple
+.PP
+\&\fIPerl tips, autodie\fR at
+<http://perltraining.com.au/tips/2008\-08\-20.html>
+.SH ACKNOWLEDGEMENTS
+.IX Header "ACKNOWLEDGEMENTS"
+Mark Reed and Roland Giersig \-\- Klingon translators.
+.PP
+See the \fIAUTHORS\fR file for full credits.  The latest version of this
+file can be found at
+<https://github.com/pjf/autodie/tree/master/AUTHORS> .