1warnings(3pm)          Perl Programmers Reference Guide          warnings(3pm)
2
3
4

NAME

6       warnings - Perl pragma to control optional warnings
7

SYNOPSIS

9           use warnings;
10           no warnings;
11
12           use warnings "all";
13           no warnings "all";
14
15           use warnings::register;
16           if (warnings::enabled()) {
17               warnings::warn("some warning");
18           }
19
20           if (warnings::enabled("void")) {
21               warnings::warn("void", "some warning");
22           }
23
24           if (warnings::enabled($object)) {
25               warnings::warn($object, "some warning");
26           }
27
28           warnings::warnif("some warning");
29           warnings::warnif("void", "some warning");
30           warnings::warnif($object, "some warning");
31

DESCRIPTION

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
37       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
43       By default, optional warnings are disabled, so any legacy code that
44       doesn't attempt to control the warnings will work unchanged.
45
46       All warnings are enabled in a block by either of these:
47
48           use warnings;
49           use warnings 'all';
50
51       Similarly all warnings are disabled in a block by either of these:
52
53           no warnings;
54           no warnings 'all';
55
56       For example, consider the code below:
57
58           use warnings;
59           my @a;
60           {
61               no warnings;
62               my $b = @a[0];
63           }
64           my $c = @a[0];
65
66       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
71   Default Warnings and Optional Warnings
72       Before the introduction of lexical warnings, Perl had two classes of
73       warnings: mandatory and optional.
74
75       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
80           my $a = "2:" + 3;
81
82       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
89           my $a = "2:" + 3;
90           no warnings;
91           my $b = "2:" + 3;
92
93       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
96   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
104       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
108            {
109                local ($^W) = 0;
110                my $a =+ 2;
111                my $b; chop $b;
112            }
113
114       When this code is run with the -w flag, a warning will be produced for
115       the $a line:  "Reversed += operator".
116
117       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
121            {
122                BEGIN { $^W = 0 }
123                my $a =+ 2;
124                my $b; chop $b;
125            }
126
127       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
133           sub doit
134           {
135               my $b; chop $b;
136           }
137
138           doit();
139
140           {
141               local ($^W) = 1;
142               doit()
143           }
144
145       This is a side-effect of $^W being dynamically scoped.
146
147       Lexical warnings get around these limitations by allowing finer control
148       over where warnings can or can't be tripped.
149
150   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
154       -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
160       -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
166       -X   Does the exact opposite to the -W flag, i.e. it disables all
167            warnings.
168
169   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
174       How Lexical Warnings interact with -w/$^W:
175
176       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
182       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
186       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
190       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
194       5.   The only way to override a lexical warnings setting is with the -W
195            or -X command line flags.
196
197       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
201   Category Hierarchy
202       A hierarchy of "categories" have been defined to allow groups of
203       warnings to be enabled/disabled in isolation.
204
205       The current hierarchy is:
206
207           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
353       Just like the "strict" pragma any of these categories can be combined
354
355           use warnings qw(void redefine);
356           no warnings qw(io syntax untie);
357
358       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
362           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
368       To determine which category a specific warning has been assigned to see
369       perldiag.
370
371       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
375       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
379   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
383       NOTE: FATAL warnings should be used with care, particularly "FATAL =>
384       'all'".
385
386       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
392       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
397       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
402       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
405       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
422       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
428       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
431           use warnings;
432
433           time;
434
435           {
436               use warnings FATAL => qw(void);
437               length "abc";
438           }
439
440           join "", 1,2,3;
441
442           print "done\n";
443
444       When run it produces this output
445
446           Useless use of time in void context at fatal line 3.
447           Useless use of length in void context at fatal line 7.
448
449       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
453       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
457           no warnings qw(void);
458           no warnings FATAL => qw(void);
459
460       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
465           use warnings FATAL => 'all', NONFATAL => 'syntax';
466
467       As of Perl 5.20, instead of "use warnings FATAL => 'all';" you can use:
468
469          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
472       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
479   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
485       Consider the module "MyMod::Abc" below.
486
487           package MyMod::Abc;
488
489           use warnings::register;
490
491           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
500           1;
501
502       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
509           use MyMod::Abc;
510           use warnings 'MyMod::Abc';
511           ...
512           abc::open("../fred.txt");
513
514       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
518           package MyMod::Abc;
519
520           sub open {
521               if (warnings::enabled("deprecated")) {
522                   warnings::warn("deprecated",
523                                  "open is deprecated, use new instead");
524               }
525               new(@_);
526           }
527
528           sub new
529           ...
530           1;
531
532       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
536           use warnings 'deprecated';
537           use MyMod::Abc;
538           ...
539           MyMod::Abc::open($filename);
540
541       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
546           use MyMod::Abc;
547           use warnings FATAL => 'MyMod::Abc';
548           ...
549           MyMod::Abc::open('../fred.txt');
550
551       the "warnings::warnif" function will detect this and die after
552       displaying the warning message.
553
554       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
559       Consider this example:
560
561           package Original;
562
563           no warnings;
564           use warnings::register;
565
566           sub new
567           {
568               my $class = shift;
569               bless [], $class;
570           }
571
572           sub check
573           {
574               my $self = shift;
575               my $value = shift;
576
577               if ($value % 2 && warnings::enabled($self))
578                 { warnings::warn($self, "Odd numbers are unsafe") }
579           }
580
581           sub doit
582           {
583               my $self = shift;
584               my $value = shift;
585               $self->check($value);
586               # ...
587           }
588
589           1;
590
591           package Derived;
592
593           use warnings::register;
594           use Original;
595           our @ISA = qw( Original );
596           sub new
597           {
598               my $class = shift;
599               bless [], $class;
600           }
601
602
603           1;
604
605       The code below makes use of both modules, but it only enables warnings
606       from "Derived".
607
608           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
616       When this code is run only the "Derived" object, $b, will generate a
617       warning.
618
619           Odd numbers are unsafe at main.pl line 7
620
621       Notice also that the warning is reported at the line where the object
622       is first used.
623
624       When registering new categories of warning, you can supply more names
625       to warnings::register like this:
626
627           package MyModule;
628           use warnings::register qw(format precision);
629
630           ...
631
632           warnings::warnif('MyModule::format', '...');
633

