1warnings(3pm) Perl Programmers Reference Guide warnings(3pm)
2
6 warnings - Perl pragma to control optional warnings
7
9 use warnings;
10 no warnings;
11 use warnings "all";
13 no warnings "all";
14 use warnings::register;
16 if (warnings::enabled()) {
17 warnings::warn("some warning");
18 }
19 if (warnings::enabled("void")) {
21 warnings::warn("void", "some warning");
22 }
23 if (warnings::enabled($object)) {
25 warnings::warn($object, "some warning");
26 }
27 warnings::warnif("some warning");
29 warnings::warnif("void", "some warning");
30 warnings::warnif($object, "some warning");
31
33 The "warnings" pragma gives control over which warnings are enabled in
34 which parts of a Perl program. It's a more flexible alternative for
35 both the command line flag -w and the equivalent Perl variable, $^W.
36 This pragma works just like the "strict" pragma. This means that the
38 scope of the warning pragma is limited to the enclosing block. It also
39 means that the pragma setting will not leak across files (via "use",
40 "require" or "do"). This allows authors to independently define the
41 degree of warning checks that will be applied to their module.
42 By default, optional warnings are disabled, so any legacy code that
44 doesn't attempt to control the warnings will work unchanged.
45 All warnings are enabled in a block by either of these:
47 use warnings;
49 use warnings 'all';
50 Similarly all warnings are disabled in a block by either of these:
52 no warnings;
54 no warnings 'all';
55 For example, consider the code below:
57 use warnings;
59 my @a;
60 {
61 no warnings;
62 my $b = @a[0];
63 }
64 my $c = @a[0];
65 The code in the enclosing block has warnings enabled, but the inner
67 block has them disabled. In this case that means the assignment to the
68 scalar $c will trip the "Scalar value @a[0] better written as $a[0]"
69 warning, but the assignment to the scalar $b will not.
70 Default Warnings and Optional Warnings
72 Before the introduction of lexical warnings, Perl had two classes of
73 warnings: mandatory and optional.
74 As its name suggests, if your code tripped a mandatory warning, you
76 would get a warning whether you wanted it or not. For example, the
77 code below would always produce an "isn't numeric" warning about the
78 "2:".
79 my $a = "2:" + 3;
81 With the introduction of lexical warnings, mandatory warnings now
83 become default warnings. The difference is that although the
84 previously mandatory warnings are still enabled by default, they can
85 then be subsequently enabled or disabled with the lexical warning
86 pragma. For example, in the code below, an "isn't numeric" warning
87 will only be reported for the $a variable.
88 my $a = "2:" + 3;
90 no warnings;
91 my $b = "2:" + 3;
92 Note that neither the -w flag or the $^W can be used to disable/enable
94 default warnings. They are still mandatory in this case.
95 What's wrong with -w and $^W
97 Although very useful, the big problem with using -w on the command line
98 to enable warnings is that it is all or nothing. Take the typical
99 scenario when you are writing a Perl program. Parts of the code you
100 will write yourself, but it's very likely that you will make use of
101 pre-written Perl modules. If you use the -w flag in this case, you end
102 up enabling warnings in pieces of code that you haven't written.
103 Similarly, using $^W to either disable or enable blocks of code is
105 fundamentally flawed. For a start, say you want to disable warnings in
106 a block of code. You might expect this to be enough to do the trick:
107 {
109 local ($^W) = 0;
110 my $a =+ 2;
111 my $b; chop $b;
112 }
113 When this code is run with the -w flag, a warning will be produced for
115 the $a line: "Reversed += operator".
116 The problem is that Perl has both compile-time and run-time warnings.
118 To disable compile-time warnings you need to rewrite the code like
119 this:
120 {
122 BEGIN { $^W = 0 }
123 my $a =+ 2;
124 my $b; chop $b;
125 }
126 And note that unlike the first example, this will permanently set $^W
128 since it cannot both run during compile-time and be localized to a run-
129 time block.
130 The other big problem with $^W is the way you can inadvertently change
132 the warning setting in unexpected places in your code. For example,
133 when the code below is run (without the -w flag), the second call to
134 "doit" will trip a "Use of uninitialized value" warning, whereas the
135 first will not.
136 sub doit
138 {
139 my $b; chop $b;
140 }
141 doit();
143 {
145 local ($^W) = 1;
146 doit()
147 }
148 This is a side-effect of $^W being dynamically scoped.
150 Lexical warnings get around these limitations by allowing finer control
152 over where warnings can or can't be tripped.
153 Controlling Warnings from the Command Line
155 There are three Command Line flags that can be used to control when
156 warnings are (or aren't) produced:
157 -w This is the existing flag. If the lexical warnings pragma is not
159 used in any of you code, or any of the modules that you use, this
160 flag will enable warnings everywhere. See "Backward
161 Compatibility" for details of how this flag interacts with lexical
162 warnings.
163 -W If the -W flag is used on the command line, it will enable all
165 warnings throughout the program regardless of whether warnings
166 were disabled locally using "no warnings" or "$^W =0". This
167 includes all files that get included via "use", "require" or "do".
168 Think of it as the Perl equivalent of the "lint" command.
169 -X Does the exact opposite to the -W flag, i.e. it disables all
171 warnings.
172 Backward Compatibility
174 If you are used to working with a version of Perl prior to the
175 introduction of lexically scoped warnings, or have code that uses both
176 lexical warnings and $^W, this section will describe how they interact.
177 How Lexical Warnings interact with -w/$^W:
179 1. If none of the three command line flags (-w, -W or -X) that
181 control warnings is used and neither $^W nor the "warnings" pragma
182 are used, then default warnings will be enabled and optional
183 warnings disabled. This means that legacy code that doesn't
184 attempt to control the warnings will work unchanged.
185 2. The -w flag just sets the global $^W variable as in 5.005. This
187 means that any legacy code that currently relies on manipulating
188 $^W to control warning behavior will still work as is.
189 3. Apart from now being a boolean, the $^W variable operates in
191 exactly the same horrible uncontrolled global way, except that it
192 cannot disable/enable default warnings.
193 4. If a piece of code is under the control of the "warnings" pragma,
195 both the $^W variable and the -w flag will be ignored for the
196 scope of the lexical warning.
197 5. The only way to override a lexical warnings setting is with the -W
199 or -X command line flags.
200 The combined effect of 3 & 4 is that it will allow code which uses the
202 "warnings" pragma to control the warning behavior of $^W-type code
203 (using a "local $^W=0") if it really wants to, but not vice-versa.
204 Category Hierarchy
206 A hierarchy of "categories" have been defined to allow groups of
207 warnings to be enabled/disabled in isolation.
208 The current hierarchy is:
210 all -+
212 |
213 +- closure
214 |
215 +- deprecated
216 |
217 +- exiting
218 |
219 +- experimental --+
220 | |
221 | +- experimental::alpha_assertions
222 | |
223 | +- experimental::bitwise
224 | |
225 | +- experimental::const_attr
226 | |
227 | +- experimental::declared_refs
228 | |
229 | +- experimental::isa
230 | |
231 | +- experimental::lexical_subs
232 | |
233 | +- experimental::postderef
234 | |
235 | +- experimental::private_use
236 | |
237 | +- experimental::re_strict
238 | |
239 | +- experimental::refaliasing
240 | |
241 | +- experimental::regex_sets
242 | |
243 | +- experimental::script_run
244 | |
245 | +- experimental::signatures
246 | |
247 | +- experimental::smartmatch
248 | |
249 | +- experimental::uniprop_wildcards
250 | |
251 | +- experimental::vlb
252 | |
253 | +- experimental::win32_perlio
254 |
255 +- glob
256 |
257 +- imprecision
258 |
259 +- io ------------+
260 | |
261 | +- closed
262 | |
263 | +- exec
264 | |
265 | +- layer
266 | |
267 | +- newline
268 | |
269 | +- pipe
270 | |
271 | +- syscalls
272 | |
273 | +- unopened
274 |
275 +- locale
276 |
277 +- misc
278 |
279 +- missing
280 |
281 +- numeric
282 |
283 +- once
284 |
285 +- overflow
286 |
287 +- pack
288 |
289 +- portable
290 |
291 +- recursion
292 |
293 +- redefine
294 |
295 +- redundant
296 |
297 +- regexp
298 |
299 +- severe --------+
300 | |
301 | +- debugging
302 | |
303 | +- inplace
304 | |
305 | +- internal
306 | |
307 | +- malloc
308 |
309 +- shadow
310 |
311 +- signal
312 |
313 +- substr
314 |
315 +- syntax --------+
316 | |
317 | +- ambiguous
318 | |
319 | +- bareword
320 | |
321 | +- digit
322 | |
323 | +- illegalproto
324 | |
325 | +- parenthesis
326 | |
327 | +- precedence
328 | |
329 | +- printf
330 | |
331 | +- prototype
332 | |
333 | +- qw
334 | |
335 | +- reserved
336 | |
337 | +- semicolon
338 |
339 +- taint
340 |
341 +- threads
342 |
343 +- uninitialized
344 |
345 +- unpack
346 |
347 +- untie
348 |
349 +- utf8 ----------+
350 | |
351 | +- non_unicode
352 | |
353 | +- nonchar
354 | |
355 | +- surrogate
356 |
357 +- void
358 Just like the "strict" pragma any of these categories can be combined
360 use warnings qw(void redefine);
362 no warnings qw(io syntax untie);
363 Also like the "strict" pragma, if there is more than one instance of
365 the "warnings" pragma in a given scope the cumulative effect is
366 additive.
367 use warnings qw(void); # only "void" warnings enabled
369 ...
370 use warnings qw(io); # only "void" & "io" warnings enabled
371 ...
372 no warnings qw(void); # only "io" warnings enabled
373 To determine which category a specific warning has been assigned to see
375 perldiag.
376 Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was
378 a sub-category of the "syntax" category. It is now a top-level
379 category in its own right.
380 Note: Before 5.21.0, the "missing" lexical warnings category was
382 internally defined to be the same as the "uninitialized" category. It
383 is now a top-level category in its own right.
384 Fatal Warnings
386 The presence of the word "FATAL" in the category list will escalate
387 warnings in those categories into fatal errors in that lexical scope.
388 NOTE: FATAL warnings should be used with care, particularly "FATAL =>
390 'all'".
391 Libraries using warnings::warn for custom warning categories generally
393 don't expect warnings::warn to be fatal and can wind up in an
394 unexpected state as a result. For XS modules issuing categorized
395 warnings, such unanticipated exceptions could also expose memory leak
396 bugs.
397 Moreover, the Perl interpreter itself has had serious bugs involving
399 fatalized warnings. For a summary of resolved and unresolved problems
400 as of January 2015, please see this perl5-porters post
401 <http://www.nntp.perl.org/group/perl.perl5.porters/2015/01/msg225235.html>.
402 While some developers find fatalizing some warnings to be a useful
404 defensive programming technique, using "FATAL => 'all'" to fatalize all
405 possible warning categories -- including custom ones -- is particularly
406 risky. Therefore, the use of "FATAL => 'all'" is discouraged.
407 The strictures module on CPAN offers one example of a warnings subset
409 that the module's authors believe is relatively safe to fatalize.
410 NOTE: users of FATAL warnings, especially those using "FATAL => 'all'",
412 should be fully aware that they are risking future portability of their
413 programs by doing so. Perl makes absolutely no commitments to not
414 introduce new warnings or warnings categories in the future; indeed, we
415 explicitly reserve the right to do so. Code that may not warn now may
416 warn in a future release of Perl if the Perl5 development team deems it
417 in the best interests of the community to do so. Should code using
418 FATAL warnings break due to the introduction of a new warning we will
419 NOT consider it an incompatible change. Users of FATAL warnings should
420 take special caution during upgrades to check to see if their code
421 triggers any new warnings and should pay particular attention to the
422 fine print of the documentation of the features they use to ensure they
423 do not exploit features that are documented as risky, deprecated, or
424 unspecified, or where the documentation says "so don't do that", or
425 anything with the same sense and spirit. Use of such features in
426 combination with FATAL warnings is ENTIRELY AT THE USER'S RISK.
427 The following documentation describes how to use FATAL warnings but the
429 perl5 porters strongly recommend that you understand the risks before
430 doing so, especially for library code intended for use by others, as
431 there is no way for downstream users to change the choice of fatal
432 categories.
433 In the code below, the use of "time", "length" and "join" can all
435 produce a "Useless use of xxx in void context" warning.
436 use warnings;
438 time;
440 {
442 use warnings FATAL => qw(void);
443 length "abc";
444 }
445 join "", 1,2,3;
447 print "done\n";
449 When run it produces this output
451 Useless use of time in void context at fatal line 3.
453 Useless use of length in void context at fatal line 7.
454 The scope where "length" is used has escalated the "void" warnings
456 category into a fatal error, so the program terminates immediately when
457 it encounters the warning.
458 To explicitly turn off a "FATAL" warning you just disable the warning
460 it is associated with. So, for example, to disable the "void" warning
461 in the example above, either of these will do the trick:
462 no warnings qw(void);
464 no warnings FATAL => qw(void);
465 If you want to downgrade a warning that has been escalated into a fatal
467 error back to a normal warning, you can use the "NONFATAL" keyword.
468 For example, the code below will promote all warnings into fatal
469 errors, except for those in the "syntax" category.
470 use warnings FATAL => 'all', NONFATAL => 'syntax';
472 As of Perl 5.20, instead of "use warnings FATAL => 'all';" you can use:
474 use v5.20; # Perl 5.20 or greater is required for the following
476 use warnings 'FATAL'; # short form of "use warnings FATAL => 'all';"
477 If you want your program to be compatible with versions of Perl before
479 5.20, you must use "use warnings FATAL => 'all';" instead. (In
480 previous versions of Perl, the behavior of the statements "use warnings
481 'FATAL';", "use warnings 'NONFATAL';" and "no warnings 'FATAL';" was
482 unspecified; they did not behave as if they included the "=> 'all'"
483 portion. As of 5.20, they do.)
484 Reporting Warnings from a Module
486 The "warnings" pragma provides a number of functions that are useful
487 for module authors. These are used when you want to report a module-
488 specific warning to a calling module has enabled warnings via the
489 "warnings" pragma.
490 Consider the module "MyMod::Abc" below.
492 package MyMod::Abc;
494 use warnings::register;
496 sub open {
498 my $path = shift;
499 if ($path !~ m#^/#) {
500 warnings::warn("changing relative path to /var/abc")
501 if warnings::enabled();
502 $path = "/var/abc/$path";
503 }
504 }
505 1;
507 The call to "warnings::register" will create a new warnings category
509 called "MyMod::Abc", i.e. the new category name matches the current
510 package name. The "open" function in the module will display a warning
511 message if it gets given a relative path as a parameter. This warnings
512 will only be displayed if the code that uses "MyMod::Abc" has actually
513 enabled them with the "warnings" pragma like below.
514 use MyMod::Abc;
516 use warnings 'MyMod::Abc';
517 ...
518 abc::open("../fred.txt");
519 It is also possible to test whether the pre-defined warnings categories
521 are set in the calling module with the "warnings::enabled" function.
522 Consider this snippet of code:
523 package MyMod::Abc;
525 sub open {
527 if (warnings::enabled("deprecated")) {
528 warnings::warn("deprecated",
529 "open is deprecated, use new instead");
530 }
531 new(@_);
532 }
533 sub new
535 ...
536 1;
537 The function "open" has been deprecated, so code has been included to
539 display a warning message whenever the calling module has (at least)
540 the "deprecated" warnings category enabled. Something like this, say.
541 use warnings 'deprecated';
543 use MyMod::Abc;
544 ...
545 MyMod::Abc::open($filename);
546 Either the "warnings::warn" or "warnings::warnif" function should be
548 used to actually display the warnings message. This is because they
549 can make use of the feature that allows warnings to be escalated into
550 fatal errors. So in this case
551 use MyMod::Abc;
553 use warnings FATAL => 'MyMod::Abc';
554 ...
555 MyMod::Abc::open('../fred.txt');
556 the "warnings::warnif" function will detect this and die after
558 displaying the warning message.
559 The three warnings functions, "warnings::warn", "warnings::warnif" and
561 "warnings::enabled" can optionally take an object reference in place of
562 a category name. In this case the functions will use the class name of
563 the object as the warnings category.
564 Consider this example:
566 package Original;
568 no warnings;
570 use warnings::register;
571 sub new
573 {
574 my $class = shift;
575 bless [], $class;
576 }
577 sub check
579 {
580 my $self = shift;
581 my $value = shift;
582 if ($value % 2 && warnings::enabled($self))
584 { warnings::warn($self, "Odd numbers are unsafe") }
585 }
586 sub doit
588 {
589 my $self = shift;
590 my $value = shift;
591 $self->check($value);
592 # ...
593 }
594 1;
596 package Derived;
598 use warnings::register;
600 use Original;
601 our @ISA = qw( Original );
602 sub new
603 {
604 my $class = shift;
605 bless [], $class;
606 }
607 1;
610 The code below makes use of both modules, but it only enables warnings
612 from "Derived".
613 use Original;
615 use Derived;
616 use warnings 'Derived';
617 my $a = Original->new();
618 $a->doit(1);
619 my $b = Derived->new();
620 $a->doit(1);
621 When this code is run only the "Derived" object, $b, will generate a
623 warning.
624 Odd numbers are unsafe at main.pl line 7
626 Notice also that the warning is reported at the line where the object
628 is first used.
629 When registering new categories of warning, you can supply more names
631 to warnings::register like this:
632 package MyModule;
634 use warnings::register qw(format precision);
635 ...
637 warnings::warnif('MyModule::format', '...');
639
641 Note: The functions with names ending in "_at_level" were added in Perl
642 5.28.
643 use warnings::register
645 Creates a new warnings category with the same name as the package
646 where the call to the pragma is used.
647 warnings::enabled()
649 Use the warnings category with the same name as the current
650 package.
651 Return TRUE if that warnings category is enabled in the calling
653 module. Otherwise returns FALSE.
654 warnings::enabled($category)
656 Return TRUE if the warnings category, $category, is enabled in the
657 calling module. Otherwise returns FALSE.
658 warnings::enabled($object)
660 Use the name of the class for the object reference, $object, as the
661 warnings category.
662 Return TRUE if that warnings category is enabled in the first scope
664 where the object is used. Otherwise returns FALSE.
665 warnings::enabled_at_level($category, $level)
667 Like "warnings::enabled", but $level specifies the exact call
668 frame, 0 being the immediate caller.
669 warnings::fatal_enabled()
671 Return TRUE if the warnings category with the same name as the
672 current package has been set to FATAL in the calling module.
673 Otherwise returns FALSE.
674 warnings::fatal_enabled($category)
676 Return TRUE if the warnings category $category has been set to
677 FATAL in the calling module. Otherwise returns FALSE.
678 warnings::fatal_enabled($object)
680 Use the name of the class for the object reference, $object, as the
681 warnings category.
682 Return TRUE if that warnings category has been set to FATAL in the
684 first scope where the object is used. Otherwise returns FALSE.
685 warnings::fatal_enabled_at_level($category, $level)
687 Like "warnings::fatal_enabled", but $level specifies the exact call
688 frame, 0 being the immediate caller.
689 warnings::warn($message)
691 Print $message to STDERR.
692 Use the warnings category with the same name as the current
694 package.
695 If that warnings category has been set to "FATAL" in the calling
697 module then die. Otherwise return.
698 warnings::warn($category, $message)
700 Print $message to STDERR.
701 If the warnings category, $category, has been set to "FATAL" in the
703 calling module then die. Otherwise return.
704 warnings::warn($object, $message)
706 Print $message to STDERR.
707 Use the name of the class for the object reference, $object, as the
709 warnings category.
710 If that warnings category has been set to "FATAL" in the scope
712 where $object is first used then die. Otherwise return.
713 warnings::warn_at_level($category, $level, $message)
715 Like "warnings::warn", but $level specifies the exact call frame, 0
716 being the immediate caller.
717 warnings::warnif($message)
719 Equivalent to:
720 if (warnings::enabled())
722 { warnings::warn($message) }
723 warnings::warnif($category, $message)
725 Equivalent to:
726 if (warnings::enabled($category))
728 { warnings::warn($category, $message) }
729 warnings::warnif($object, $message)
731 Equivalent to:
732 if (warnings::enabled($object))
734 { warnings::warn($object, $message) }
735 warnings::warnif_at_level($category, $level, $message)
737 Like "warnings::warnif", but $level specifies the exact call frame,
738 0 being the immediate caller.
739 warnings::register_categories(@names)
741 This registers warning categories for the given names and is
742 primarily for use by the warnings::register pragma.
743 See also "Pragmatic Modules" in perlmodlib and perldiag.
745perl v5.32.1 2021-03-31 warnings(3pm)