1autodie(3pm)           Perl Programmers Reference Guide           autodie(3pm)
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

DESCRIPTION

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

EXCEPTIONS

44       Exceptions produced by the "autodie" pragma are members of the
45       autodie::exception class.  The preferred way to work with these
46       exceptions under Perl 5.10 is as follows:
47
48           use feature qw(switch);
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
63           given ($@) {
64               when (undef)   { say "No error";                    }
65               when ('open')  { say "Error from open";             }
66               when (':io')   { say "Non-open, IO error.";         }
67               when (':all')  { say "All other autodie errors."    }
68               default        { say "Not an autodie error at all." }
69           }
70
71       Under Perl 5.8, the "given/when" structure is not available, so the
72       following structure may be used:
73
74           eval {
75               use autodie;
76
77               open(my $fh, '<', $some_file);
78
79               my @records = <$fh>;
80
81               # Do things with @records...
82
83               close($fh);
84           };
85
86           if ($@ and $@->isa('autodie::exception')) {
87               if ($@->matches('open')) { print "Error from open\n";   }
88               if ($@->matches(':io' )) { print "Non-open, IO error."; }
89           } elsif ($@) {
90               # A non-autodie exception.
91           }
92
93       See autodie::exception for further information on interrogating
94       exceptions.
95

CATEGORIES

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

FUNCTION SPECIFIC NOTES

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

GOTCHAS

237       Functions called in list context are assumed to have failed if they
238       return an empty list, or a list consisting only of a single undef
239       element.
240

DIAGNOSTICS

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

BUGS

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

FEEDBACK

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

AUTHOR

304       Copyright 2008-2009, Paul Fenwick <pjf@perltraining.com.au>
305

LICENSE

307       This module is free software.  You may distribute it under the same
308       terms as Perl itself.
309

SEE ALSO

311       Fatal, autodie::exception, autodie::hints, IPC::System::Simple
312
313       Perl tips, autodie at http://perltraining.com.au/tips/2008-08-20.html
314       <http://perltraining.com.au/tips/2008-08-20.html>
315

ACKNOWLEDGEMENTS

317       Mark Reed and Roland Giersig -- Klingon translators.
318
319       See the AUTHORS file for full credits.  The latest version of this file
320       can be found at
321       <http://github.com/pfenwick/autodie/tree/master/AUTHORS> .
322
323
324
325perl v5.12.4                      2011-06-07                      autodie(3pm)
Impressum