1autodie(3) User Contributed Perl Documentation autodie(3)
2
6 autodie - Replace functions with ones that succeed or die with lexical
7 scope
8
10 use autodie; # Recommended: implies 'use autodie qw(:default)'
11 use autodie qw(:all); # Recommended more: defaults and system/exec.
13 use autodie qw(open close); # open/close succeed or die
15 open(my $fh, "<", $filename); # No need to check!
17 {
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 print "Hello World" or die $!; # autodie DOESN'T check print!
25
27 bIlujDI' yIchegh()Qo'; yIHegh()!
28 It is better to die() than to return() in failure.
30 -- Klingon programming proverb.
32 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 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 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
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 eval {
51 use autodie;
52 open(my $fh, '<', $some_file);
54 my @records = <$fh>;
56 # Do things with @records...
58 close($fh);
60 };
61 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 See autodie::exception for further information on interrogating
70 exceptions.
71
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 The categories are currently:
80 :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 Note that while the above category system is presently a strict
148 hierarchy, this should not be assumed.
149 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 The syntax:
157 use autodie qw(:1.994);
159 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 "autodie" can be enabled for all of Perl's built-ins, including
166 "system" and "exec" with:
167 use autodie qw(:all);
169
171 print
172 The autodie pragma does not check calls to "print".
173 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 use autodie;
181 if ( flock($fh, LOCK_EX | LOCK_NB) ) {
183 # We have a lock
184 }
185 Autodying "flock" will generate an exception if "flock" returns false
187 with any other error.
188 system/exec
190 The "system" built-in is considered to have failed in the following
191 circumstances:
192 • The command does not start.
194 • The command is killed by a signal.
196 • The command returns a non-zero exit value (but see below).
198 On success, the autodying form of "system" returns the exit value
200 rather than the contents of $?.
201 Additional allowable exit values can be supplied as an optional first
203 argument to autodying "system":
204 system( [ 0, 1, 2 ], $cmd, @args); # 0,1,2 are good exit values
206 "autodie" uses the IPC::System::Simple module to change "system". See
208 its documentation for further information.
209 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
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 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 chdir(BAREWORD);
228 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
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 "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 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 See also "DIAGNOSTICS" in Fatal.
253
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
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 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 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 "autodie" may not work correctly if used inside a file with a name that
275 looks like a string eval, such as eval [4m(3).
276 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 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 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 None of these bugs exist when using block eval. The use of "autodie"
293 with block eval is considered good practice.
294 REPORTING BUGS
296 Please report bugs via the GitHub Issue Tracker at
297 <https://github.com/pjf/autodie/issues>.
298
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 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
308 Copyright 2008-2009, Paul Fenwick <pjf@perltraining.com.au>
309
311 This module is free software. You may distribute it under the same
312 terms as Perl itself.
313
315 Fatal, autodie::exception, autodie::hints, IPC::System::Simple
316 Perl tips, autodie at <http://perltraining.com.au/tips/2008-08-20.html>
318
320 Mark Reed and Roland Giersig -- Klingon translators.
321 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> .
324perl v5.36.0 2023-01-30 autodie(3)