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 The other big problem with $^W is the way you can inadvertently change
128 the warning setting in unexpected places in your code. For example,
129 when the code below is run (without the -w flag), the second call to
130 "doit" will trip a "Use of uninitialized value" warning, whereas the
131 first will not.
132 sub doit
134 {
135 my $b; chop $b;
136 }
137 doit();
139 {
141 local ($^W) = 1;
142 doit()
143 }
144 This is a side-effect of $^W being dynamically scoped.
146 Lexical warnings get around these limitations by allowing finer control
148 over where warnings can or can't be tripped.
149 Controlling Warnings from the Command Line
151 There are three Command Line flags that can be used to control when
152 warnings are (or aren't) produced:
153 -w This is the existing flag. If the lexical warnings pragma is not
155 used in any of you code, or any of the modules that you use, this
156 flag will enable warnings everywhere. See "Backward
157 Compatibility" for details of how this flag interacts with lexical
158 warnings.
159 -W If the -W flag is used on the command line, it will enable all
161 warnings throughout the program regardless of whether warnings
162 were disabled locally using "no warnings" or "$^W =0". This
163 includes all files that get included via "use", "require" or "do".
164 Think of it as the Perl equivalent of the "lint" command.
165 -X Does the exact opposite to the -W flag, i.e. it disables all
167 warnings.
168 Backward Compatibility
170 If you are used to working with a version of Perl prior to the
171 introduction of lexically scoped warnings, or have code that uses both
172 lexical warnings and $^W, this section will describe how they interact.
173 How Lexical Warnings interact with -w/$^W:
175 1. If none of the three command line flags (-w, -W or -X) that
177 control warnings is used and neither $^W nor the "warnings" pragma
178 are used, then default warnings will be enabled and optional
179 warnings disabled. This means that legacy code that doesn't
180 attempt to control the warnings will work unchanged.
181 2. The -w flag just sets the global $^W variable as in 5.005. This
183 means that any legacy code that currently relies on manipulating
184 $^W to control warning behavior will still work as is.
185 3. Apart from now being a boolean, the $^W variable operates in
187 exactly the same horrible uncontrolled global way, except that it
188 cannot disable/enable default warnings.
189 4. If a piece of code is under the control of the "warnings" pragma,
191 both the $^W variable and the -w flag will be ignored for the
192 scope of the lexical warning.
193 5. The only way to override a lexical warnings setting is with the -W
195 or -X command line flags.
196 The combined effect of 3 & 4 is that it will allow code which uses the
198 "warnings" pragma to control the warning behavior of $^W-type code
199 (using a "local $^W=0") if it really wants to, but not vice-versa.
200 Category Hierarchy
202 A hierarchy of "categories" have been defined to allow groups of
203 warnings to be enabled/disabled in isolation.
204 The current hierarchy is:
206 all -+
208 |
209 +- closure
210 |
211 +- deprecated
212 |
213 +- exiting
214 |
215 +- experimental --+
216 | |
217 | +- experimental::alpha_assertions
218 | |
219 | +- experimental::bitwise
220 | |
221 | +- experimental::const_attr
222 | |
223 | +- experimental::declared_refs
224 | |
225 | +- experimental::lexical_subs
226 | |
227 | +- experimental::postderef
228 | |
229 | +- experimental::private_use
230 | |
231 | +- experimental::re_strict
232 | |
233 | +- experimental::refaliasing
234 | |
235 | +- experimental::regex_sets
236 | |
237 | +- experimental::script_run
238 | |
239 | +- experimental::signatures
240 | |
241 | +- experimental::smartmatch
242 | |
243 | +- experimental::uniprop_wildcards
244 | |
245 | +- experimental::vlb
246 | |
247 | +- experimental::win32_perlio
248 |
249 +- glob
250 |
251 +- imprecision
252 |
253 +- io ------------+
254 | |
255 | +- closed
256 | |
257 | +- exec
258 | |
259 | +- layer
260 | |
261 | +- newline
262 | |
263 | +- pipe
264 | |
265 | +- syscalls
266 | |
267 | +- unopened
268 |
269 +- locale
270 |
271 +- misc
272 |
273 +- missing
274 |
275 +- numeric
276 |
277 +- once
278 |
279 +- overflow
280 |
281 +- pack
282 |
283 +- portable
284 |
285 +- recursion
286 |
287 +- redefine
288 |
289 +- redundant
290 |
291 +- regexp
292 |
293 +- severe --------+
294 | |
295 | +- debugging
296 | |
297 | +- inplace
298 | |
299 | +- internal
300 | |
301 | +- malloc
302 |
303 +- shadow
304 |
305 +- signal
306 |
307 +- substr
308 |
309 +- syntax --------+
310 | |
311 | +- ambiguous
312 | |
313 | +- bareword
314 | |
315 | +- digit
316 | |
317 | +- illegalproto
318 | |
319 | +- parenthesis
320 | |
321 | +- precedence
322 | |
323 | +- printf
324 | |
325 | +- prototype
326 | |
327 | +- qw
328 | |
329 | +- reserved
330 | |
331 | +- semicolon
332 |
333 +- taint
334 |
335 +- threads
336 |
337 +- uninitialized
338 |
339 +- unpack
340 |
341 +- untie
342 |
343 +- utf8 ----------+
344 | |
345 | +- non_unicode
346 | |
347 | +- nonchar
348 | |
349 | +- surrogate
350 |
351 +- void
352 Just like the "strict" pragma any of these categories can be combined
354 use warnings qw(void redefine);
356 no warnings qw(io syntax untie);
357 Also like the "strict" pragma, if there is more than one instance of
359 the "warnings" pragma in a given scope the cumulative effect is
360 additive.
361 use warnings qw(void); # only "void" warnings enabled
363 ...
364 use warnings qw(io); # only "void" & "io" warnings enabled
365 ...
366 no warnings qw(void); # only "io" warnings enabled
367 To determine which category a specific warning has been assigned to see
369 perldiag.
370 Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was
372 a sub-category of the "syntax" category. It is now a top-level
373 category in its own right.
374 Note: Before 5.21.0, the "missing" lexical warnings category was
376 internally defined to be the same as the "uninitialized" category. It
377 is now a top-level category in its own right.
378 Fatal Warnings
380 The presence of the word "FATAL" in the category list will escalate
381 warnings in those categories into fatal errors in that lexical scope.
382 NOTE: FATAL warnings should be used with care, particularly "FATAL =>
384 'all'".
385 Libraries using warnings::warn for custom warning categories generally
387 don't expect warnings::warn to be fatal and can wind up in an
388 unexpected state as a result. For XS modules issuing categorized
389 warnings, such unanticipated exceptions could also expose memory leak
390 bugs.
391 Moreover, the Perl interpreter itself has had serious bugs involving
393 fatalized warnings. For a summary of resolved and unresolved problems
394 as of January 2015, please see this perl5-porters post
395 <http://www.nntp.perl.org/group/perl.perl5.porters/2015/01/msg225235.html>.
396 While some developers find fatalizing some warnings to be a useful
398 defensive programming technique, using "FATAL => 'all'" to fatalize all
399 possible warning categories -- including custom ones -- is particularly
400 risky. Therefore, the use of "FATAL => 'all'" is discouraged.
401 The strictures module on CPAN offers one example of a warnings subset
403 that the module's authors believe is relatively safe to fatalize.
404 NOTE: users of FATAL warnings, especially those using "FATAL => 'all'",
406 should be fully aware that they are risking future portability of their
407 programs by doing so. Perl makes absolutely no commitments to not
408 introduce new warnings or warnings categories in the future; indeed, we
409 explicitly reserve the right to do so. Code that may not warn now may
410 warn in a future release of Perl if the Perl5 development team deems it
411 in the best interests of the community to do so. Should code using
412 FATAL warnings break due to the introduction of a new warning we will
413 NOT consider it an incompatible change. Users of FATAL warnings should
414 take special caution during upgrades to check to see if their code
415 triggers any new warnings and should pay particular attention to the
416 fine print of the documentation of the features they use to ensure they
417 do not exploit features that are documented as risky, deprecated, or
418 unspecified, or where the documentation says "so don't do that", or
419 anything with the same sense and spirit. Use of such features in
420 combination with FATAL warnings is ENTIRELY AT THE USER'S RISK.
421 The following documentation describes how to use FATAL warnings but the
423 perl5 porters strongly recommend that you understand the risks before
424 doing so, especially for library code intended for use by others, as
425 there is no way for downstream users to change the choice of fatal
426 categories.
427 In the code below, the use of "time", "length" and "join" can all
429 produce a "Useless use of xxx in void context" warning.
430 use warnings;
432 time;
434 {
436 use warnings FATAL => qw(void);
437 length "abc";
438 }
439 join "", 1,2,3;
441 print "done\n";
443 When run it produces this output
445 Useless use of time in void context at fatal line 3.
447 Useless use of length in void context at fatal line 7.
448 The scope where "length" is used has escalated the "void" warnings
450 category into a fatal error, so the program terminates immediately when
451 it encounters the warning.
452 To explicitly turn off a "FATAL" warning you just disable the warning
454 it is associated with. So, for example, to disable the "void" warning
455 in the example above, either of these will do the trick:
456 no warnings qw(void);
458 no warnings FATAL => qw(void);
459 If you want to downgrade a warning that has been escalated into a fatal
461 error back to a normal warning, you can use the "NONFATAL" keyword.
462 For example, the code below will promote all warnings into fatal
463 errors, except for those in the "syntax" category.
464 use warnings FATAL => 'all', NONFATAL => 'syntax';
466 As of Perl 5.20, instead of "use warnings FATAL => 'all';" you can use:
468 use v5.20; # Perl 5.20 or greater is required for the following
470 use warnings 'FATAL'; # short form of "use warnings FATAL => 'all';"
471 If you want your program to be compatible with versions of Perl before
473 5.20, you must use "use warnings FATAL => 'all';" instead. (In
474 previous versions of Perl, the behavior of the statements "use warnings
475 'FATAL';", "use warnings 'NONFATAL';" and "no warnings 'FATAL';" was
476 unspecified; they did not behave as if they included the "=> 'all'"
477 portion. As of 5.20, they do.)
478 Reporting Warnings from a Module
480 The "warnings" pragma provides a number of functions that are useful
481 for module authors. These are used when you want to report a module-
482 specific warning to a calling module has enabled warnings via the
483 "warnings" pragma.
484 Consider the module "MyMod::Abc" below.
486 package MyMod::Abc;
488 use warnings::register;
490 sub open {
492 my $path = shift;
493 if ($path !~ m#^/#) {
494 warnings::warn("changing relative path to /var/abc")
495 if warnings::enabled();
496 $path = "/var/abc/$path";
497 }
498 }
499 1;
501 The call to "warnings::register" will create a new warnings category
503 called "MyMod::Abc", i.e. the new category name matches the current
504 package name. The "open" function in the module will display a warning
505 message if it gets given a relative path as a parameter. This warnings
506 will only be displayed if the code that uses "MyMod::Abc" has actually
507 enabled them with the "warnings" pragma like below.
508 use MyMod::Abc;
510 use warnings 'MyMod::Abc';
511 ...
512 abc::open("../fred.txt");
513 It is also possible to test whether the pre-defined warnings categories
515 are set in the calling module with the "warnings::enabled" function.
516 Consider this snippet of code:
517 package MyMod::Abc;
519 sub open {
521 if (warnings::enabled("deprecated")) {
522 warnings::warn("deprecated",
523 "open is deprecated, use new instead");
524 }
525 new(@_);
526 }
527 sub new
529 ...
530 1;
531 The function "open" has been deprecated, so code has been included to
533 display a warning message whenever the calling module has (at least)
534 the "deprecated" warnings category enabled. Something like this, say.
535 use warnings 'deprecated';
537 use MyMod::Abc;
538 ...
539 MyMod::Abc::open($filename);
540 Either the "warnings::warn" or "warnings::warnif" function should be
542 used to actually display the warnings message. This is because they
543 can make use of the feature that allows warnings to be escalated into
544 fatal errors. So in this case
545 use MyMod::Abc;
547 use warnings FATAL => 'MyMod::Abc';
548 ...
549 MyMod::Abc::open('../fred.txt');
550 the "warnings::warnif" function will detect this and die after
552 displaying the warning message.
553 The three warnings functions, "warnings::warn", "warnings::warnif" and
555 "warnings::enabled" can optionally take an object reference in place of
556 a category name. In this case the functions will use the class name of
557 the object as the warnings category.
558 Consider this example:
560 package Original;
562 no warnings;
564 use warnings::register;
565 sub new
567 {
568 my $class = shift;
569 bless [], $class;
570 }
571 sub check
573 {
574 my $self = shift;
575 my $value = shift;
576 if ($value % 2 && warnings::enabled($self))
578 { warnings::warn($self, "Odd numbers are unsafe") }
579 }
580 sub doit
582 {
583 my $self = shift;
584 my $value = shift;
585 $self->check($value);
586 # ...
587 }
588 1;
590 package Derived;
592 use warnings::register;
594 use Original;
595 our @ISA = qw( Original );
596 sub new
597 {
598 my $class = shift;
599 bless [], $class;
600 }
601 1;
604 The code below makes use of both modules, but it only enables warnings
606 from "Derived".
607 use Original;
609 use Derived;
610 use warnings 'Derived';
611 my $a = Original->new();
612 $a->doit(1);
613 my $b = Derived->new();
614 $a->doit(1);
615 When this code is run only the "Derived" object, $b, will generate a
617 warning.
618 Odd numbers are unsafe at main.pl line 7
620 Notice also that the warning is reported at the line where the object
622 is first used.
623 When registering new categories of warning, you can supply more names
625 to warnings::register like this:
626 package MyModule;
628 use warnings::register qw(format precision);
629 ...
631 warnings::warnif('MyModule::format', '...');
633
635 Note: The functions with names ending in "_at_level" were added in Perl
636 5.28.
637 use warnings::register
639 Creates a new warnings category with the same name as the package
640 where the call to the pragma is used.
641 warnings::enabled()
643 Use the warnings category with the same name as the current
644 package.
645 Return TRUE if that warnings category is enabled in the calling
647 module. Otherwise returns FALSE.
648 warnings::enabled($category)
650 Return TRUE if the warnings category, $category, is enabled in the
651 calling module. Otherwise returns FALSE.
652 warnings::enabled($object)
654 Use the name of the class for the object reference, $object, as the
655 warnings category.
656 Return TRUE if that warnings category is enabled in the first scope
658 where the object is used. Otherwise returns FALSE.
659 warnings::enabled_at_level($category, $level)
661 Like "warnings::enabled", but $level specifies the exact call
662 frame, 0 being the immediate caller.
663 warnings::fatal_enabled()
665 Return TRUE if the warnings category with the same name as the
666 current package has been set to FATAL in the calling module.
667 Otherwise returns FALSE.
668 warnings::fatal_enabled($category)
670 Return TRUE if the warnings category $category has been set to
671 FATAL in the calling module. Otherwise returns FALSE.
672 warnings::fatal_enabled($object)
674 Use the name of the class for the object reference, $object, as the
675 warnings category.
676 Return TRUE if that warnings category has been set to FATAL in the
678 first scope where the object is used. Otherwise returns FALSE.
679 warnings::fatal_enabled_at_level($category, $level)
681 Like "warnings::fatal_enabled", but $level specifies the exact call
682 frame, 0 being the immediate caller.
683 warnings::warn($message)
685 Print $message to STDERR.
686 Use the warnings category with the same name as the current
688 package.
689 If that warnings category has been set to "FATAL" in the calling
691 module then die. Otherwise return.
692 warnings::warn($category, $message)
694 Print $message to STDERR.
695 If the warnings category, $category, has been set to "FATAL" in the
697 calling module then die. Otherwise return.
698 warnings::warn($object, $message)
700 Print $message to STDERR.
701 Use the name of the class for the object reference, $object, as the
703 warnings category.
704 If that warnings category has been set to "FATAL" in the scope
706 where $object is first used then die. Otherwise return.
707 warnings::warn_at_level($category, $level, $message)
709 Like "warnings::warn", but $level specifies the exact call frame, 0
710 being the immediate caller.
711 warnings::warnif($message)
713 Equivalent to:
714 if (warnings::enabled())
716 { warnings::warn($message) }
717 warnings::warnif($category, $message)
719 Equivalent to:
720 if (warnings::enabled($category))
722 { warnings::warn($category, $message) }
723 warnings::warnif($object, $message)
725 Equivalent to:
726 if (warnings::enabled($object))
728 { warnings::warn($object, $message) }
729 warnings::warnif_at_level($category, $level, $message)
731 Like "warnings::warnif", but $level specifies the exact call frame,
732 0 being the immediate caller.
733 warnings::register_categories(@names)
735 This registers warning categories for the given names and is
736 primarily for use by the warnings::register pragma.
737 See also "Pragmatic Modules" in perlmodlib and perldiag.
739perl v5.30.2 2020-03-27 warnings(3pm)