Debian Codegraph @

upstream/mageia-cauldron/man3pm/autodie.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "autodie 3pm"
61 .TH autodie 3pm 2023-12-30 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 autodie \- Replace functions with ones that succeed or die with lexical scope
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use autodie; # Recommended: implies \*(Aquse autodie qw(:default)\*(Aq
72 \&
73 \& use autodie qw(:all); # Recommended more: defaults and system/exec.
74 \&
75 \& use autodie qw(open close); # open/close succeed or die
76 \&
77 \& open(my $fh, "<", $filename); # No need to check!
78 \&
79 \& {
80 \& no autodie qw(open); # open failures won\*(Aqt die
81 \& open(my $fh, "<", $filename); # Could fail silently!
82 \& no autodie; # disable all autodies
83 \& }
84 \&
85 \& print "Hello World" or die $!; # autodie DOESN\*(AqT check print!
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 .Vb 1
90 \& bIlujDI\*(Aq yIchegh()Qo\*(Aq; yIHegh()!
91 \&
92 \& It is better to die() than to return() in failure.
93 \&
94 \& \-\- Klingon programming proverb.
95 .Ve
96 .PP
97 The \f(CW\*(C`autodie\*(C'\fR pragma provides a convenient way to replace functions
98 that normally return false on failure with equivalents that throw
99 an exception on failure.
100 .PP
101 The \f(CW\*(C`autodie\*(C'\fR pragma has \fIlexical scope\fR, meaning that functions
102 and subroutines altered with \f(CW\*(C`autodie\*(C'\fR will only change their behaviour
103 until the end of the enclosing block, file, or \f(CW\*(C`eval\*(C'\fR.
104 .PP
105 If \f(CW\*(C`system\*(C'\fR is specified as an argument to \f(CW\*(C`autodie\*(C'\fR, then it
106 uses IPC::System::Simple to do the heavy lifting. See the
107 description of that module for more information.
108 .SH EXCEPTIONS
109 .IX Header "EXCEPTIONS"
110 Exceptions produced by the \f(CW\*(C`autodie\*(C'\fR pragma are members of the
111 autodie::exception class. The preferred way to work with
112 these exceptions under Perl 5.10 is as follows:
113 .PP
114 .Vb 2
115 \& eval {
116 \& use autodie;
117 \&
118 \& open(my $fh, \*(Aq<\*(Aq, $some_file);
119 \&
120 \& my @records = <$fh>;
121 \&
122 \& # Do things with @records...
123 \&
124 \& close($fh);
125 \& };
126 \&
127 \& if ($@ and $@\->isa(\*(Aqautodie::exception\*(Aq)) {
128 \& if ($@\->matches(\*(Aqopen\*(Aq)) { print "Error from open\en"; }
129 \& if ($@\->matches(\*(Aq:io\*(Aq )) { print "Non\-open, IO error."; }
130 \& } elsif ($@) {
131 \& # A non\-autodie exception.
132 \& }
133 .Ve
134 .PP
135 See autodie::exception for further information on interrogating
136 exceptions.
137 .SH CATEGORIES
138 .IX Header "CATEGORIES"
139 Autodie uses a simple set of categories to group together similar
140 built\-ins. Requesting a category type (starting with a colon) will
141 enable autodie for all built\-ins beneath that category. For example,
142 requesting \f(CW\*(C`:file\*(C'\fR will enable autodie for \f(CW\*(C`close\*(C'\fR, \f(CW\*(C`fcntl\*(C'\fR,
143 \&\f(CW\*(C`open\*(C'\fR and \f(CW\*(C`sysopen\*(C'\fR.
144 .PP
145 The categories are currently:
146 .PP
147 .Vb 10
148 \& :all
149 \& :default
150 \& :io
151 \& read
152 \& seek
153 \& sysread
154 \& sysseek
155 \& syswrite
156 \& :dbm
157 \& dbmclose
158 \& dbmopen
159 \& :file
160 \& binmode
161 \& close
162 \& chmod
163 \& chown
164 \& fcntl
165 \& flock
166 \& ioctl
167 \& open
168 \& sysopen
169 \& truncate
170 \& :filesys
171 \& chdir
172 \& closedir
173 \& opendir
174 \& link
175 \& mkdir
176 \& readlink
177 \& rename
178 \& rmdir
179 \& symlink
180 \& unlink
181 \& :ipc
182 \& kill
183 \& pipe
184 \& :msg
185 \& msgctl
186 \& msgget
187 \& msgrcv
188 \& msgsnd
189 \& :semaphore
190 \& semctl
191 \& semget
192 \& semop
193 \& :shm
194 \& shmctl
195 \& shmget
196 \& shmread
197 \& :socket
198 \& accept
199 \& bind
200 \& connect
201 \& getsockopt
202 \& listen
203 \& recv
204 \& send
205 \& setsockopt
206 \& shutdown
207 \& socketpair
208 \& :threads
209 \& fork
210 \& :system
211 \& system
212 \& exec
213 .Ve
214 .PP
215 Note that while the above category system is presently a strict
216 hierarchy, this should not be assumed.
217 .PP
218 A plain \f(CW\*(C`use autodie\*(C'\fR implies \f(CW\*(C`use autodie qw(:default)\*(C'\fR. Note that
219 \&\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
220 the optional IPC::System::Simple module to be installed, and enabling
221 \&\f(CW\*(C`system\*(C'\fR or \f(CW\*(C`exec\*(C'\fR will invalidate their exotic forms. See "BUGS"
222 below for more details.
223 .PP
224 The syntax:
225 .PP
226 .Vb 1
227 \& use autodie qw(:1.994);
228 .Ve
229 .PP
230 allows the \f(CW\*(C`:default\*(C'\fR list from a particular version to be used. This
231 provides the convenience of using the default methods, but the surety
232 that no behavioral changes will occur if the \f(CW\*(C`autodie\*(C'\fR module is
233 upgraded.
234 .PP
235 \&\f(CW\*(C`autodie\*(C'\fR can be enabled for all of Perl\*(Aqs built\-ins, including
236 \&\f(CW\*(C`system\*(C'\fR and \f(CW\*(C`exec\*(C'\fR with:
237 .PP
238 .Vb 1
239 \& use autodie qw(:all);
240 .Ve
241 .SH "FUNCTION SPECIFIC NOTES"
242 .IX Header "FUNCTION SPECIFIC NOTES"
243 .SS print
244 .IX Subsection "print"
245 The autodie pragma \fBdoes not check calls to \fR\f(CB\*(C`print\*(C'\fR.
246 .SS flock
247 .IX Subsection "flock"
248 It is not considered an error for \f(CW\*(C`flock\*(C'\fR to return false if it fails
249 due to an \f(CW\*(C`EWOULDBLOCK\*(C'\fR (or equivalent) condition. This means one can
250 still use the common convention of testing the return value of
251 \&\f(CW\*(C`flock\*(C'\fR when called with the \f(CW\*(C`LOCK_NB\*(C'\fR option:
252 .PP
253 .Vb 1
254 \& use autodie;
255 \&
256 \& if ( flock($fh, LOCK_EX | LOCK_NB) ) {
257 \& # We have a lock
258 \& }
259 .Ve
260 .PP
261 Autodying \f(CW\*(C`flock\*(C'\fR will generate an exception if \f(CW\*(C`flock\*(C'\fR returns
262 false with any other error.
263 .SS system/exec
264 .IX Subsection "system/exec"
265 The \f(CW\*(C`system\*(C'\fR built\-in is considered to have failed in the following
266 circumstances:
267 .IP \(bu 4
268 The command does not start.
269 .IP \(bu 4
270 The command is killed by a signal.
271 .IP \(bu 4
272 The command returns a non\-zero exit value (but see below).
273 .PP
274 On success, the autodying form of \f(CW\*(C`system\*(C'\fR returns the \fIexit value\fR
275 rather than the contents of \f(CW$?\fR.
276 .PP
277 Additional allowable exit values can be supplied as an optional first
278 argument to autodying \f(CW\*(C`system\*(C'\fR:
279 .PP
280 .Vb 1
281 \& system( [ 0, 1, 2 ], $cmd, @args); # 0,1,2 are good exit values
282 .Ve
283 .PP
284 \&\f(CW\*(C`autodie\*(C'\fR uses the IPC::System::Simple module to change \f(CW\*(C`system\*(C'\fR.
285 See its documentation for further information.
286 .PP
287 Applying \f(CW\*(C`autodie\*(C'\fR to \f(CW\*(C`system\*(C'\fR or \f(CW\*(C`exec\*(C'\fR causes the exotic
288 forms \f(CW\*(C`system { $cmd } @args \*(C'\fR or \f(CW\*(C`exec { $cmd } @args\*(C'\fR
289 to be considered a syntax error until the end of the lexical scope.
290 If you really need to use the exotic form, you can call \f(CW\*(C`CORE::system\*(C'\fR
291 or \f(CW\*(C`CORE::exec\*(C'\fR instead, or use \f(CW\*(C`no autodie qw(system exec)\*(C'\fR before
292 calling the exotic form.
293 .SH GOTCHAS
294 .IX Header "GOTCHAS"
295 Functions called in list context are assumed to have failed if they
296 return an empty list, or a list consisting only of a single undef
297 element.
298 .PP
299 Some builtins (e.g. \f(CW\*(C`chdir\*(C'\fR or \f(CW\*(C`truncate\*(C'\fR) has a call signature that
300 cannot completely be represented with a Perl prototype. This means
301 that some valid Perl code will be invalid under autodie. As an example:
302 .PP
303 .Vb 1
304 \& chdir(BAREWORD);
305 .Ve
306 .PP
307 Without autodie (and assuming BAREWORD is an open
308 filehandle/dirhandle) this is a valid call to chdir. But under
309 autodie, \f(CW\*(C`chdir\*(C'\fR will behave like it had the prototype ";$" and thus
310 BAREWORD will be a syntax error (under "use strict". Without strict, it
311 will interpreted as a filename).
312 .SH DIAGNOSTICS
313 .IX Header "DIAGNOSTICS"
314 .IP ":void cannot be used with lexical scope" 4
315 .IX Item ":void cannot be used with lexical scope"
316 The \f(CW\*(C`:void\*(C'\fR option is supported in Fatal, but not
317 \&\f(CW\*(C`autodie\*(C'\fR. To workaround this, \f(CW\*(C`autodie\*(C'\fR may be explicitly disabled until
318 the end of the current block with \f(CW\*(C`no autodie\*(C'\fR.
319 To disable autodie for only a single function (eg, open)
320 use \f(CW\*(C`no autodie qw(open)\*(C'\fR.
321 .Sp
322 \&\f(CW\*(C`autodie\*(C'\fR performs no checking of called context to determine whether to throw
323 an exception; the explicitness of error handling with \f(CW\*(C`autodie\*(C'\fR is a deliberate
324 feature.
325 .ie n .IP "No user hints defined for %s" 4
326 .el .IP "No user hints defined for \f(CW%s\fR" 4
327 .IX Item "No user hints defined for %s"
328 You\*(Aqve insisted on hints for user\-subroutines, either by pre\-pending
329 a \f(CW\*(C`!\*(C'\fR to the subroutine name itself, or earlier in the list of arguments
330 to \f(CW\*(C`autodie\*(C'\fR. However the subroutine in question does not have
331 any hints available.
332 .PP
333 See also "DIAGNOSTICS" in Fatal.
334 .SH "Tips and Tricks"
335 .IX Header "Tips and Tricks"
336 .SS "Importing autodie into another namespace than ""caller"""
337 .IX Subsection "Importing autodie into another namespace than ""caller"""
338 It is possible to import autodie into a different namespace by using
339 Import::Into. However, you have to pass a "caller depth" (rather
340 than a package name) for this to work correctly.
341 .SH BUGS
342 .IX Header "BUGS"
343 "Used only once" warnings can be generated when \f(CW\*(C`autodie\*(C'\fR or \f(CW\*(C`Fatal\*(C'\fR
344 is used with package filehandles (eg, \f(CW\*(C`FILE\*(C'\fR). Scalar filehandles are
345 strongly recommended instead.
346 .PP
347 When using \f(CW\*(C`autodie\*(C'\fR or \f(CW\*(C`Fatal\*(C'\fR with user subroutines, the
348 declaration of those subroutines must appear before the first use of
349 \&\f(CW\*(C`Fatal\*(C'\fR or \f(CW\*(C`autodie\*(C'\fR, or have been exported from a module.
350 Attempting to use \f(CW\*(C`Fatal\*(C'\fR or \f(CW\*(C`autodie\*(C'\fR on other user subroutines will
351 result in a compile\-time error.
352 .PP
353 Due to a bug in Perl, \f(CW\*(C`autodie\*(C'\fR may "lose" any format which has the
354 same name as an autodying built\-in or function.
355 .PP
356 \&\f(CW\*(C`autodie\*(C'\fR may not work correctly if used inside a file with a
357 name that looks like a string eval, such as \fIeval (3)\fR.
358 .SS "autodie and string eval"
359 .IX Subsection "autodie and string eval"
360 Due to the current implementation of \f(CW\*(C`autodie\*(C'\fR, unexpected results
361 may be seen when used near or with the string version of eval.
362 \&\fINone of these bugs exist when using block eval\fR.
363 .PP
364 Under Perl 5.8 only, \f(CW\*(C`autodie\*(C'\fR \fIdoes not\fR propagate into string \f(CW\*(C`eval\*(C'\fR
365 statements, although it can be explicitly enabled inside a string
366 \&\f(CW\*(C`eval\*(C'\fR.
367 .PP
368 Under Perl 5.10 only, using a string eval when \f(CW\*(C`autodie\*(C'\fR is in
369 effect can cause the autodie behaviour to leak into the surrounding
370 scope. This can be worked around by using a \f(CW\*(C`no autodie\*(C'\fR at the
371 end of the scope to explicitly remove autodie\*(Aqs effects, or by
372 avoiding the use of string eval.
373 .PP
374 \&\fINone of these bugs exist when using block eval\fR. The use of
375 \&\f(CW\*(C`autodie\*(C'\fR with block eval is considered good practice.
376 .SS "REPORTING BUGS"
377 .IX Subsection "REPORTING BUGS"
378 Please report bugs via the GitHub Issue Tracker at
379 <https://github.com/pjf/autodie/issues>.
380 .SH FEEDBACK
381 .IX Header "FEEDBACK"
382 If you find this module useful, please consider rating it on metacpan at
383 <https://metacpan.org/pod/autodie> .
384 .PP
385 The module author loves to hear how \f(CW\*(C`autodie\*(C'\fR has made your life
386 better (or worse). Feedback can be sent to
387 <[email protected]>.
388 .SH AUTHOR
389 .IX Header "AUTHOR"
390 Copyright 2008\-2009, Paul Fenwick <[email protected]>
391 .SH LICENSE
392 .IX Header "LICENSE"
393 This module is free software. You may distribute it under the
394 same terms as Perl itself.
395 .SH "SEE ALSO"
396 .IX Header "SEE ALSO"
397 Fatal, autodie::exception, autodie::hints, IPC::System::Simple
398 .PP
399 \&\fIPerl tips, autodie\fR at
400 <http://perltraining.com.au/tips/2008\-08\-20.html>
401 .SH ACKNOWLEDGEMENTS
402 .IX Header "ACKNOWLEDGEMENTS"
403 Mark Reed and Roland Giersig \-\- Klingon translators.
404 .PP
405 See the \fIAUTHORS\fR file for full credits. The latest version of this
406 file can be found at
407 <https://github.com/pjf/autodie/tree/master/AUTHORS> .