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           use feature qw(switch);
51
52           eval {
53               use autodie;
54
55               open(my $fh, '<', $some_file);
56
57               my @records = <$fh>;
58
59               # Do things with @records...
60
61               close($fh);
62
63           };
64
65           given ($@) {
66               when (undef)   { say "No error";                    }
67               when ('open')  { say "Error from open";             }
68               when (':io')   { say "Non-open, IO error.";         }
69               when (':all')  { say "All other autodie errors."    }
70               default        { say "Not an autodie error at all." }
71           }
72
73       Under Perl 5.8, the "given/when" structure is not available, so the
74       following structure may be used:
75
76           eval {
77               use autodie;
78
79               open(my $fh, '<', $some_file);
80
81               my @records = <$fh>;
82
83               # Do things with @records...
84
85               close($fh);
86           };
87
88           if ($@ and $@->isa('autodie::exception')) {
89               if ($@->matches('open')) { print "Error from open\n";   }
90               if ($@->matches(':io' )) { print "Non-open, IO error."; }
91           } elsif ($@) {
92               # A non-autodie exception.
93           }
94
95       See autodie::exception for further information on interrogating
96       exceptions.
97

CATEGORIES

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

FUNCTION SPECIFIC NOTES

197   print
198       The autodie pragma <does not check calls to "print">.
199
200   flock
201       It is not considered an error for "flock" to return false if it fails
202       due to an "EWOULDBLOCK" (or equivalent) condition.  This means one can
203       still use the common convention of testing the return value of "flock"
204       when called with the "LOCK_NB" option:
205
206           use autodie;
207
208           if ( flock($fh, LOCK_EX | LOCK_NB) ) {
209               # We have a lock
210           }
211
212       Autodying "flock" will generate an exception if "flock" returns false
213       with any other error.
214
215   system/exec
216       The "system" built-in is considered to have failed in the following
217       circumstances:
218
219       ·   The command does not start.
220
221       ·   The command is killed by a signal.
222
223       ·   The command returns a non-zero exit value (but see below).
224
225       On success, the autodying form of "system" returns the exit value
226       rather than the contents of $?.
227
228       Additional allowable exit values can be supplied as an optional first
229       argument to autodying "system":
230
231           system( [ 0, 1, 2 ], $cmd, @args);  # 0,1,2 are good exit values
232
233       "autodie" uses the IPC::System::Simple module to change "system".  See
234       its documentation for further information.
235
236       Applying "autodie" to "system" or "exec" causes the exotic forms
237       "system { $cmd } @args " or "exec { $cmd } @args" to be considered a
238       syntax error until the end of the lexical scope.  If you really need to
239       use the exotic form, you can call "CORE::system" or "CORE::exec"
240       instead, or use "no autodie qw(system exec)" before calling the exotic
241       form.
242

GOTCHAS

244       Functions called in list context are assumed to have failed if they
245       return an empty list, or a list consisting only of a single undef
246       element.
247
248       Some builtins (e.g. "chdir" or "truncate") has a call signature that
249       cannot completely be representated with a Perl prototype.  This means
250       that some valid Perl code will be invalid under autodie.  As an
251       example:
252
253         chdir(BAREWORD);
254
255       Without autodie (and assuming BAREWORD is an open filehandle/dirhandle)
256       this is a valid call to chdir.  But under autodie, "chdir" will behave
257       like it had the prototype ";$" and thus BAREWORD will be a syntax error
258       (under "use strict".  Without strict, it will interpreted as a
259       filename).
260

DIAGNOSTICS

262       :void cannot be used with lexical scope
263           The ":void" option is supported in Fatal, but not "autodie".  To
264           workaround this, "autodie" may be explicitly disabled until the end
265           of the current block with "no autodie".  To disable autodie for
266           only a single function (eg, open) use "no autodie qw(open)".
267
268           "autodie" performs no checking of called context to determine
269           whether to throw an exception; the explicitness of error handling
270           with "autodie" is a deliberate feature.
271
272       No user hints defined for %s
273           You've insisted on hints for user-subroutines, either by pre-
274           pending a "!" to the subroutine name itself, or earlier in the list
275           of arguments to "autodie".  However the subroutine in question does
276           not have any hints available.
277
278       See also "DIAGNOSTICS" in Fatal.
279

BUGS

281       "Used only once" warnings can be generated when "autodie" or "Fatal" is
282       used with package filehandles (eg, "FILE").  Scalar filehandles are
283       strongly recommended instead.
284
285       When using "autodie" or "Fatal" with user subroutines, the declaration
286       of those subroutines must appear before the first use of "Fatal" or
287       "autodie", or have been exported from a module.  Attempting to use
288       "Fatal" or "autodie" on other user subroutines will result in a
289       compile-time error.
290
291       Due to a bug in Perl, "autodie" may "lose" any format which has the
292       same name as an autodying built-in or function.
293
294       "autodie" may not work correctly if used inside a file with a name that
295       looks like a string eval, such as eval (3).
296
297   autodie and string eval
298       Due to the current implementation of "autodie", unexpected results may
299       be seen when used near or with the string version of eval.  None of
300       these bugs exist when using block eval.
301
302       Under Perl 5.8 only, "autodie" does not propagate into string "eval"
303       statements, although it can be explicitly enabled inside a string
304       "eval".
305
306       Under Perl 5.10 only, using a string eval when "autodie" is in effect
307       can cause the autodie behaviour to leak into the surrounding scope.
308       This can be worked around by using a "no autodie" at the end of the
309       scope to explicitly remove autodie's effects, or by avoiding the use of
310       string eval.
311
312       None of these bugs exist when using block eval.  The use of "autodie"
313       with block eval is considered good practice.
314
315   REPORTING BUGS
316       Please report bugs via the GitHub Issue Tracker at
317       <https://github.com/pjf/autodie/issues> or via the CPAN Request Tracker
318       at <https://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>.
319

FEEDBACK

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

AUTHOR

329       Copyright 2008-2009, Paul Fenwick <pjf@perltraining.com.au>
330

LICENSE

332       This module is free software.  You may distribute it under the same
333       terms as Perl itself.
334

SEE ALSO

336       Fatal, autodie::exception, autodie::hints, IPC::System::Simple
337
338       Perl tips, autodie at <http://perltraining.com.au/tips/2008-08-20.html>
339

ACKNOWLEDGEMENTS

341       Mark Reed and Roland Giersig -- Klingon translators.
342
343       See the AUTHORS file for full credits.  The latest version of this file
344       can be found at <https://github.com/pjf/autodie/tree/master/AUTHORS> .
345
346
347
348perl v5.26.3                      2015-07-09                        autodie(3)
Impressum