Debian Codegraph @

upstream/debian-unstable/man3/Fatal.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 "Fatal 3perl"
58 .TH Fatal 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 Fatal \- Replace functions with equivalents which succeed or die
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use Fatal qw(open close);
69 \&
70 \& open(my $fh, "<", $filename); # No need to check errors!
71 \&
72 \& use File::Copy qw(move);
73 \& use Fatal qw(move);
74 \&
75 \& move($file1, $file2); # No need to check errors!
76 \&
77 \& sub juggle { . . . }
78 \& Fatal\->import(\*(Aqjuggle\*(Aq);
79 .Ve
80 .SH "BEST PRACTICE"
81 .IX Header "BEST PRACTICE"
82 \&\fBFatal has been obsoleted by the new autodie pragma.\fR Please use
83 autodie in preference to \f(CW\*(C`Fatal\*(C'\fR. autodie supports lexical scoping,
84 throws real exception objects, and provides much nicer error messages.
85 .PP
86 The use of \f(CW\*(C`:void\*(C'\fR with Fatal is discouraged.
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 \&\f(CW\*(C`Fatal\*(C'\fR provides a way to conveniently replace
90 functions which normally return a false value when they fail with
91 equivalents which raise exceptions if they are not successful. This
92 lets you use these functions without having to test their return
93 values explicitly on each call. Exceptions can be caught using
94 \&\f(CW\*(C`eval{}\*(C'\fR. See perlfunc and perlvar for details.
95 .PP
96 The do-or-die equivalents are set up simply by calling Fatal's
97 \&\f(CW\*(C`import\*(C'\fR routine, passing it the names of the functions to be
98 replaced. You may wrap both user-defined functions and overridable
99 CORE operators (except \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`system\*(C'\fR, \f(CW\*(C`print\*(C'\fR, or any other
100 built-in that cannot be expressed via prototypes) in this way.
101 .PP
102 If the symbol \f(CW\*(C`:void\*(C'\fR appears in the import list, then functions
103 named later in that import list raise an exception only when
104 these are called in void context\-\-that is, when their return
105 values are ignored. For example
106 .PP
107 .Vb 1
108 \& use Fatal qw/:void open close/;
109 \&
110 \& # properly checked, so no exception raised on error
111 \& if (not open(my $fh, \*(Aq<\*(Aq, \*(Aq/bogotic\*(Aq) {
112 \& warn "Can\*(Aqt open /bogotic: $!";
113 \& }
114 \&
115 \& # not checked, so error raises an exception
116 \& close FH;
117 .Ve
118 .PP
119 The use of \f(CW\*(C`:void\*(C'\fR is discouraged, as it can result in exceptions
120 not being thrown if you \fIaccidentally\fR call a method without
121 void context. Use autodie instead if you need to be able to
122 disable autodying/Fatal behaviour for a small block of code.
123 .SH DIAGNOSTICS
124 .IX Header "DIAGNOSTICS"
125 .ie n .IP "Bad subroutine name for Fatal: %s" 4
126 .el .IP "Bad subroutine name for Fatal: \f(CW%s\fR" 4
127 .IX Item "Bad subroutine name for Fatal: %s"
128 You've called \f(CW\*(C`Fatal\*(C'\fR with an argument that doesn't look like
129 a subroutine name, nor a switch that this version of Fatal
130 understands.
131 .ie n .IP "%s is not a Perl subroutine" 4
132 .el .IP "\f(CW%s\fR is not a Perl subroutine" 4
133 .IX Item "%s is not a Perl subroutine"
134 You've asked \f(CW\*(C`Fatal\*(C'\fR to try and replace a subroutine which does not
135 exist, or has not yet been defined.
136 .ie n .IP "%s is neither a builtin, nor a Perl subroutine" 4
137 .el .IP "\f(CW%s\fR is neither a builtin, nor a Perl subroutine" 4
138 .IX Item "%s is neither a builtin, nor a Perl subroutine"
139 You've asked \f(CW\*(C`Fatal\*(C'\fR to replace a subroutine, but it's not a Perl
140 built-in, and \f(CW\*(C`Fatal\*(C'\fR couldn't find it as a regular subroutine.
141 It either doesn't exist or has not yet been defined.
142 .ie n .IP "Cannot make the non-overridable %s fatal" 4
143 .el .IP "Cannot make the non-overridable \f(CW%s\fR fatal" 4
144 .IX Item "Cannot make the non-overridable %s fatal"
145 You've tried to use \f(CW\*(C`Fatal\*(C'\fR on a Perl built-in that can't be
146 overridden, such as \f(CW\*(C`print\*(C'\fR or \f(CW\*(C`system\*(C'\fR, which means that
147 \&\f(CW\*(C`Fatal\*(C'\fR can't help you, although some other modules might.
148 See the "SEE ALSO" section of this documentation.
149 .ie n .IP "Internal error: %s" 4
150 .el .IP "Internal error: \f(CW%s\fR" 4
151 .IX Item "Internal error: %s"
152 You've found a bug in \f(CW\*(C`Fatal\*(C'\fR. Please report it using
153 the \f(CW\*(C`perlbug\*(C'\fR command.
154 .SH BUGS
155 .IX Header "BUGS"
156 \&\f(CW\*(C`Fatal\*(C'\fR clobbers the context in which a function is called and always
157 makes it a scalar context, except when the \f(CW\*(C`:void\*(C'\fR tag is used.
158 This problem does not exist in autodie.
159 .PP
160 "Used only once" warnings can be generated when \f(CW\*(C`autodie\*(C'\fR or \f(CW\*(C`Fatal\*(C'\fR
161 is used with package filehandles (eg, \f(CW\*(C`FILE\*(C'\fR). It's strongly recommended
162 you use scalar filehandles instead.
163 .SH AUTHOR
164 .IX Header "AUTHOR"
165 Original module by Lionel Cons (CERN).
166 .PP
167 Prototype updates by Ilya Zakharevich <[email protected]\-state.edu>.
168 .PP
169 autodie support, bugfixes, extended diagnostics, \f(CW\*(C`system\*(C'\fR
170 support, and major overhauling by Paul Fenwick <[email protected]>
171 .SH LICENSE
172 .IX Header "LICENSE"
173 This module is free software, you may distribute it under the
174 same terms as Perl itself.
175 .SH "SEE ALSO"
176 .IX Header "SEE ALSO"
177 autodie for a nicer way to use lexical Fatal.
178 .PP
179 IPC::System::Simple for a similar idea for calls to \f(CWsystem()\fR
180 and backticks.