"... where is that behavior documented?"

The "Illegal division by zero" example is documented in eval. This has additional information about $SIG{__DIE__}.

die also has information about $SIG{__DIE__}.

More general information related to this topic can be found in local, perlsub, perlipc and, as already noted, perlvar.

I meant specifically that local %SIG; does not appear to affect the signal handlers, even though it creates a local, empty %SIG, does not appear to be documented.

use warnings;
use strict;

use Data::Dumper;
local $SIG{__WARN__} = sub { warn "outer: $_[0]" };
warn "one\n";
{
    local $SIG{__WARN__} = sub { warn "inner 1: $_[0]" };
    warn "two\n";
    {
        local %SIG;
        warn "three\n";
        print Dumper(\%SIG);
        {
            local $SIG{__WARN__} = sub { warn "inner 2: $_[0]" };
            warn "four\n";
        }
    }
    warn "five\n";
}
warn "six\n";

__END__

outer: one
inner 1: two
inner 1: three
$VAR1 = {};
inner 2: four
five
outer: six
[download]

Okay, so the result for "five" isn't correct... looks like there really may be a bug somewhere.

Okay, so the result for "five" isn't correct... looks like there really may be a bug somewhere.

This is a bug. The result for "five" should be "inner 1: five". The code reference is still in place, but the warn vector seems to be clobbered by the aliasing of %SIG inside the scope of the previous block. Commenting out the local %SIG; line makes the line warn "five\n"; work as expected.

Update: I filed a bug report. Thanks, Anonymous Monk.

perl -le'print map{pack c,($-++?1:13)+ord}split//,ESEL'

Fair enough. Obviously, your reference to "It" wasn't specific enough. :-)

[Disclaimer: The following is my best guess. This isn't my area of expertise. I could be entirely wrong.]

In perlsub, under Localization of special variables, it says:

"If you localize a special variable, you'll be giving a new value to it, but its magic won't go away. That means that all side-effects related to this magic still work with the localized value."

Localizing %SIG and the $SIG{__WARN__} magic remains:

$ perl -wE 'warn 1; $SIG{__WARN__} = sub { say "WARN: $_[0]" }; warn 2
+; { local %SIG; warn 3 } warn 4'
1 at -e line 1.
WARN: 2 at -e line 1.

WARN: 3 at -e line 1.

WARN: 4 at -e line 1.
[download]

However, localizing $SIG{__WARN__} and the magic is temporarily removed:

$ perl -wE 'warn 1; $SIG{__WARN__} = sub { say "WARN: $_[0]" }; warn 2
+; { local $SIG{__WARN__}; warn 3 } warn 4'
1 at -e line 1.
WARN: 2 at -e line 1.

3 at -e line 1.
WARN: 4 at -e line 1.
[download]

— Ken

> looks like there really may be a bug somewhere.

IMHO local %SIG shouldn't be allowed and throw an error.

Such special vars are far too magic to allow any useful localization of complete hashes.

Cheers Rolf
_{(addicted to the Perl Programming Language and ☆☆☆☆ :)
Je suis Charlie!}