Debian Codegraph @

upstream/debian-unstable/man3/autodie.3perl

raw
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> .