1Lexical::SealRequireHinUtsse(r3)Contributed Perl DocumenLteaxtiicoanl::SealRequireHints(3)
2
3
4

NAME

6       Lexical::SealRequireHints - prevent leakage of lexical hints
7

SYNOPSIS

9               use Lexical::SealRequireHints;
10

DESCRIPTION

12       This module works around two historical bugs in Perl's handling of the
13       "%^H" (lexical hints) variable.  One bug causes lexical state in one
14       file to leak into another that is "require"d/"use"d from it.  This bug,
15       [perl #68590], was present from Perl 5.6 up to Perl 5.10, fixed in Perl
16       5.11.0.  The second bug causes lexical state (normally a blank "%^H"
17       once the first bug is fixed) to leak outwards from "utf8.pm", if it is
18       automatically loaded during Unicode regular expression matching, into
19       whatever source is compiling at the time of the regexp match.  This
20       bug, [perl #73174], was present from Perl 5.8.7 up to Perl 5.11.5,
21       fixed in Perl 5.12.0.
22
23       Both of these bugs seriously damage the usability of any module relying
24       on "%^H" for lexical scoping, on the affected Perl versions.  It is in
25       practice essential to work around these bugs when using such modules.
26       On versions of Perl that require such a workaround, this module
27       globally changes the behaviour of "require", including "use" and the
28       implicit "require" performed in Unicode regular expression matching, so
29       that it no longer exhibits these bugs.
30
31       The workaround supplied by this module takes effect the first time its
32       "import" method is called.  Typically this will be done by means of a
33       "use" statement.  This should be done as early as possible, because it
34       only affects "require"/"use" statements that are compiled after the
35       workaround goes into effect.  For "use" statements, and "require"
36       statements that are executed immediately and only once, it suffices to
37       invoke the workaround when loading the first module that will set up
38       vulnerable lexical state.  Delayed-action "require" statements,
39       however, are more troublesome, and can require the workaround to be
40       loaded much earlier.  Ultimately, an affected Perl program may need to
41       load the workaround as very nearly its first action.  Invoking this
42       module multiple times, from multiple modules, is not a problem: the
43       workaround is only applied once, and applies to everything subsequently
44       compiled.
45
46       This module is implemented in XS, with a pure Perl backup version for
47       systems that can't handle XS modules.  The XS version has a better
48       chance of playing nicely with other modules that modify "require"
49       handling.  The pure Perl version can't work at all on some Perl
50       versions; users of those versions must use the XS.  On all Perl
51       versions suffering the underlying hint leakage bug, pure Perl hooking
52       of "require" breaks the use of "require" without an explicit parameter
53       (implicitly using $_).
54

PERL VERSION DIFFERENCES

56       The history of the "%^H" bugs is complex.  Here is a chronological
57       statement of the relevant changes.
58
59       Perl 5.6.0
60           "%^H" introduced.  It exists only as a hash at compile time.  It is
61           not localised by "require", so lexical hints leak into every module
62           loaded, which is bug [perl #68590].
63
64           The "CORE::GLOBAL" mechanism doesn't work cleanly for "require",
65           because overriding "require" loses the necessary special parsing of
66           bareword arguments to it.  As a result, pure Perl code can't
67           properly globally affect the behaviour of "require".  Pure Perl
68           code can localise "%^H" itself for any particular "require"
69           invocation, but a global fix is only possible through XS.
70
71       Perl 5.7.2
72           The "CORE::GLOBAL" mechanism now works cleanly for "require", so
73           pure Perl code can globally affect the behaviour of "require" to
74           achieve a global fix for the bug.
75
76       Perl 5.8.7
77           When "utf8.pm" is automatically loaded during Unicode regular
78           expression matching, "%^H" now leaks outward from it into whatever
79           source is compiling at the time of the regexp match, which is bug
80           [perl #73174].  It often goes unnoticed, because [perl #68590]
81           makes "%^H" leak into "utf8.pm" which then doesn't modify it, so
82           what leaks out tends to be identical to what leaked in.  If [perl
83           #68590] is worked around, however, "%^H" tends to be (correctly)
84           blank inside "utf8.pm", and this bug therefore blanks it for the
85           outer module.
86
87       Perl 5.9.4
88           "%^H" now exists in two forms.  In addition to the relatively
89           ordinary hash that is modified during compilation, the value that
90           it had at each point in compilation is recorded in the compiled op
91           tree, for later examination at runtime.  It is in a special
92           representation-sharing format, and writes to "%^H" are meant to be
93           performed on both forms.  "require" does not localise the runtime
94           form of "%^H" (and still doesn't localise the compile-time form).
95
96           A couple of special "%^H" entries are erroneously written only to
97           the runtime form.
98
99           Pure Perl code, although it can localise the compile-time "%^H" by
100           normal means, can't adequately localise the runtime "%^H", except
101           by using a string eval stack frame.  This makes a satisfactory
102           global fix for the leakage bug impossible in pure Perl.
103
104       Perl 5.10.1
105           "require" now properly localises the runtime form of "%^H", but
106           still not the compile-time form.
107
108           A global fix is once again possible in pure Perl, because the fix
109           only needs to localise the compile-time form.
110
111       Perl 5.11.0
112           "require" now properly localises both forms of "%^H", fixing [perl
113           #68590].  This makes [perl #73174] apparent without any workaround
114           for [perl #68590].
115
116           The special "%^H" entries are now correctly written to both forms
117           of the hash.
118
119       Perl 5.12.0
120           The automatic loading of "utf8.pm" during Unicode regular
121           expression matching now properly restores "%^H", fixing [perl
122           #73174].
123

BUGS

125       The operation of this module depends on influencing the compilation of
126       "require".  As a result, it cannot prevent lexical state leakage
127       through a "require" statement that was compiled before this module was
128       invoked.  Where problems occur, this module must be invoked earlier.
129
130       On all Perl versions that need a fix for the lexical hint leakage bug,
131       the pure Perl implementation of this module unavoidably breaks the use
132       of "require" without an explicit parameter (implicitly using $_).  This
133       is due to another bug in the Perl core, fixed in Perl 5.15.5, and is
134       inherent to the mechanism by which pure Perl code can hook "require".
135       The use of implicit $_ with "require" is rare, so although this state
136       of affairs is faulty it will actually work for most programs.  Perl
137       versions 5.12.0 and greater, despite having the "require" hooking bug,
138       don't actually exhibit a problem with the pure Perl version of this
139       module, because with the lexical hint leakage bug fixed there is no
140       need for this module to hook "require".
141

SEE ALSO

143       perlpragma
144

AUTHOR

146       Andrew Main (Zefram) <zefram@fysh.org>
147
149       Copyright (C) 2009, 2010, 2011, 2012, 2015, 2016, 2017 Andrew Main
150       (Zefram) <zefram@fysh.org>
151

LICENSE

153       This module is free software; you can redistribute it and/or modify it
154       under the same terms as Perl itself.
155
156
157
158perl v5.34.0                      2022-01-21      Lexical::SealRequireHints(3)
Impressum