Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Carp.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 "Carp 3pm"
61 .TH Carp 3pm 2026-03-09 "perl v5.42.1" "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 Carp \- alternative warn and die for modules
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Carp;
72 \&
73 \& # warn user (from perspective of caller)
74 \& carp "string trimmed to 80 chars";
75 \&
76 \& # die of errors (from perspective of caller)
77 \& croak "We\*(Aqre outta here!";
78 \&
79 \& # die of errors with stack backtrace
80 \& confess "not implemented";
81 \&
82 \& # cluck, longmess and shortmess not exported by default
83 \& use Carp qw(cluck longmess shortmess);
84 \& cluck "This is how we got here!"; # warn with stack backtrace
85 \& my $long_message = longmess( "message from cluck() or confess()" );
86 \& my $short_message = shortmess( "message from carp() or croak()" );
87 .Ve
88 .SH DESCRIPTION
89 .IX Header "DESCRIPTION"
90 The Carp routines are useful in your own modules because
91 they act like \f(CWdie()\fR or \f(CWwarn()\fR, but with a message which is more
92 likely to be useful to a user of your module. In the case of
93 \&\f(CWcluck()\fR and \f(CWconfess()\fR, that context is a summary of every
94 call in the call\-stack; \f(CWlongmess()\fR returns the contents of the error
95 message.
96 .PP
97 For a shorter message you can use \f(CWcarp()\fR or \f(CWcroak()\fR which report the
98 error as being from where your module was called. \f(CWshortmess()\fR returns the
99 contents of this error message. There is no guarantee that that is where the
100 error was, but it is a good educated guess.
101 .PP
102 \&\f(CW\*(C`Carp\*(C'\fR takes care not to clobber the status variables \f(CW$!\fR and \f(CW$^E\fR
103 in the course of assembling its error messages. This means that a
104 \&\f(CW$SIG{_\|_DIE_\|_}\fR or \f(CW$SIG{_\|_WARN_\|_}\fR handler can capture the error
105 information held in those variables, if it is required to augment the
106 error message, and if the code calling \f(CW\*(C`Carp\*(C'\fR left useful values there.
107 Of course, \f(CW\*(C`Carp\*(C'\fR can\*(Aqt guarantee the latter.
108 .PP
109 You can also alter the way the output and logic of \f(CW\*(C`Carp\*(C'\fR works, by
110 changing some global variables in the \f(CW\*(C`Carp\*(C'\fR namespace. See the
111 section on "GLOBAL VARIABLES" below.
112 .PP
113 Here is a more complete description of how \f(CW\*(C`carp\*(C'\fR and \f(CW\*(C`croak\*(C'\fR work.
114 What they do is search the call\-stack for a function call stack where
115 they have not been told that there shouldn\*(Aqt be an error. If every
116 call is marked safe, they give up and give a full stack backtrace
117 instead. In other words they presume that the first likely looking
118 potential suspect is guilty. Their rules for telling whether
119 a call shouldn\*(Aqt generate errors work as follows:
120 .IP 1. 4
121 Any call from a package to itself is safe.
122 .IP 2. 4
123 Packages claim that there won\*(Aqt be errors on calls to or from
124 packages explicitly marked as safe by inclusion in \f(CW@CARP_NOT\fR, or
125 (if that array is empty) \f(CW@ISA\fR. The ability to override what
126 \&\f(CW@ISA\fR says is new in 5.8.
127 .IP 3. 4
128 The trust in item 2 is transitive. If A trusts B, and B
129 trusts C, then A trusts C. So if you do not override \f(CW@ISA\fR
130 with \f(CW@CARP_NOT\fR, then this trust relationship is identical to,
131 "inherits from".
132 .IP 4. 4
133 Any call from an internal Perl module is safe. (Nothing keeps
134 user modules from marking themselves as internal to Perl, but
135 this practice is discouraged.)
136 .IP 5. 4
137 Any call to Perl\*(Aqs warning system (eg Carp itself) is safe.
138 (This rule is what keeps it from reporting the error at the
139 point where you call \f(CW\*(C`carp\*(C'\fR or \f(CW\*(C`croak\*(C'\fR.)
140 .IP 6. 4
141 \&\f(CW$Carp::CarpLevel\fR can be set to skip a fixed number of additional
142 call levels. Using this is not recommended because it is very
143 difficult to get it to behave correctly.
144 .SS "Forcing a Stack Trace"
145 .IX Subsection "Forcing a Stack Trace"
146 As a debugging aid, you can force Carp to treat a croak as a confess
147 and a carp as a cluck across \fIall\fR modules. In other words, force a
148 detailed stack trace to be given. This can be very helpful when trying
149 to understand why, or from where, a warning or error is being generated.
150 .PP
151 This feature is enabled by \*(Aqimporting\*(Aq the non\-existent symbol
152 \&\*(Aqverbose\*(Aq. You would typically enable it by saying
153 .PP
154 .Vb 1
155 \& perl \-MCarp=verbose script.pl
156 .Ve
157 .PP
158 or by including the string \f(CW\*(C`\-MCarp=verbose\*(C'\fR in the PERL5OPT
159 environment variable.
160 .PP
161 Alternately, you can set the global variable \f(CW$Carp::Verbose\fR to true.
162 See the "GLOBAL VARIABLES" section below.
163 .SS "Stack Trace formatting"
164 .IX Subsection "Stack Trace formatting"
165 At each stack level, the subroutine\*(Aqs name is displayed along with
166 its parameters. For simple scalars, this is sufficient. For complex
167 data types, such as objects and other references, this can simply
168 display \f(CW\*(AqHASH(0x1ab36d8)\*(Aq\fR.
169 .PP
170 Carp gives two ways to control this.
171 .IP 1. 4
172 For objects, a method, \f(CW\*(C`CARP_TRACE\*(C'\fR, will be called, if it exists. If
173 this method doesn\*(Aqt exist, or it recurses into \f(CW\*(C`Carp\*(C'\fR, or it otherwise
174 throws an exception, this is skipped, and Carp moves on to the next option,
175 otherwise checking stops and the string returned is used. It is recommended
176 that the object\*(Aqs type is part of the string to make debugging easier.
177 .IP 2. 4
178 For any type of reference, \f(CW$Carp::RefArgFormatter\fR is checked (see below).
179 This variable is expected to be a code reference, and the current parameter
180 is passed in. If this function doesn\*(Aqt exist (the variable is undef), or
181 it recurses into \f(CW\*(C`Carp\*(C'\fR, or it otherwise throws an exception, this is
182 skipped, and Carp moves on to the next option, otherwise checking stops
183 and the string returned is used.
184 .IP 3. 4
185 Otherwise, if neither \f(CW\*(C`CARP_TRACE\*(C'\fR nor \f(CW$Carp::RefArgFormatter\fR is
186 available, stringify the value ignoring any overloading.
187 .SH "GLOBAL VARIABLES"
188 .IX Header "GLOBAL VARIABLES"
189 .ie n .SS $Carp::MaxEvalLen
190 .el .SS \f(CW$Carp::MaxEvalLen\fP
191 .IX Subsection "$Carp::MaxEvalLen"
192 This variable determines how many characters of a string\-eval are to
193 be shown in the output. Use a value of \f(CW0\fR to show all text.
194 .PP
195 Defaults to \f(CW0\fR.
196 .ie n .SS $Carp::MaxArgLen
197 .el .SS \f(CW$Carp::MaxArgLen\fP
198 .IX Subsection "$Carp::MaxArgLen"
199 This variable determines how many characters of each argument to a
200 function to print. Use a value of \f(CW0\fR to show the full length of the
201 argument.
202 .PP
203 Defaults to \f(CW64\fR.
204 .ie n .SS $Carp::MaxArgNums
205 .el .SS \f(CW$Carp::MaxArgNums\fP
206 .IX Subsection "$Carp::MaxArgNums"
207 This variable determines how many arguments to each function to show.
208 Use a false value to show all arguments to a function call. To suppress all
209 arguments, use \f(CW\-1\fR or \f(CW\*(Aq0 but true\*(Aq\fR.
210 .PP
211 Defaults to \f(CW8\fR.
212 .ie n .SS $Carp::Verbose
213 .el .SS \f(CW$Carp::Verbose\fP
214 .IX Subsection "$Carp::Verbose"
215 This variable makes \f(CWcarp()\fR and \f(CWcroak()\fR generate stack backtraces
216 just like \f(CWcluck()\fR and \f(CWconfess()\fR. This is how \f(CW\*(C`use Carp \*(Aqverbose\*(Aq\*(C'\fR
217 is implemented internally.
218 .PP
219 Defaults to \f(CW0\fR.
220 .ie n .SS $Carp::RefArgFormatter
221 .el .SS \f(CW$Carp::RefArgFormatter\fP
222 .IX Subsection "$Carp::RefArgFormatter"
223 This variable sets a general argument formatter to display references.
224 Plain scalars and objects that implement \f(CW\*(C`CARP_TRACE\*(C'\fR will not go through
225 this formatter. Calling \f(CW\*(C`Carp\*(C'\fR from within this function is not supported.
226 .PP
227 .Vb 4
228 \& local $Carp::RefArgFormatter = sub {
229 \& require Data::Dumper;
230 \& Data::Dumper\->Dump($_[0]); # not necessarily safe
231 \& };
232 .Ve
233 .ie n .SS @CARP_NOT
234 .el .SS \f(CW@CARP_NOT\fP
235 .IX Subsection "@CARP_NOT"
236 This variable, \fIin your package\fR, says which packages are \fInot\fR to be
237 considered as the location of an error. The \f(CWcarp()\fR and \f(CWcluck()\fR
238 functions will skip over callers when reporting where an error occurred.
239 .PP
240 NB: This variable must be in the package\*(Aqs symbol table, thus:
241 .PP
242 .Vb 4
243 \& # These work
244 \& our @CARP_NOT; # file scope
245 \& use vars qw(@CARP_NOT); # package scope
246 \& @My::Package::CARP_NOT = ... ; # explicit package variable
247 \&
248 \& # These don\*(Aqt work
249 \& sub xyz { ... @CARP_NOT = ... } # w/o declarations above
250 \& my @CARP_NOT; # even at top\-level
251 .Ve
252 .PP
253 Example of use:
254 .PP
255 .Vb 9
256 \& package My::Carping::Package;
257 \& use Carp;
258 \& our @CARP_NOT;
259 \& sub bar { .... or _error(\*(AqWrong input\*(Aq) }
260 \& sub _error {
261 \& # temporary control of where\*(Aqness, _\|_PACKAGE_\|_ is implicit
262 \& local @CARP_NOT = qw(My::Friendly::Caller);
263 \& carp(@_)
264 \& }
265 .Ve
266 .PP
267 This would make \f(CW\*(C`Carp\*(C'\fR report the error as coming from a caller not
268 in \f(CW\*(C`My::Carping::Package\*(C'\fR, nor from \f(CW\*(C`My::Friendly::Caller\*(C'\fR.
269 .PP
270 Also read the "DESCRIPTION" section above, about how \f(CW\*(C`Carp\*(C'\fR decides
271 where the error is reported from.
272 .PP
273 Use \f(CW@CARP_NOT\fR, instead of \f(CW$Carp::CarpLevel\fR.
274 .PP
275 Overrides \f(CW\*(C`Carp\*(C'\fR\*(Aqs use of \f(CW@ISA\fR.
276 .ie n .SS %Carp::Internal
277 .el .SS \f(CW%Carp::Internal\fP
278 .IX Subsection "%Carp::Internal"
279 This says what packages are internal to Perl. \f(CW\*(C`Carp\*(C'\fR will never
280 report an error as being from a line in a package that is internal to
281 Perl. For example:
282 .PP
283 .Vb 3
284 \& $Carp::Internal{ (_\|_PACKAGE_\|_) }++;
285 \& # time passes...
286 \& sub foo { ... or confess("whatever") };
287 .Ve
288 .PP
289 would give a full stack backtrace starting from the first caller
290 outside of _\|_PACKAGE_\|_. (Unless that package was also internal to
291 Perl.)
292 .ie n .SS %Carp::CarpInternal
293 .el .SS \f(CW%Carp::CarpInternal\fP
294 .IX Subsection "%Carp::CarpInternal"
295 This says which packages are internal to Perl\*(Aqs warning system. For
296 generating a full stack backtrace this is the same as being internal
297 to Perl, the stack backtrace will not start inside packages that are
298 listed in \f(CW%Carp::CarpInternal\fR. But it is slightly different for
299 the summary message generated by \f(CW\*(C`carp\*(C'\fR or \f(CW\*(C`croak\*(C'\fR. There errors
300 will not be reported on any lines that are calling packages in
301 \&\f(CW%Carp::CarpInternal\fR.
302 .PP
303 For example \f(CW\*(C`Carp\*(C'\fR itself is listed in \f(CW%Carp::CarpInternal\fR.
304 Therefore the full stack backtrace from \f(CW\*(C`confess\*(C'\fR will not start
305 inside of \f(CW\*(C`Carp\*(C'\fR, and the short message from calling \f(CW\*(C`croak\*(C'\fR is
306 not placed on the line where \f(CW\*(C`croak\*(C'\fR was called.
307 .ie n .SS $Carp::CarpLevel
308 .el .SS \f(CW$Carp::CarpLevel\fP
309 .IX Subsection "$Carp::CarpLevel"
310 This variable determines how many additional call frames are to be
311 skipped that would not otherwise be when reporting where an error
312 occurred on a call to one of \f(CW\*(C`Carp\*(C'\fR\*(Aqs functions. It is fairly easy
313 to count these call frames on calls that generate a full stack
314 backtrace. However it is much harder to do this accounting for calls
315 that generate a short message. Usually people skip too many call
316 frames. If they are lucky they skip enough that \f(CW\*(C`Carp\*(C'\fR goes all of
317 the way through the call stack, realizes that something is wrong, and
318 then generates a full stack backtrace. If they are unlucky then the
319 error is reported from somewhere misleading very high in the call
320 stack.
321 .PP
322 Therefore it is best to avoid \f(CW$Carp::CarpLevel\fR. Instead use
323 \&\f(CW@CARP_NOT\fR, \f(CW%Carp::Internal\fR and \f(CW%Carp::CarpInternal\fR.
324 .PP
325 Defaults to \f(CW0\fR.
326 .SH BUGS
327 .IX Header "BUGS"
328 The Carp routines don\*(Aqt handle exception objects currently.
329 If called with a first argument that is a reference, they simply
330 call \fBdie()\fR or \fBwarn()\fR, as appropriate.
331 .SH "SEE ALSO"
332 .IX Header "SEE ALSO"
333 Carp::Always,
334 Carp::Clan
335 .SH CONTRIBUTING
336 .IX Header "CONTRIBUTING"
337 Carp is maintained by the perl 5 porters as part of the core perl 5
338 version control repository. Please see the perlhack perldoc for how to
339 submit patches and contribute to it.
340 .SH AUTHOR
341 .IX Header "AUTHOR"
342 The Carp module first appeared in Larry Wall\*(Aqs perl 5.000 distribution.
343 Since then it has been modified by several of the perl 5 porters.
344 Andrew Main (Zefram) <[email protected]> divested Carp into an independent
345 distribution.
346 .SH COPYRIGHT
347 .IX Header "COPYRIGHT"
348 Copyright (C) 1994\-2013 Larry Wall
349 .PP
350 Copyright (C) 2011, 2012, 2013 Andrew Main (Zefram) <[email protected]>
351 .SH LICENSE
352 .IX Header "LICENSE"
353 This module is free software; you can redistribute it and/or modify it
354 under the same terms as Perl itself.