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