| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "autodie 3perl" |
| 58 |
.TH autodie 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
autodie \- Replace functions with ones that succeed or die with lexical scope |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use autodie; # Recommended: implies \*(Aquse autodie qw(:default)\*(Aq |
| 69 |
\& |
| 70 |
\& use autodie qw(:all); # Recommended more: defaults and system/exec. |
| 71 |
\& |
| 72 |
\& use autodie qw(open close); # open/close succeed or die |
| 73 |
\& |
| 74 |
\& open(my $fh, "<", $filename); # No need to check! |
| 75 |
\& |
| 76 |
\& { |
| 77 |
\& no autodie qw(open); # open failures won\*(Aqt die |
| 78 |
\& open(my $fh, "<", $filename); # Could fail silently! |
| 79 |
\& no autodie; # disable all autodies |
| 80 |
\& } |
| 81 |
\& |
| 82 |
\& print "Hello World" or die $!; # autodie DOESN\*(AqT check print! |
| 83 |
.Ve |
| 84 |
.SH DESCRIPTION |
| 85 |
.IX Header "DESCRIPTION" |
| 86 |
.Vb 1 |
| 87 |
\& bIlujDI\*(Aq yIchegh()Qo\*(Aq; yIHegh()! |
| 88 |
\& |
| 89 |
\& It is better to die() than to return() in failure. |
| 90 |
\& |
| 91 |
\& \-\- Klingon programming proverb. |
| 92 |
.Ve |
| 93 |
.PP |
| 94 |
The \f(CW\*(C`autodie\*(C'\fR pragma provides a convenient way to replace functions |
| 95 |
that normally return false on failure with equivalents that throw |
| 96 |
an exception on failure. |
| 97 |
.PP |
| 98 |
The \f(CW\*(C`autodie\*(C'\fR pragma has \fIlexical scope\fR, meaning that functions |
| 99 |
and subroutines altered with \f(CW\*(C`autodie\*(C'\fR will only change their behaviour |
| 100 |
until the end of the enclosing block, file, or \f(CW\*(C`eval\*(C'\fR. |
| 101 |
.PP |
| 102 |
If \f(CW\*(C`system\*(C'\fR is specified as an argument to \f(CW\*(C`autodie\*(C'\fR, then it |
| 103 |
uses IPC::System::Simple to do the heavy lifting. See the |
| 104 |
description of that module for more information. |
| 105 |
.SH EXCEPTIONS |
| 106 |
.IX Header "EXCEPTIONS" |
| 107 |
Exceptions produced by the \f(CW\*(C`autodie\*(C'\fR pragma are members of the |
| 108 |
autodie::exception class. The preferred way to work with |
| 109 |
these exceptions under Perl 5.10 is as follows: |
| 110 |
.PP |
| 111 |
.Vb 2 |
| 112 |
\& eval { |
| 113 |
\& use autodie; |
| 114 |
\& |
| 115 |
\& open(my $fh, \*(Aq<\*(Aq, $some_file); |
| 116 |
\& |
| 117 |
\& my @records = <$fh>; |
| 118 |
\& |
| 119 |
\& # Do things with @records... |
| 120 |
\& |
| 121 |
\& close($fh); |
| 122 |
\& }; |
| 123 |
\& |
| 124 |
\& if ($@ and $@\->isa(\*(Aqautodie::exception\*(Aq)) { |
| 125 |
\& if ($@\->matches(\*(Aqopen\*(Aq)) { print "Error from open\en"; } |
| 126 |
\& if ($@\->matches(\*(Aq:io\*(Aq )) { print "Non\-open, IO error."; } |
| 127 |
\& } elsif ($@) { |
| 128 |
\& # A non\-autodie exception. |
| 129 |
\& } |
| 130 |
.Ve |
| 131 |
.PP |
| 132 |
See autodie::exception for further information on interrogating |
| 133 |
exceptions. |
| 134 |
.SH CATEGORIES |
| 135 |
.IX Header "CATEGORIES" |
| 136 |
Autodie uses a simple set of categories to group together similar |
| 137 |
built-ins. Requesting a category type (starting with a colon) will |
| 138 |
enable autodie for all built-ins beneath that category. For example, |
| 139 |
requesting \f(CW\*(C`:file\*(C'\fR will enable autodie for \f(CW\*(C`close\*(C'\fR, \f(CW\*(C`fcntl\*(C'\fR, |
| 140 |
\&\f(CW\*(C`open\*(C'\fR and \f(CW\*(C`sysopen\*(C'\fR. |
| 141 |
.PP |
| 142 |
The categories are currently: |
| 143 |
.PP |
| 144 |
.Vb 10 |
| 145 |
\& :all |
| 146 |
\& :default |
| 147 |
\& :io |
| 148 |
\& read |
| 149 |
\& seek |
| 150 |
\& sysread |
| 151 |
\& sysseek |
| 152 |
\& syswrite |
| 153 |
\& :dbm |
| 154 |
\& dbmclose |
| 155 |
\& dbmopen |
| 156 |
\& :file |
| 157 |
\& binmode |
| 158 |
\& close |
| 159 |
\& chmod |
| 160 |
\& chown |
| 161 |
\& fcntl |
| 162 |
\& flock |
| 163 |
\& ioctl |
| 164 |
\& open |
| 165 |
\& sysopen |
| 166 |
\& truncate |
| 167 |
\& :filesys |
| 168 |
\& chdir |
| 169 |
\& closedir |
| 170 |
\& opendir |
| 171 |
\& link |
| 172 |
\& mkdir |
| 173 |
\& readlink |
| 174 |
\& rename |
| 175 |
\& rmdir |
| 176 |
\& symlink |
| 177 |
\& unlink |
| 178 |
\& :ipc |
| 179 |
\& kill |
| 180 |
\& pipe |
| 181 |
\& :msg |
| 182 |
\& msgctl |
| 183 |
\& msgget |
| 184 |
\& msgrcv |
| 185 |
\& msgsnd |
| 186 |
\& :semaphore |
| 187 |
\& semctl |
| 188 |
\& semget |
| 189 |
\& semop |
| 190 |
\& :shm |
| 191 |
\& shmctl |
| 192 |
\& shmget |
| 193 |
\& shmread |
| 194 |
\& :socket |
| 195 |
\& accept |
| 196 |
\& bind |
| 197 |
\& connect |
| 198 |
\& getsockopt |
| 199 |
\& listen |
| 200 |
\& recv |
| 201 |
\& send |
| 202 |
\& setsockopt |
| 203 |
\& shutdown |
| 204 |
\& socketpair |
| 205 |
\& :threads |
| 206 |
\& fork |
| 207 |
\& :system |
| 208 |
\& system |
| 209 |
\& exec |
| 210 |
.Ve |
| 211 |
.PP |
| 212 |
Note that while the above category system is presently a strict |
| 213 |
hierarchy, this should not be assumed. |
| 214 |
.PP |
| 215 |
A plain \f(CW\*(C`use autodie\*(C'\fR implies \f(CW\*(C`use autodie qw(:default)\*(C'\fR. Note that |
| 216 |
\&\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 |
| 217 |
the optional IPC::System::Simple module to be installed, and enabling |
| 218 |
\&\f(CW\*(C`system\*(C'\fR or \f(CW\*(C`exec\*(C'\fR will invalidate their exotic forms. See "BUGS" |
| 219 |
below for more details. |
| 220 |
.PP |
| 221 |
The syntax: |
| 222 |
.PP |
| 223 |
.Vb 1 |
| 224 |
\& use autodie qw(:1.994); |
| 225 |
.Ve |
| 226 |
.PP |
| 227 |
allows the \f(CW\*(C`:default\*(C'\fR list from a particular version to be used. This |
| 228 |
provides the convenience of using the default methods, but the surety |
| 229 |
that no behavioral changes will occur if the \f(CW\*(C`autodie\*(C'\fR module is |
| 230 |
upgraded. |
| 231 |
.PP |
| 232 |
\&\f(CW\*(C`autodie\*(C'\fR can be enabled for all of Perl's built-ins, including |
| 233 |
\&\f(CW\*(C`system\*(C'\fR and \f(CW\*(C`exec\*(C'\fR with: |
| 234 |
.PP |
| 235 |
.Vb 1 |
| 236 |
\& use autodie qw(:all); |
| 237 |
.Ve |
| 238 |
.SH "FUNCTION SPECIFIC NOTES" |
| 239 |
.IX Header "FUNCTION SPECIFIC NOTES" |
| 240 |
.SS print |
| 241 |
.IX Subsection "print" |
| 242 |
The autodie pragma \fBdoes not check calls to \fR\f(CB\*(C`print\*(C'\fR. |
| 243 |
.SS flock |
| 244 |
.IX Subsection "flock" |
| 245 |
It is not considered an error for \f(CW\*(C`flock\*(C'\fR to return false if it fails |
| 246 |
due to an \f(CW\*(C`EWOULDBLOCK\*(C'\fR (or equivalent) condition. This means one can |
| 247 |
still use the common convention of testing the return value of |
| 248 |
\&\f(CW\*(C`flock\*(C'\fR when called with the \f(CW\*(C`LOCK_NB\*(C'\fR option: |
| 249 |
.PP |
| 250 |
.Vb 1 |
| 251 |
\& use autodie; |
| 252 |
\& |
| 253 |
\& if ( flock($fh, LOCK_EX | LOCK_NB) ) { |
| 254 |
\& # We have a lock |
| 255 |
\& } |
| 256 |
.Ve |
| 257 |
.PP |
| 258 |
Autodying \f(CW\*(C`flock\*(C'\fR will generate an exception if \f(CW\*(C`flock\*(C'\fR returns |
| 259 |
false with any other error. |
| 260 |
.SS system/exec |
| 261 |
.IX Subsection "system/exec" |
| 262 |
The \f(CW\*(C`system\*(C'\fR built-in is considered to have failed in the following |
| 263 |
circumstances: |
| 264 |
.IP \(bu 4 |
| 265 |
The command does not start. |
| 266 |
.IP \(bu 4 |
| 267 |
The command is killed by a signal. |
| 268 |
.IP \(bu 4 |
| 269 |
The command returns a non-zero exit value (but see below). |
| 270 |
.PP |
| 271 |
On success, the autodying form of \f(CW\*(C`system\*(C'\fR returns the \fIexit value\fR |
| 272 |
rather than the contents of \f(CW$?\fR. |
| 273 |
.PP |
| 274 |
Additional allowable exit values can be supplied as an optional first |
| 275 |
argument to autodying \f(CW\*(C`system\*(C'\fR: |
| 276 |
.PP |
| 277 |
.Vb 1 |
| 278 |
\& system( [ 0, 1, 2 ], $cmd, @args); # 0,1,2 are good exit values |
| 279 |
.Ve |
| 280 |
.PP |
| 281 |
\&\f(CW\*(C`autodie\*(C'\fR uses the IPC::System::Simple module to change \f(CW\*(C`system\*(C'\fR. |
| 282 |
See its documentation for further information. |
| 283 |
.PP |
| 284 |
Applying \f(CW\*(C`autodie\*(C'\fR to \f(CW\*(C`system\*(C'\fR or \f(CW\*(C`exec\*(C'\fR causes the exotic |
| 285 |
forms \f(CW\*(C`system { $cmd } @args \*(C'\fR or \f(CW\*(C`exec { $cmd } @args\*(C'\fR |
| 286 |
to be considered a syntax error until the end of the lexical scope. |
| 287 |
If you really need to use the exotic form, you can call \f(CW\*(C`CORE::system\*(C'\fR |
| 288 |
or \f(CW\*(C`CORE::exec\*(C'\fR instead, or use \f(CW\*(C`no autodie qw(system exec)\*(C'\fR before |
| 289 |
calling the exotic form. |
| 290 |
.SH GOTCHAS |
| 291 |
.IX Header "GOTCHAS" |
| 292 |
Functions called in list context are assumed to have failed if they |
| 293 |
return an empty list, or a list consisting only of a single undef |
| 294 |
element. |
| 295 |
.PP |
| 296 |
Some builtins (e.g. \f(CW\*(C`chdir\*(C'\fR or \f(CW\*(C`truncate\*(C'\fR) has a call signature that |
| 297 |
cannot completely be represented with a Perl prototype. This means |
| 298 |
that some valid Perl code will be invalid under autodie. As an example: |
| 299 |
.PP |
| 300 |
.Vb 1 |
| 301 |
\& chdir(BAREWORD); |
| 302 |
.Ve |
| 303 |
.PP |
| 304 |
Without autodie (and assuming BAREWORD is an open |
| 305 |
filehandle/dirhandle) this is a valid call to chdir. But under |
| 306 |
autodie, \f(CW\*(C`chdir\*(C'\fR will behave like it had the prototype ";$" and thus |
| 307 |
BAREWORD will be a syntax error (under "use strict". Without strict, it |
| 308 |
will interpreted as a filename). |
| 309 |
.SH DIAGNOSTICS |
| 310 |
.IX Header "DIAGNOSTICS" |
| 311 |
.IP ":void cannot be used with lexical scope" 4 |
| 312 |
.IX Item ":void cannot be used with lexical scope" |
| 313 |
The \f(CW\*(C`:void\*(C'\fR option is supported in Fatal, but not |
| 314 |
\&\f(CW\*(C`autodie\*(C'\fR. To workaround this, \f(CW\*(C`autodie\*(C'\fR may be explicitly disabled until |
| 315 |
the end of the current block with \f(CW\*(C`no autodie\*(C'\fR. |
| 316 |
To disable autodie for only a single function (eg, open) |
| 317 |
use \f(CW\*(C`no autodie qw(open)\*(C'\fR. |
| 318 |
.Sp |
| 319 |
\&\f(CW\*(C`autodie\*(C'\fR performs no checking of called context to determine whether to throw |
| 320 |
an exception; the explicitness of error handling with \f(CW\*(C`autodie\*(C'\fR is a deliberate |
| 321 |
feature. |
| 322 |
.ie n .IP "No user hints defined for %s" 4 |
| 323 |
.el .IP "No user hints defined for \f(CW%s\fR" 4 |
| 324 |
.IX Item "No user hints defined for %s" |
| 325 |
You've insisted on hints for user-subroutines, either by pre-pending |
| 326 |
a \f(CW\*(C`!\*(C'\fR to the subroutine name itself, or earlier in the list of arguments |
| 327 |
to \f(CW\*(C`autodie\*(C'\fR. However the subroutine in question does not have |
| 328 |
any hints available. |
| 329 |
.PP |
| 330 |
See also "DIAGNOSTICS" in Fatal. |
| 331 |
.SH "Tips and Tricks" |
| 332 |
.IX Header "Tips and Tricks" |
| 333 |
.SS "Importing autodie into another namespace than ""caller""" |
| 334 |
.IX Subsection "Importing autodie into another namespace than ""caller""" |
| 335 |
It is possible to import autodie into a different namespace by using |
| 336 |
Import::Into. However, you have to pass a "caller depth" (rather |
| 337 |
than a package name) for this to work correctly. |
| 338 |
.SH BUGS |
| 339 |
.IX Header "BUGS" |
| 340 |
"Used only once" warnings can be generated when \f(CW\*(C`autodie\*(C'\fR or \f(CW\*(C`Fatal\*(C'\fR |
| 341 |
is used with package filehandles (eg, \f(CW\*(C`FILE\*(C'\fR). Scalar filehandles are |
| 342 |
strongly recommended instead. |
| 343 |
.PP |
| 344 |
When using \f(CW\*(C`autodie\*(C'\fR or \f(CW\*(C`Fatal\*(C'\fR with user subroutines, the |
| 345 |
declaration of those subroutines must appear before the first use of |
| 346 |
\&\f(CW\*(C`Fatal\*(C'\fR or \f(CW\*(C`autodie\*(C'\fR, or have been exported from a module. |
| 347 |
Attempting to use \f(CW\*(C`Fatal\*(C'\fR or \f(CW\*(C`autodie\*(C'\fR on other user subroutines will |
| 348 |
result in a compile-time error. |
| 349 |
.PP |
| 350 |
Due to a bug in Perl, \f(CW\*(C`autodie\*(C'\fR may "lose" any format which has the |
| 351 |
same name as an autodying built-in or function. |
| 352 |
.PP |
| 353 |
\&\f(CW\*(C`autodie\*(C'\fR may not work correctly if used inside a file with a |
| 354 |
name that looks like a string eval, such as \fIeval (3)\fR. |
| 355 |
.SS "autodie and string eval" |
| 356 |
.IX Subsection "autodie and string eval" |
| 357 |
Due to the current implementation of \f(CW\*(C`autodie\*(C'\fR, unexpected results |
| 358 |
may be seen when used near or with the string version of eval. |
| 359 |
\&\fINone of these bugs exist when using block eval\fR. |
| 360 |
.PP |
| 361 |
Under Perl 5.8 only, \f(CW\*(C`autodie\*(C'\fR \fIdoes not\fR propagate into string \f(CW\*(C`eval\*(C'\fR |
| 362 |
statements, although it can be explicitly enabled inside a string |
| 363 |
\&\f(CW\*(C`eval\*(C'\fR. |
| 364 |
.PP |
| 365 |
Under Perl 5.10 only, using a string eval when \f(CW\*(C`autodie\*(C'\fR is in |
| 366 |
effect can cause the autodie behaviour to leak into the surrounding |
| 367 |
scope. This can be worked around by using a \f(CW\*(C`no autodie\*(C'\fR at the |
| 368 |
end of the scope to explicitly remove autodie's effects, or by |
| 369 |
avoiding the use of string eval. |
| 370 |
.PP |
| 371 |
\&\fINone of these bugs exist when using block eval\fR. The use of |
| 372 |
\&\f(CW\*(C`autodie\*(C'\fR with block eval is considered good practice. |
| 373 |
.SS "REPORTING BUGS" |
| 374 |
.IX Subsection "REPORTING BUGS" |
| 375 |
Please report bugs via the GitHub Issue Tracker at |
| 376 |
<https://github.com/pjf/autodie/issues>. |
| 377 |
.SH FEEDBACK |
| 378 |
.IX Header "FEEDBACK" |
| 379 |
If you find this module useful, please consider rating it on metacpan at |
| 380 |
<https://metacpan.org/pod/autodie> . |
| 381 |
.PP |
| 382 |
The module author loves to hear how \f(CW\*(C`autodie\*(C'\fR has made your life |
| 383 |
better (or worse). Feedback can be sent to |
| 384 |
<[email protected]>. |
| 385 |
.SH AUTHOR |
| 386 |
.IX Header "AUTHOR" |
| 387 |
Copyright 2008\-2009, Paul Fenwick <[email protected]> |
| 388 |
.SH LICENSE |
| 389 |
.IX Header "LICENSE" |
| 390 |
This module is free software. You may distribute it under the |
| 391 |
same terms as Perl itself. |
| 392 |
.SH "SEE ALSO" |
| 393 |
.IX Header "SEE ALSO" |
| 394 |
Fatal, autodie::exception, autodie::hints, IPC::System::Simple |
| 395 |
.PP |
| 396 |
\&\fIPerl tips, autodie\fR at |
| 397 |
<http://perltraining.com.au/tips/2008\-08\-20.html> |
| 398 |
.SH ACKNOWLEDGEMENTS |
| 399 |
.IX Header "ACKNOWLEDGEMENTS" |
| 400 |
Mark Reed and Roland Giersig \-\- Klingon translators. |
| 401 |
.PP |
| 402 |
See the \fIAUTHORS\fR file for full credits. The latest version of this |
| 403 |
file can be found at |
| 404 |
<https://github.com/pjf/autodie/tree/master/AUTHORS> . |