Lexical::SealRequireHints - prevent leakage of lexical hints
This module works around two historical bugs in Perl's handling of the
%^H (lexical hints) variable. One bug causes lexical state in one file to leak into another that is
used from it. This bug, [perl #68590], was present from Perl 5.6 up to Perl 5.10, fixed in Perl 5.11.0. The second bug causes lexical state (normally a blank
%^H once the first bug is fixed) to leak outwards from
utf8.pm, if it is automatically loaded during Unicode regular expression matching, into whatever source is compiling at the time of the regexp match. This bug, [perl #73174], was present from Perl 5.8.7 up to Perl 5.11.5, fixed in Perl 5.12.0.
Both of these bugs seriously damage the usability of any module relying on
%^H for lexical scoping, on the affected Perl versions. It is in practice essential to work around these bugs when using such modules. On versions of Perl that require such a workaround, this module globally changes the behaviour of
use and the implicit
require performed in Unicode regular expression matching, so that it no longer exhibits these bugs.
The workaround supplied by this module takes effect the first time its
import method is called. Typically this will be done by means of a
use statement. This should be done as early as possible, because it only affects
use statements that are compiled after the workaround goes into effect. For
use statements, and
require statements that are executed immediately and only once, it suffices to invoke the workaround when loading the first module that will set up vulnerable lexical state. Delayed-action
require statements, however, are more troublesome, and can require the workaround to be loaded much earlier. Ultimately, an affected Perl program may need to load the workaround as very nearly its first action. Invoking this module multiple times, from multiple modules, is not a problem: the workaround is only applied once, and applies to everything subsequently compiled.
This module is implemented in XS, with a pure Perl backup version for systems that can't handle XS modules. The XS version has a better chance of playing nicely with other modules that modify
require handling. The pure Perl version can't work at all on some Perl versions; users of those versions must use the XS. On all Perl versions suffering the underlying hint leakage bug, pure Perl hooking of
require breaks the use of
require without an explicit parameter (implicitly using
The history of the
%^H bugs is complex. Here is a chronological statement of the relevant changes.
- Perl 5.6.0
%^Hintroduced. It exists only as a hash at compile time. It is not localised by
require, so lexical hints leak into every module loaded, which is bug [perl #68590].
CORE::GLOBALmechanism doesn't work cleanly for
require, because overriding
requireloses the necessary special parsing of bareword arguments to it. As a result, pure Perl code can't properly globally affect the behaviour of
require. Pure Perl code can localise
%^Hitself for any particular
requireinvocation, but a global fix is only possible through XS.
- Perl 5.7.2
CORE::GLOBALmechanism now works cleanly for
require, so pure Perl code can globally affect the behaviour of
requireto achieve a global fix for the bug.
- Perl 5.8.7
utf8.pmis automatically loaded during Unicode regular expression matching,
%^Hnow leaks outward from it into whatever source is compiling at the time of the regexp match, which is bug [perl #73174]. It often goes unnoticed, because [perl #68590] makes
utf8.pmwhich then doesn't modify it, so what leaks out tends to be identical to what leaked in. If [perl #68590] is worked around, however,
%^Htends to be (correctly) blank inside
utf8.pm, and this bug therefore blanks it for the outer module.
- Perl 5.9.4
%^Hnow exists in two forms. In addition to the relatively ordinary hash that is modified during compilation, the value that it had at each point in compilation is recorded in the compiled op tree, for later examination at runtime. It is in a special representation-sharing format, and writes to
%^Hare meant to be performed on both forms.
requiredoes not localise the runtime form of
%^H(and still doesn't localise the compile-time form).
A couple of special
%^Hentries are erroneously written only to the runtime form.
Pure Perl code, although it can localise the compile-time
%^Hby normal means, can't adequately localise the runtime
%^H, except by using a string eval stack frame. This makes a satisfactory global fix for the leakage bug impossible in pure Perl.
- Perl 5.10.1
requirenow properly localises the runtime form of
%^H, but still not the compile-time form.
A global fix is once again possible in pure Perl, because the fix only needs to localise the compile-time form.
- Perl 5.11.0
requirenow properly localises both forms of
%^H, fixing [perl #68590]. This makes [perl #73174] apparent without any workaround for [perl #68590].
%^Hentries are now correctly written to both forms of the hash.
- Perl 5.12.0
The automatic loading of
utf8.pmduring Unicode regular expression matching now properly restores
%^H, fixing [perl #73174].
The operation of this module depends on influencing the compilation of
require. As a result, it cannot prevent lexical state leakage through a
require statement that was compiled before this module was invoked. Where problems occur, this module must be invoked earlier.
On all Perl versions that need a fix for the lexical hint leakage bug, the pure Perl implementation of this module unavoidably breaks the use of
require without an explicit parameter (implicitly using
$_). This is due to another bug in the Perl core, fixed in Perl 5.15.5, and is inherent to the mechanism by which pure Perl code can hook
require. The use of implicit
require is rare, so although this state of affairs is faulty it will actually work for most programs. Perl versions 5.12.0 and greater, despite having the
require hooking bug, don't actually exhibit a problem with the pure Perl version of this module, because with the lexical hint leakage bug fixed there is no need for this module to hook
Andrew Main (Zefram) <email@example.com>
Copyright (C) 2009, 2010, 2011, 2012, 2015, 2016 Andrew Main (Zefram) <firstname.lastname@example.org>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.