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::re_strict
230 | |
231 | +- experimental::refaliasing
232 | |
233 | +- experimental::regex_sets
234 | |
235 | +- experimental::script_run
236 | |
237 | +- experimental::signatures
238 | |
239 | +- experimental::smartmatch
240 | |
241 | +- experimental::win32_perlio
242 |
243 +- glob
244 |
245 +- imprecision
246 |
247 +- io ------------+
248 | |
249 | +- closed
250 | |
251 | +- exec
252 | |
253 | +- layer
254 | |
255 | +- newline
256 | |
257 | +- pipe
258 | |
259 | +- syscalls
260 | |
261 | +- unopened
262 |
263 +- locale
264 |
265 +- misc
266 |
267 +- missing
268 |
269 +- numeric
270 |
271 +- once
272 |
273 +- overflow
274 |
275 +- pack
276 |
277 +- portable
278 |
279 +- recursion
280 |
281 +- redefine
282 |
283 +- redundant
284 |
285 +- regexp
286 |
287 +- severe --------+
288 | |
289 | +- debugging
290 | |
291 | +- inplace
292 | |
293 | +- internal
294 | |
295 | +- malloc
296 |
297 +- shadow
298 |
299 +- signal
300 |
301 +- substr
302 |
303 +- syntax --------+
304 | |
305 | +- ambiguous
306 | |
307 | +- bareword
308 | |
309 | +- digit
310 | |
311 | +- illegalproto
312 | |
313 | +- parenthesis
314 | |
315 | +- precedence
316 | |
317 | +- printf
318 | |
319 | +- prototype
320 | |
321 | +- qw
322 | |
323 | +- reserved
324 | |
325 | +- semicolon
326 |
327 +- taint
328 |
329 +- threads
330 |
331 +- uninitialized
332 |
333 +- unpack
334 |
335 +- untie
336 |
337 +- utf8 ----------+
338 | |
339 | +- non_unicode
340 | |
341 | +- nonchar
342 | |
343 | +- surrogate
344 |
345 +- void
346 Just like the "strict" pragma any of these categories can be combined
348 use warnings qw(void redefine);
350 no warnings qw(io syntax untie);
351 Also like the "strict" pragma, if there is more than one instance of
353 the "warnings" pragma in a given scope the cumulative effect is
354 additive.
355 use warnings qw(void); # only "void" warnings enabled
357 ...
358 use warnings qw(io); # only "void" & "io" warnings enabled
359 ...
360 no warnings qw(void); # only "io" warnings enabled
361 To determine which category a specific warning has been assigned to see
363 perldiag.
364 Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was
366 a sub-category of the "syntax" category. It is now a top-level
367 category in its own right.
368 Note: Before 5.21.0, the "missing" lexical warnings category was
370 internally defined to be the same as the "uninitialized" category. It
371 is now a top-level category in its own right.
372 Fatal Warnings
374 The presence of the word "FATAL" in the category list will escalate
375 warnings in those categories into fatal errors in that lexical scope.
376 NOTE: FATAL warnings should be used with care, particularly "FATAL =>
378 'all'".
379 Libraries using warnings::warn for custom warning categories generally
381 don't expect warnings::warn to be fatal and can wind up in an
382 unexpected state as a result. For XS modules issuing categorized
383 warnings, such unanticipated exceptions could also expose memory leak
384 bugs.
385 Moreover, the Perl interpreter itself has had serious bugs involving
387 fatalized warnings. For a summary of resolved and unresolved problems
388 as of January 2015, please see this perl5-porters post
389 <http://www.nntp.perl.org/group/perl.perl5.porters/2015/01/msg225235.html>.
390 While some developers find fatalizing some warnings to be a useful
392 defensive programming technique, using "FATAL => 'all'" to fatalize all
393 possible warning categories -- including custom ones -- is particularly
394 risky. Therefore, the use of "FATAL => 'all'" is discouraged.
395 The strictures module on CPAN offers one example of a warnings subset
397 that the module's authors believe is relatively safe to fatalize.
398 NOTE: users of FATAL warnings, especially those using "FATAL => 'all'",
400 should be fully aware that they are risking future portability of their
401 programs by doing so. Perl makes absolutely no commitments to not
402 introduce new warnings or warnings categories in the future; indeed, we
403 explicitly reserve the right to do so. Code that may not warn now may
404 warn in a future release of Perl if the Perl5 development team deems it
405 in the best interests of the community to do so. Should code using
406 FATAL warnings break due to the introduction of a new warning we will
407 NOT consider it an incompatible change. Users of FATAL warnings should
408 take special caution during upgrades to check to see if their code
409 triggers any new warnings and should pay particular attention to the
410 fine print of the documentation of the features they use to ensure they
411 do not exploit features that are documented as risky, deprecated, or
412 unspecified, or where the documentation says "so don't do that", or
413 anything with the same sense and spirit. Use of such features in
414 combination with FATAL warnings is ENTIRELY AT THE USER'S RISK.
415 The following documentation describes how to use FATAL warnings but the
417 perl5 porters strongly recommend that you understand the risks before
418 doing so, especially for library code intended for use by others, as
419 there is no way for downstream users to change the choice of fatal
420 categories.
421 In the code below, the use of "time", "length" and "join" can all
423 produce a "Useless use of xxx in void context" warning.
424 use warnings;
426 time;
428 {
430 use warnings FATAL => qw(void);
431 length "abc";
432 }
433 join "", 1,2,3;
435 print "done\n";
437 When run it produces this output
439 Useless use of time in void context at fatal line 3.
441 Useless use of length in void context at fatal line 7.
442 The scope where "length" is used has escalated the "void" warnings
444 category into a fatal error, so the program terminates immediately when
445 it encounters the warning.
446 To explicitly turn off a "FATAL" warning you just disable the warning
448 it is associated with. So, for example, to disable the "void" warning
449 in the example above, either of these will do the trick:
450 no warnings qw(void);
452 no warnings FATAL => qw(void);
453 If you want to downgrade a warning that has been escalated into a fatal
455 error back to a normal warning, you can use the "NONFATAL" keyword.
456 For example, the code below will promote all warnings into fatal
457 errors, except for those in the "syntax" category.
458 use warnings FATAL => 'all', NONFATAL => 'syntax';
460 As of Perl 5.20, instead of "use warnings FATAL => 'all';" you can use:
462 use v5.20; # Perl 5.20 or greater is required for the following
464 use warnings 'FATAL'; # short form of "use warnings FATAL => 'all';"
465 If you want your program to be compatible with versions of Perl before
467 5.20, you must use "use warnings FATAL => 'all';" instead. (In
468 previous versions of Perl, the behavior of the statements "use warnings
469 'FATAL';", "use warnings 'NONFATAL';" and "no warnings 'FATAL';" was
470 unspecified; they did not behave as if they included the "=> 'all'"
471 portion. As of 5.20, they do.)
472 Reporting Warnings from a Module
474 The "warnings" pragma provides a number of functions that are useful
475 for module authors. These are used when you want to report a module-
476 specific warning to a calling module has enabled warnings via the
477 "warnings" pragma.
478 Consider the module "MyMod::Abc" below.
480 package MyMod::Abc;
482 use warnings::register;
484 sub open {
486 my $path = shift;
487 if ($path !~ m#^/#) {
488 warnings::warn("changing relative path to /var/abc")
489 if warnings::enabled();
490 $path = "/var/abc/$path";
491 }
492 }
493 1;
495 The call to "warnings::register" will create a new warnings category
497 called "MyMod::Abc", i.e. the new category name matches the current
498 package name. The "open" function in the module will display a warning
499 message if it gets given a relative path as a parameter. This warnings
500 will only be displayed if the code that uses "MyMod::Abc" has actually
501 enabled them with the "warnings" pragma like below.
502 use MyMod::Abc;
504 use warnings 'MyMod::Abc';
505 ...
506 abc::open("../fred.txt");
507 It is also possible to test whether the pre-defined warnings categories
509 are set in the calling module with the "warnings::enabled" function.
510 Consider this snippet of code:
511 package MyMod::Abc;
513 sub open {
515 if (warnings::enabled("deprecated")) {
516 warnings::warn("deprecated",
517 "open is deprecated, use new instead");
518 }
519 new(@_);
520 }
521 sub new
523 ...
524 1;
525 The function "open" has been deprecated, so code has been included to
527 display a warning message whenever the calling module has (at least)
528 the "deprecated" warnings category enabled. Something like this, say.
529 use warnings 'deprecated';
531 use MyMod::Abc;
532 ...
533 MyMod::Abc::open($filename);
534 Either the "warnings::warn" or "warnings::warnif" function should be
536 used to actually display the warnings message. This is because they
537 can make use of the feature that allows warnings to be escalated into
538 fatal errors. So in this case
539 use MyMod::Abc;
541 use warnings FATAL => 'MyMod::Abc';
542 ...
543 MyMod::Abc::open('../fred.txt');
544 the "warnings::warnif" function will detect this and die after
546 displaying the warning message.
547 The three warnings functions, "warnings::warn", "warnings::warnif" and
549 "warnings::enabled" can optionally take an object reference in place of
550 a category name. In this case the functions will use the class name of
551 the object as the warnings category.
552 Consider this example:
554 package Original;
556 no warnings;
558 use warnings::register;
559 sub new
561 {
562 my $class = shift;
563 bless [], $class;
564 }
565 sub check
567 {
568 my $self = shift;
569 my $value = shift;
570 if ($value % 2 && warnings::enabled($self))
572 { warnings::warn($self, "Odd numbers are unsafe") }
573 }
574 sub doit
576 {
577 my $self = shift;
578 my $value = shift;
579 $self->check($value);
580 # ...
581 }
582 1;
584 package Derived;
586 use warnings::register;
588 use Original;
589 our @ISA = qw( Original );
590 sub new
591 {
592 my $class = shift;
593 bless [], $class;
594 }
595 1;
598 The code below makes use of both modules, but it only enables warnings
600 from "Derived".
601 use Original;
603 use Derived;
604 use warnings 'Derived';
605 my $a = Original->new();
606 $a->doit(1);
607 my $b = Derived->new();
608 $a->doit(1);
609 When this code is run only the "Derived" object, $b, will generate a
611 warning.
612 Odd numbers are unsafe at main.pl line 7
614 Notice also that the warning is reported at the line where the object
616 is first used.
617 When registering new categories of warning, you can supply more names
619 to warnings::register like this:
620 package MyModule;
622 use warnings::register qw(format precision);
623 ...
625 warnings::warnif('MyModule::format', '...');
627
629 Note: The functions with names ending in "_at_level" were added in Perl
630 5.28.
631 use warnings::register
633 Creates a new warnings category with the same name as the package
634 where the call to the pragma is used.
635 warnings::enabled()
637 Use the warnings category with the same name as the current
638 package.
639 Return TRUE if that warnings category is enabled in the calling
641 module. Otherwise returns FALSE.
642 warnings::enabled($category)
644 Return TRUE if the warnings category, $category, is enabled in the
645 calling module. Otherwise returns FALSE.
646 warnings::enabled($object)
648 Use the name of the class for the object reference, $object, as the
649 warnings category.
650 Return TRUE if that warnings category is enabled in the first scope
652 where the object is used. Otherwise returns FALSE.
653 warnings::enabled_at_level($category, $level)
655 Like "warnings::enabled", but $level specifies the exact call
656 frame, 0 being the immediate caller.
657 warnings::fatal_enabled()
659 Return TRUE if the warnings category with the same name as the
660 current package has been set to FATAL in the calling module.
661 Otherwise returns FALSE.
662 warnings::fatal_enabled($category)
664 Return TRUE if the warnings category $category has been set to
665 FATAL in the calling module. Otherwise returns FALSE.
666 warnings::fatal_enabled($object)
668 Use the name of the class for the object reference, $object, as the
669 warnings category.
670 Return TRUE if that warnings category has been set to FATAL in the
672 first scope where the object is used. Otherwise returns FALSE.
673 warnings::fatal_enabled_at_level($category, $level)
675 Like "warnings::fatal_enabled", but $level specifies the exact call
676 frame, 0 being the immediate caller.
677 warnings::warn($message)
679 Print $message to STDERR.
680 Use the warnings category with the same name as the current
682 package.
683 If that warnings category has been set to "FATAL" in the calling
685 module then die. Otherwise return.
686 warnings::warn($category, $message)
688 Print $message to STDERR.
689 If the warnings category, $category, has been set to "FATAL" in the
691 calling module then die. Otherwise return.
692 warnings::warn($object, $message)
694 Print $message to STDERR.
695 Use the name of the class for the object reference, $object, as the
697 warnings category.
698 If that warnings category has been set to "FATAL" in the scope
700 where $object is first used then die. Otherwise return.
701 warnings::warn_at_level($category, $level, $message)
703 Like "warnings::warn", but $level specifies the exact call frame, 0
704 being the immediate caller.
705 warnings::warnif($message)
707 Equivalent to:
708 if (warnings::enabled())
710 { warnings::warn($message) }
711 warnings::warnif($category, $message)
713 Equivalent to:
714 if (warnings::enabled($category))
716 { warnings::warn($category, $message) }
717 warnings::warnif($object, $message)
719 Equivalent to:
720 if (warnings::enabled($object))
722 { warnings::warn($object, $message) }
723 warnings::warnif_at_level($category, $level, $message)
725 Like "warnings::warnif", but $level specifies the exact call frame,
726 0 being the immediate caller.
727 warnings::register_categories(@names)
729 This registers warning categories for the given names and is
730 primarily for use by the warnings::register pragma.
731 See also "Pragmatic Modules" in perlmodlib and perldiag.
733perl v5.28.2 2018-11-01 warnings(3pm)