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::bitwise
218 | |
219 | +- experimental::const_attr
220 | |
221 | +- experimental::declared_refs
222 | |
223 | +- experimental::lexical_subs
224 | |
225 | +- experimental::postderef
226 | |
227 | +- experimental::re_strict
228 | |
229 | +- experimental::refaliasing
230 | |
231 | +- experimental::regex_sets
232 | |
233 | +- experimental::signatures
234 | |
235 | +- experimental::smartmatch
236 | |
237 | +- experimental::win32_perlio
238 |
239 +- glob
240 |
241 +- imprecision
242 |
243 +- io ------------+
244 | |
245 | +- closed
246 | |
247 | +- exec
248 | |
249 | +- layer
250 | |
251 | +- newline
252 | |
253 | +- pipe
254 | |
255 | +- syscalls
256 | |
257 | +- unopened
258 |
259 +- locale
260 |
261 +- misc
262 |
263 +- missing
264 |
265 +- numeric
266 |
267 +- once
268 |
269 +- overflow
270 |
271 +- pack
272 |
273 +- portable
274 |
275 +- recursion
276 |
277 +- redefine
278 |
279 +- redundant
280 |
281 +- regexp
282 |
283 +- severe --------+
284 | |
285 | +- debugging
286 | |
287 | +- inplace
288 | |
289 | +- internal
290 | |
291 | +- malloc
292 |
293 +- signal
294 |
295 +- substr
296 |
297 +- syntax --------+
298 | |
299 | +- ambiguous
300 | |
301 | +- bareword
302 | |
303 | +- digit
304 | |
305 | +- illegalproto
306 | |
307 | +- parenthesis
308 | |
309 | +- precedence
310 | |
311 | +- printf
312 | |
313 | +- prototype
314 | |
315 | +- qw
316 | |
317 | +- reserved
318 | |
319 | +- semicolon
320 |
321 +- taint
322 |
323 +- threads
324 |
325 +- uninitialized
326 |
327 +- unpack
328 |
329 +- untie
330 |
331 +- utf8 ----------+
332 | |
333 | +- non_unicode
334 | |
335 | +- nonchar
336 | |
337 | +- surrogate
338 |
339 +- void
340 Just like the "strict" pragma any of these categories can be combined
342 use warnings qw(void redefine);
344 no warnings qw(io syntax untie);
345 Also like the "strict" pragma, if there is more than one instance of
347 the "warnings" pragma in a given scope the cumulative effect is
348 additive.
349 use warnings qw(void); # only "void" warnings enabled
351 ...
352 use warnings qw(io); # only "void" & "io" warnings enabled
353 ...
354 no warnings qw(void); # only "io" warnings enabled
355 To determine which category a specific warning has been assigned to see
357 perldiag.
358 Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was
360 a sub-category of the "syntax" category. It is now a top-level
361 category in its own right.
362 Note: Before 5.21.0, the "missing" lexical warnings category was
364 internally defined to be the same as the "uninitialized" category. It
365 is now a top-level category in its own right.
366 Fatal Warnings
368 The presence of the word "FATAL" in the category list will escalate
369 warnings in those categories into fatal errors in that lexical scope.
370 NOTE: FATAL warnings should be used with care, particularly "FATAL =>
372 'all'".
373 Libraries using warnings::warn for custom warning categories generally
375 don't expect warnings::warn to be fatal and can wind up in an
376 unexpected state as a result. For XS modules issuing categorized
377 warnings, such unanticipated exceptions could also expose memory leak
378 bugs.
379 Moreover, the Perl interpreter itself has had serious bugs involving
381 fatalized warnings. For a summary of resolved and unresolved problems
382 as of January 2015, please see this perl5-porters post
383 <http://www.nntp.perl.org/group/perl.perl5.porters/2015/01/msg225235.html>.
384 While some developers find fatalizing some warnings to be a useful
386 defensive programming technique, using "FATAL => 'all'" to fatalize all
387 possible warning categories -- including custom ones -- is particularly
388 risky. Therefore, the use of "FATAL => 'all'" is discouraged.
389 The strictures module on CPAN offers one example of a warnings subset
391 that the module's authors believe is relatively safe to fatalize.
392 NOTE: users of FATAL warnings, especially those using "FATAL => 'all'",
394 should be fully aware that they are risking future portability of their
395 programs by doing so. Perl makes absolutely no commitments to not
396 introduce new warnings or warnings categories in the future; indeed, we
397 explicitly reserve the right to do so. Code that may not warn now may
398 warn in a future release of Perl if the Perl5 development team deems it
399 in the best interests of the community to do so. Should code using
400 FATAL warnings break due to the introduction of a new warning we will
401 NOT consider it an incompatible change. Users of FATAL warnings should
402 take special caution during upgrades to check to see if their code
403 triggers any new warnings and should pay particular attention to the
404 fine print of the documentation of the features they use to ensure they
405 do not exploit features that are documented as risky, deprecated, or
406 unspecified, or where the documentation says "so don't do that", or
407 anything with the same sense and spirit. Use of such features in
408 combination with FATAL warnings is ENTIRELY AT THE USER'S RISK.
409 The following documentation describes how to use FATAL warnings but the
411 perl5 porters strongly recommend that you understand the risks before
412 doing so, especially for library code intended for use by others, as
413 there is no way for downstream users to change the choice of fatal
414 categories.
415 In the code below, the use of "time", "length" and "join" can all
417 produce a "Useless use of xxx in void context" warning.
418 use warnings;
420 time;
422 {
424 use warnings FATAL => qw(void);
425 length "abc";
426 }
427 join "", 1,2,3;
429 print "done\n";
431 When run it produces this output
433 Useless use of time in void context at fatal line 3.
435 Useless use of length in void context at fatal line 7.
436 The scope where "length" is used has escalated the "void" warnings
438 category into a fatal error, so the program terminates immediately when
439 it encounters the warning.
440 To explicitly turn off a "FATAL" warning you just disable the warning
442 it is associated with. So, for example, to disable the "void" warning
443 in the example above, either of these will do the trick:
444 no warnings qw(void);
446 no warnings FATAL => qw(void);
447 If you want to downgrade a warning that has been escalated into a fatal
449 error back to a normal warning, you can use the "NONFATAL" keyword.
450 For example, the code below will promote all warnings into fatal
451 errors, except for those in the "syntax" category.
452 use warnings FATAL => 'all', NONFATAL => 'syntax';
454 As of Perl 5.20, instead of "use warnings FATAL => 'all';" you can use:
456 use v5.20; # Perl 5.20 or greater is required for the following
458 use warnings 'FATAL'; # short form of "use warnings FATAL => 'all';"
459 If you want your program to be compatible with versions of Perl before
461 5.20, you must use "use warnings FATAL => 'all';" instead. (In
462 previous versions of Perl, the behavior of the statements "use warnings
463 'FATAL';", "use warnings 'NONFATAL';" and "no warnings 'FATAL';" was
464 unspecified; they did not behave as if they included the "=> 'all'"
465 portion. As of 5.20, they do.)
466 Reporting Warnings from a Module
468 The "warnings" pragma provides a number of functions that are useful
469 for module authors. These are used when you want to report a module-
470 specific warning to a calling module has enabled warnings via the
471 "warnings" pragma.
472 Consider the module "MyMod::Abc" below.
474 package MyMod::Abc;
476 use warnings::register;
478 sub open {
480 my $path = shift;
481 if ($path !~ m#^/#) {
482 warnings::warn("changing relative path to /var/abc")
483 if warnings::enabled();
484 $path = "/var/abc/$path";
485 }
486 }
487 1;
489 The call to "warnings::register" will create a new warnings category
491 called "MyMod::Abc", i.e. the new category name matches the current
492 package name. The "open" function in the module will display a warning
493 message if it gets given a relative path as a parameter. This warnings
494 will only be displayed if the code that uses "MyMod::Abc" has actually
495 enabled them with the "warnings" pragma like below.
496 use MyMod::Abc;
498 use warnings 'MyMod::Abc';
499 ...
500 abc::open("../fred.txt");
501 It is also possible to test whether the pre-defined warnings categories
503 are set in the calling module with the "warnings::enabled" function.
504 Consider this snippet of code:
505 package MyMod::Abc;
507 sub open {
509 if (warnings::enabled("deprecated")) {
510 warnings::warn("deprecated",
511 "open is deprecated, use new instead");
512 }
513 new(@_);
514 }
515 sub new
517 ...
518 1;
519 The function "open" has been deprecated, so code has been included to
521 display a warning message whenever the calling module has (at least)
522 the "deprecated" warnings category enabled. Something like this, say.
523 use warnings 'deprecated';
525 use MyMod::Abc;
526 ...
527 MyMod::Abc::open($filename);
528 Either the "warnings::warn" or "warnings::warnif" function should be
530 used to actually display the warnings message. This is because they
531 can make use of the feature that allows warnings to be escalated into
532 fatal errors. So in this case
533 use MyMod::Abc;
535 use warnings FATAL => 'MyMod::Abc';
536 ...
537 MyMod::Abc::open('../fred.txt');
538 the "warnings::warnif" function will detect this and die after
540 displaying the warning message.
541 The three warnings functions, "warnings::warn", "warnings::warnif" and
543 "warnings::enabled" can optionally take an object reference in place of
544 a category name. In this case the functions will use the class name of
545 the object as the warnings category.
546 Consider this example:
548 package Original;
550 no warnings;
552 use warnings::register;
553 sub new
555 {
556 my $class = shift;
557 bless [], $class;
558 }
559 sub check
561 {
562 my $self = shift;
563 my $value = shift;
564 if ($value % 2 && warnings::enabled($self))
566 { warnings::warn($self, "Odd numbers are unsafe") }
567 }
568 sub doit
570 {
571 my $self = shift;
572 my $value = shift;
573 $self->check($value);
574 # ...
575 }
576 1;
578 package Derived;
580 use warnings::register;
582 use Original;
583 our @ISA = qw( Original );
584 sub new
585 {
586 my $class = shift;
587 bless [], $class;
588 }
589 1;
592 The code below makes use of both modules, but it only enables warnings
594 from "Derived".
595 use Original;
597 use Derived;
598 use warnings 'Derived';
599 my $a = Original->new();
600 $a->doit(1);
601 my $b = Derived->new();
602 $a->doit(1);
603 When this code is run only the "Derived" object, $b, will generate a
605 warning.
606 Odd numbers are unsafe at main.pl line 7
608 Notice also that the warning is reported at the line where the object
610 is first used.
611 When registering new categories of warning, you can supply more names
613 to warnings::register like this:
614 package MyModule;
616 use warnings::register qw(format precision);
617 ...
619 warnings::warnif('MyModule::format', '...');
621
623 use warnings::register
624 Creates a new warnings category with the same name as the package
625 where the call to the pragma is used.
626 warnings::enabled()
628 Use the warnings category with the same name as the current
629 package.
630 Return TRUE if that warnings category is enabled in the calling
632 module. Otherwise returns FALSE.
633 warnings::enabled($category)
635 Return TRUE if the warnings category, $category, is enabled in the
636 calling module. Otherwise returns FALSE.
637 warnings::enabled($object)
639 Use the name of the class for the object reference, $object, as the
640 warnings category.
641 Return TRUE if that warnings category is enabled in the first scope
643 where the object is used. Otherwise returns FALSE.
644 warnings::fatal_enabled()
646 Return TRUE if the warnings category with the same name as the
647 current package has been set to FATAL in the calling module.
648 Otherwise returns FALSE.
649 warnings::fatal_enabled($category)
651 Return TRUE if the warnings category $category has been set to
652 FATAL in the calling module. Otherwise returns FALSE.
653 warnings::fatal_enabled($object)
655 Use the name of the class for the object reference, $object, as the
656 warnings category.
657 Return TRUE if that warnings category has been set to FATAL in the
659 first scope where the object is used. Otherwise returns FALSE.
660 warnings::warn($message)
662 Print $message to STDERR.
663 Use the warnings category with the same name as the current
665 package.
666 If that warnings category has been set to "FATAL" in the calling
668 module then die. Otherwise return.
669 warnings::warn($category, $message)
671 Print $message to STDERR.
672 If the warnings category, $category, has been set to "FATAL" in the
674 calling module then die. Otherwise return.
675 warnings::warn($object, $message)
677 Print $message to STDERR.
678 Use the name of the class for the object reference, $object, as the
680 warnings category.
681 If that warnings category has been set to "FATAL" in the scope
683 where $object is first used then die. Otherwise return.
684 warnings::warnif($message)
686 Equivalent to:
687 if (warnings::enabled())
689 { warnings::warn($message) }
690 warnings::warnif($category, $message)
692 Equivalent to:
693 if (warnings::enabled($category))
695 { warnings::warn($category, $message) }
696 warnings::warnif($object, $message)
698 Equivalent to:
699 if (warnings::enabled($object))
701 { warnings::warn($object, $message) }
702 warnings::register_categories(@names)
704 This registers warning categories for the given names and is
705 primarily for use by the warnings::register pragma.
706 See also "Pragmatic Modules" in perlmodlib and perldiag.
708perl v5.26.3 2018-03-23 warnings(3pm)