FUNCTIONS

635       Note: The functions with names ending in "_at_level" were added in Perl
636       5.28.
637
638       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
642       warnings::enabled()
643           Use the warnings category with the same name as the current
644           package.
645
646           Return TRUE if that warnings category is enabled in the calling
647           module.  Otherwise returns FALSE.
648
649       warnings::enabled($category)
650           Return TRUE if the warnings category, $category, is enabled in the
651           calling module.  Otherwise returns FALSE.
652
653       warnings::enabled($object)
654           Use the name of the class for the object reference, $object, as the
655           warnings category.
656
657           Return TRUE if that warnings category is enabled in the first scope
658           where the object is used.  Otherwise returns FALSE.
659
660       warnings::enabled_at_level($category, $level)
661           Like "warnings::enabled", but $level specifies the exact call
662           frame, 0 being the immediate caller.
663
664       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
669       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
673       warnings::fatal_enabled($object)
674           Use the name of the class for the object reference, $object, as the
675           warnings category.
676
677           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
680       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
684       warnings::warn($message)
685           Print $message to STDERR.
686
687           Use the warnings category with the same name as the current
688           package.
689
690           If that warnings category has been set to "FATAL" in the calling
691           module then die. Otherwise return.
692
693       warnings::warn($category, $message)
694           Print $message to STDERR.
695
696           If the warnings category, $category, has been set to "FATAL" in the
697           calling module then die. Otherwise return.
698
699       warnings::warn($object, $message)
700           Print $message to STDERR.
701
702           Use the name of the class for the object reference, $object, as the
703           warnings category.
704
705           If that warnings category has been set to "FATAL" in the scope
706           where $object is first used then die. Otherwise return.
707
708       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
712       warnings::warnif($message)
713           Equivalent to:
714
715               if (warnings::enabled())
716                 { warnings::warn($message) }
717
718       warnings::warnif($category, $message)
719           Equivalent to:
720
721               if (warnings::enabled($category))
722                 { warnings::warn($category, $message) }
723
724       warnings::warnif($object, $message)
725           Equivalent to:
726
727               if (warnings::enabled($object))
728                 { warnings::warn($object, $message) }
729
730       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
734       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
738       See also "Pragmatic Modules" in perlmodlib and perldiag.
739
740
741
742perl v5.30.2                      2020-03-27                     warnings(3pm)
Impressum