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