1autodie(3)            User Contributed Perl Documentation           autodie(3)
2
3
4

NAME

6       autodie - Replace functions with ones that succeed or die with lexical
7       scope
8

SYNOPSIS

10           use autodie;            # Recommended: implies 'use autodie qw(:default)'
11
12           use autodie qw(:all);   # Recommended more: defaults and system/exec.
13
14           use autodie qw(open close);   # open/close succeed or die
15
16           open(my $fh, "<", $filename); # No need to check!
17
18           {
19               no autodie qw(open);          # open failures won't die
20               open(my $fh, "<", $filename); # Could fail silently!
21               no autodie;                   # disable all autodies
22           }
23
24           print "Hello World" or die $!;    # autodie DOESN'T check print!
25

DESCRIPTION

27               bIlujDI' yIchegh()Qo'; yIHegh()!
28
29               It is better to die() than to return() in failure.
30
31                       -- Klingon programming proverb.
32
33       The "autodie" pragma provides a convenient way to replace functions
34       that normally return false on failure with equivalents that throw an
35       exception on failure.
36
37       The "autodie" pragma has lexical scope, meaning that functions and
38       subroutines altered with "autodie" will only change their behaviour
39       until the end of the enclosing block, file, or "eval".
40
41       If "system" is specified as an argument to "autodie", then it uses
42       IPC::System::Simple to do the heavy lifting.  See the description of
43       that module for more information.
44

EXCEPTIONS

46       Exceptions produced by the "autodie" pragma are members of the
47       autodie::exception class.  The preferred way to work with these
48       exceptions under Perl 5.10 is as follows:
49
50           eval {
51               use autodie;
52
53               open(my $fh, '<', $some_file);
54
55               my @records = <$fh>;
56
57               # Do things with @records...
58
59               close($fh);
60           };
61
62           if ($@ and $@->isa('autodie::exception')) {
63               if ($@->matches('open')) { print "Error from open\n";   }
64               if ($@->matches(':io' )) { print "Non-open, IO error."; }
65           } elsif ($@) {
66               # A non-autodie exception.
67           }
68
69       See autodie::exception for further information on interrogating
70       exceptions.
71

CATEGORIES

73       Autodie uses a simple set of categories to group together similar
74       built-ins.  Requesting a category type (starting with a colon) will
75       enable autodie for all built-ins beneath that category.  For example,
76       requesting ":file" will enable autodie for "close", "fcntl", "open" and
77       "sysopen".
78
79       The categories are currently:
80
81           :all
82               :default
83                   :io
84                       read
85                       seek
86                       sysread
87                       sysseek
88                       syswrite
89                       :dbm
90                           dbmclose
91                           dbmopen
92                       :file
93                           binmode
94                           close
95                           chmod
96                           chown
97                           fcntl
98                           flock
99                           ioctl
100                           open
101                           sysopen
102                           truncate
103                       :filesys
104                           chdir
105                           closedir
106                           opendir
107                           link
108                           mkdir
109                           readlink
110                           rename
111                           rmdir
112                           symlink
113                           unlink
114                       :ipc
115                           kill
116                           pipe
117                           :msg
118                               msgctl
119                               msgget
120                               msgrcv
121                               msgsnd
122                           :semaphore
123                               semctl
124                               semget
125                               semop
126                           :shm
127                               shmctl
128                               shmget
129                               shmread
130                       :socket
131                           accept
132                           bind
133                           connect
134                           getsockopt
135                           listen
136                           recv
137                           send
138                           setsockopt
139                           shutdown
140                           socketpair
141                   :threads
142                       fork
143               :system
144                   system
145                   exec
146
147       Note that while the above category system is presently a strict
148       hierarchy, this should not be assumed.
149
150       A plain "use autodie" implies "use autodie qw(:default)".  Note that
151       "system" and "exec" are not enabled by default.  "system" requires the
152       optional IPC::System::Simple module to be installed, and enabling
153       "system" or "exec" will invalidate their exotic forms.  See "BUGS"
154       below for more details.
155
156       The syntax:
157
158           use autodie qw(:1.994);
159
160       allows the ":default" list from a particular version to be used.  This
161       provides the convenience of using the default methods, but the surety
162       that no behavioral changes will occur if the "autodie" module is
163       upgraded.
164
165       "autodie" can be enabled for all of Perl's built-ins, including
166       "system" and "exec" with:
167
168           use autodie qw(:all);
169

FUNCTION SPECIFIC NOTES

