Debian Codegraph @

upstream/debian-unstable/man3/diagnostics.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 "diagnostics 3perl"
58 .TH diagnostics 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 diagnostics, splain \- produce verbose warning diagnostics
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 Using the \f(CW\*(C`diagnostics\*(C'\fR pragma:
68 .PP
69 .Vb 2
70 \& use diagnostics;
71 \& use diagnostics \-verbose;
72 \&
73 \& diagnostics\->enable;
74 \& diagnostics\->disable;
75 .Ve
76 .PP
77 Using the \f(CW\*(C`splain\*(C'\fR standalone filter program:
78 .PP
79 .Vb 2
80 \& perl program 2>diag.out
81 \& splain [\-v] [\-p] diag.out
82 .Ve
83 .PP
84 Using diagnostics to get stack traces from a misbehaving script:
85 .PP
86 .Vb 1
87 \& perl \-Mdiagnostics=\-traceonly my_script.pl
88 .Ve
89 .SH DESCRIPTION
90 .IX Header "DESCRIPTION"
91 .ie n .SS "The ""diagnostics"" Pragma"
92 .el .SS "The \f(CWdiagnostics\fP Pragma"
93 .IX Subsection "The diagnostics Pragma"
94 This module extends the terse diagnostics normally emitted by both the
95 perl compiler and the perl interpreter (from running perl with a \-w
96 switch or \f(CW\*(C`use warnings\*(C'\fR), augmenting them with the more
97 explicative and endearing descriptions found in perldiag. Like the
98 other pragmata, it affects the compilation phase of your program rather
99 than merely the execution phase.
100 .PP
101 To use in your program as a pragma, merely invoke
102 .PP
103 .Vb 1
104 \& use diagnostics;
105 .Ve
106 .PP
107 at the start (or near the start) of your program. (Note
108 that this \fIdoes\fR enable perl's \fB\-w\fR flag.) Your whole
109 compilation will then be subject(ed :\-) to the enhanced diagnostics.
110 These still go out \fBSTDERR\fR.
111 .PP
112 Due to the interaction between runtime and compiletime issues,
113 and because it's probably not a very good idea anyway,
114 you may not use \f(CW\*(C`no diagnostics\*(C'\fR to turn them off at compiletime.
115 However, you may control their behaviour at runtime using the
116 \&\f(CWdisable()\fR and \f(CWenable()\fR methods to turn them off and on respectively.
117 .PP
118 The \fB\-verbose\fR flag first prints out the perldiag introduction before
119 any other diagnostics. The \f(CW$diagnostics::PRETTY\fR variable can generate nicer
120 escape sequences for pagers.
121 .PP
122 Warnings dispatched from perl itself (or more accurately, those that match
123 descriptions found in perldiag) are only displayed once (no duplicate
124 descriptions). User code generated warnings a la \fBwarn()\fR are unaffected,
125 allowing duplicate user messages to be displayed.
126 .PP
127 This module also adds a stack trace to the error message when perl dies.
128 This is useful for pinpointing what
129 caused the death. The \fB\-traceonly\fR (or
130 just \fB\-t\fR) flag turns off the explanations of warning messages leaving just
131 the stack traces. So if your script is dieing, run it again with
132 .PP
133 .Vb 1
134 \& perl \-Mdiagnostics=\-traceonly my_bad_script
135 .Ve
136 .PP
137 to see the call stack at the time of death. By supplying the \fB\-warntrace\fR
138 (or just \fB\-w\fR) flag, any warnings emitted will also come with a stack
139 trace.
140 .SS "The \fIsplain\fP Program"
141 .IX Subsection "The splain Program"
142 Another program, \fIsplain\fR is actually nothing
143 more than a link to the (executable) \fIdiagnostics.pm\fR module, as well as
144 a link to the \fIdiagnostics.pod\fR documentation. The \fB\-v\fR flag is like
145 the \f(CW\*(C`use diagnostics \-verbose\*(C'\fR directive.
146 The \fB\-p\fR flag is like the
147 \&\f(CW$diagnostics::PRETTY\fR variable. Since you're post-processing with
148 \&\fIsplain\fR, there's no sense in being able to \fBenable()\fR or \fBdisable()\fR processing.
149 .PP
150 Output from \fIsplain\fR is directed to \fBSTDOUT\fR, unlike the pragma.
151 .SH EXAMPLES
152 .IX Header "EXAMPLES"
153 The following file is certain to trigger a few errors at both
154 runtime and compiletime:
155 .PP
156 .Vb 8
157 \& use diagnostics;
158 \& print NOWHERE "nothing\en";
159 \& print STDERR "\en\etThis message should be unadorned.\en";
160 \& warn "\etThis is a user warning";
161 \& print "\enDIAGNOSTIC TESTER: Please enter a <CR> here: ";
162 \& my $a, $b = scalar <STDIN>;
163 \& print "\en";
164 \& print $x/$y;
165 .Ve
166 .PP
167 If you prefer to run your program first and look at its problem
168 afterwards, do this:
169 .PP
170 .Vb 2
171 \& perl \-w test.pl 2>test.out
172 \& ./splain < test.out
173 .Ve
174 .PP
175 Note that this is not in general possible in shells of more dubious heritage,
176 as the theoretical
177 .PP
178 .Vb 2
179 \& (perl \-w test.pl >/dev/tty) >& test.out
180 \& ./splain < test.out
181 .Ve
182 .PP
183 Because you just moved the existing \fBstdout\fR to somewhere else.
184 .PP
185 If you don't want to modify your source code, but still have on-the-fly
186 warnings, do this:
187 .PP
188 .Vb 1
189 \& exec 3>&1; perl \-w test.pl 2>&1 1>&3 3>&\- | splain 1>&2 3>&\-
190 .Ve
191 .PP
192 Nifty, eh?
193 .PP
194 If you want to control warnings on the fly, do something like this.
195 Make sure you do the \f(CW\*(C`use\*(C'\fR first, or you won't be able to get
196 at the \fBenable()\fR or \fBdisable()\fR methods.
197 .PP
198 .Vb 4
199 \& use diagnostics; # checks entire compilation phase
200 \& print "\entime for 1st bogus diags: SQUAWKINGS\en";
201 \& print BOGUS1 \*(Aqnada\*(Aq;
202 \& print "done with 1st bogus\en";
203 \&
204 \& diagnostics\->disable; # only turns off runtime warnings
205 \& print "\entime for 2nd bogus: (squelched)\en";
206 \& print BOGUS2 \*(Aqnada\*(Aq;
207 \& print "done with 2nd bogus\en";
208 \&
209 \& diagnostics\->enable; # turns back on runtime warnings
210 \& print "\entime for 3rd bogus: SQUAWKINGS\en";
211 \& print BOGUS3 \*(Aqnada\*(Aq;
212 \& print "done with 3rd bogus\en";
213 \&
214 \& diagnostics\->disable;
215 \& print "\entime for 4th bogus: (squelched)\en";
216 \& print BOGUS4 \*(Aqnada\*(Aq;
217 \& print "done with 4th bogus\en";
218 .Ve
219 .SH INTERNALS
220 .IX Header "INTERNALS"
221 Diagnostic messages derive from the \fIperldiag.pod\fR file when available at
222 runtime. Otherwise, they may be embedded in the file itself when the
223 splain package is built. See the \fIMakefile\fR for details.
224 .PP
225 If an extant \f(CW$SIG\fR{_\|_WARN_\|_} handler is discovered, it will continue
226 to be honored, but only after the \fBdiagnostics::splainthis()\fR function
227 (the module's \f(CW$SIG\fR{_\|_WARN_\|_} interceptor) has had its way with your
228 warnings.
229 .PP
230 There is a \f(CW$diagnostics::DEBUG\fR variable you may set if you're desperately
231 curious what sorts of things are being intercepted.
232 .PP
233 .Vb 1
234 \& BEGIN { $diagnostics::DEBUG = 1 }
235 .Ve
236 .SH BUGS
237 .IX Header "BUGS"
238 Not being able to say "no diagnostics" is annoying, but may not be
239 insurmountable.
240 .PP
241 The \f(CW\*(C`\-pretty\*(C'\fR directive is called too late to affect matters.
242 You have to do this instead, and \fIbefore\fR you load the module.
243 .PP
244 .Vb 1
245 \& BEGIN { $diagnostics::PRETTY = 1 }
246 .Ve
247 .PP
248 I could start up faster by delaying compilation until it should be
249 needed, but this gets a "panic: top_level" when using the pragma form
250 in Perl 5.001e.
251 .PP
252 While it's true that this documentation is somewhat subserious, if you use
253 a program named \fIsplain\fR, you should expect a bit of whimsy.
254 .SH AUTHOR
255 .IX Header "AUTHOR"
256 Tom Christiansen <\[email protected]\fR>, 25 June 1995.