From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/mageia-cauldron/man3pm/autodie.3pm | 405 ++++++++++++++++++++++++++++ 1 file changed, 405 insertions(+) create mode 100644 upstream/mageia-cauldron/man3pm/autodie.3pm (limited to 'upstream/mageia-cauldron/man3pm/autodie.3pm') diff --git a/upstream/mageia-cauldron/man3pm/autodie.3pm b/upstream/mageia-cauldron/man3pm/autodie.3pm new file mode 100644 index 00000000..2ebb3bdc --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/autodie.3pm @@ -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 3pm" +.TH autodie 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 +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 +. +.SH FEEDBACK +.IX Header "FEEDBACK" +If you find this module useful, please consider rating it on the +CPAN Ratings service at + . +.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 +. +.SH AUTHOR +.IX Header "AUTHOR" +Copyright 2008\-2009, Paul Fenwick +.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 + +.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 + . -- cgit v1.2.3