171   print
172       The autodie pragma does not check calls to "print".
173
174   flock
175       It is not considered an error for "flock" to return false if it fails
176       due to an "EWOULDBLOCK" (or equivalent) condition.  This means one can
177       still use the common convention of testing the return value of "flock"
178       when called with the "LOCK_NB" option:
179
180           use autodie;
181
182           if ( flock($fh, LOCK_EX | LOCK_NB) ) {
183               # We have a lock
184           }
185
186       Autodying "flock" will generate an exception if "flock" returns false
187       with any other error.
188
189   system/exec
190       The "system" built-in is considered to have failed in the following
191       circumstances:
192
193       •   The command does not start.
194
195       •   The command is killed by a signal.
196
197       •   The command returns a non-zero exit value (but see below).
198
199       On success, the autodying form of "system" returns the exit value
200       rather than the contents of $?.
201
202       Additional allowable exit values can be supplied as an optional first
203       argument to autodying "system":
204
205           system( [ 0, 1, 2 ], $cmd, @args);  # 0,1,2 are good exit values
206
207       "autodie" uses the IPC::System::Simple module to change "system".  See
208       its documentation for further information.
209
210       Applying "autodie" to "system" or "exec" causes the exotic forms
211       "system { $cmd } @args " or "exec { $cmd } @args" to be considered a
212       syntax error until the end of the lexical scope.  If you really need to
213       use the exotic form, you can call "CORE::system" or "CORE::exec"
214       instead, or use "no autodie qw(system exec)" before calling the exotic
215       form.
216

GOTCHAS

218       Functions called in list context are assumed to have failed if they
219       return an empty list, or a list consisting only of a single undef
220       element.
221
222       Some builtins (e.g. "chdir" or "truncate") has a call signature that
223       cannot completely be represented with a Perl prototype.  This means
224       that some valid Perl code will be invalid under autodie.  As an
225       example:
226
227         chdir(BAREWORD);
228
229       Without autodie (and assuming BAREWORD is an open filehandle/dirhandle)
230       this is a valid call to chdir.  But under autodie, "chdir" will behave
231       like it had the prototype ";$" and thus BAREWORD will be a syntax error
232       (under "use strict".  Without strict, it will interpreted as a
233       filename).
234

DIAGNOSTICS

236       :void cannot be used with lexical scope
237           The ":void" option is supported in Fatal, but not "autodie".  To
238           workaround this, "autodie" may be explicitly disabled until the end
239           of the current block with "no autodie".  To disable autodie for
240           only a single function (eg, open) use "no autodie qw(open)".
241
242           "autodie" performs no checking of called context to determine
243           whether to throw an exception; the explicitness of error handling
244           with "autodie" is a deliberate feature.
245
246       No user hints defined for %s
247           You've insisted on hints for user-subroutines, either by pre-
248           pending a "!" to the subroutine name itself, or earlier in the list
249           of arguments to "autodie".  However the subroutine in question does
250           not have any hints available.
251
252       See also "DIAGNOSTICS" in Fatal.
253

Tips and Tricks

255   Importing autodie into another namespace than "caller"
256       It is possible to import autodie into a different namespace by using
257       Import::Into.  However, you have to pass a "caller depth" (rather than
258       a package name) for this to work correctly.
259

BUGS

261       "Used only once" warnings can be generated when "autodie" or "Fatal" is
262       used with package filehandles (eg, "FILE").  Scalar filehandles are
263       strongly recommended instead.
264
265       When using "autodie" or "Fatal" with user subroutines, the declaration
266       of those subroutines must appear before the first use of "Fatal" or
267       "autodie", or have been exported from a module.  Attempting to use
268       "Fatal" or "autodie" on other user subroutines will result in a
269       compile-time error.
270
271       Due to a bug in Perl, "autodie" may "lose" any format which has the
272       same name as an autodying built-in or function.
273
274       "autodie" may not work correctly if used inside a file with a name that
275       looks like a string eval, such as eval (3).
276
277   autodie and string eval
278       Due to the current implementation of "autodie", unexpected results may
279       be seen when used near or with the string version of eval.  None of
280       these bugs exist when using block eval.
281
282       Under Perl 5.8 only, "autodie" does not propagate into string "eval"
283       statements, although it can be explicitly enabled inside a string
284       "eval".
285
286       Under Perl 5.10 only, using a string eval when "autodie" is in effect
287       can cause the autodie behaviour to leak into the surrounding scope.
288       This can be worked around by using a "no autodie" at the end of the
289       scope to explicitly remove autodie's effects, or by avoiding the use of
290       string eval.
291
292       None of these bugs exist when using block eval.  The use of "autodie"
293       with block eval is considered good practice.
294
295   REPORTING BUGS
296       Please report bugs via the GitHub Issue Tracker at
297       <https://github.com/pjf/autodie/issues>.
298

FEEDBACK

300       If you find this module useful, please consider rating it on the CPAN
301       Ratings service at
302       <http://cpanratings.perl.org/rate?distribution=autodie> .
303
304       The module author loves to hear how "autodie" has made your life better
305       (or worse).  Feedback can be sent to <pjf@perltraining.com.au>.
306

AUTHOR

308       Copyright 2008-2009, Paul Fenwick <pjf@perltraining.com.au>
309

LICENSE

311       This module is free software.  You may distribute it under the same
312       terms as Perl itself.
313

SEE ALSO

315       Fatal, autodie::exception, autodie::hints, IPC::System::Simple
316
317       Perl tips, autodie at <http://perltraining.com.au/tips/2008-08-20.html>
318

ACKNOWLEDGEMENTS

320       Mark Reed and Roland Giersig -- Klingon translators.
321
322       See the AUTHORS file for full credits.  The latest version of this file
323       can be found at <https://github.com/pjf/autodie/tree/master/AUTHORS> .
324
325
326
327perl v5.34.0                      2022-01-21                        autodie(3)
Impressum