1Lexical::SealRequireHinUtsse(r3pCmo)ntributed Perl DocumLeenxtiactailo:n:SealRequireHints(3pm)
2
6 Lexical::SealRequireHints - prevent leakage of lexical hints
7
9 use Lexical::SealRequireHints;
10
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/"do"ed from it.
15 This bug, [perl #68590], was present from Perl 5.6 up to Perl 5.10,
16 fixed in Perl 5.11.0. The second bug causes lexical state (normally a
17 blank "%^H" once the first bug is fixed) to leak outwards from
18 "utf8.pm", if it is automatically loaded during Unicode regular
19 expression matching, into whatever source is compiling at the time of
20 the regexp match. This bug, [perl #73174], was present from Perl 5.8.7
21 up to Perl 5.11.5, fixed in Perl 5.12.0.
22 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,
29 and of "do", so that they no longer exhibit these bugs.
30 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"/"do" statements that are compiled after
35 the workaround goes into effect. For "use" statements, and "require"
36 and "do" statements that are executed immediately and only once, it
37 suffices to invoke the workaround when loading the first module that
38 will set up vulnerable lexical state. Delayed-action "require" and
39 "do" statements, however, are more troublesome, and can require the
40 workaround to be loaded much earlier. Ultimately, an affected Perl
41 program may need to load the workaround as very nearly its first
42 action. Invoking this module multiple times, from multiple modules, is
43 not a problem: the workaround is only applied once, and applies to
44 everything subsequently compiled.
45 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" or
49 "do" 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
56 The history of the "%^H" bugs is complex. Here is a chronological
57 statement of the relevant changes.
58 Perl 5.6.0
60 "%^H" introduced. It exists only as a hash at compile time. It is
61 not localised by "require"/"do", so lexical hints leak into every
62 module loaded, which is bug [perl #68590].
63 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 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 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 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"/"do" does not localise the
94 runtime form of "%^H" (and still doesn't localise the compile-time
95 form).
96 A couple of special "%^H" entries are erroneously written only to
98 the runtime form.
99 Pure Perl code, although it can localise the compile-time "%^H" by
101 normal means, can't adequately localise the runtime "%^H", except
102 by using a string eval stack frame. This makes a satisfactory
103 global fix for the leakage bug impossible in pure Perl.
104 Perl 5.10.1
106 "require"/"do" now properly localise the runtime form of "%^H", but
107 still not the compile-time form.
108 A global fix is once again possible in pure Perl, because the fix
110 only needs to localise the compile-time form.
111 Perl 5.11.0
113 "require"/"do" now properly localise both forms of "%^H", fixing
114 [perl #68590]. This makes [perl #73174] apparent without any
115 workaround for [perl #68590].
116 The special "%^H" entries are now correctly written to both forms
118 of the hash.
119 Perl 5.12.0
121 The automatic loading of "utf8.pm" during Unicode regular
122 expression matching now properly restores "%^H", fixing [perl
123 #73174].
124
126 The operation of this module depends on influencing the compilation of
127 "require" and "do". As a result, it cannot prevent lexical state
128 leakage through a "require"/"do" statement that was compiled before
129 this module was invoked. Where problems occur, this module must be
130 invoked earlier.
131 On all Perl versions that need a fix for the lexical hint leakage bug,
133 the pure Perl implementation of this module unavoidably breaks the use
134 of "require" without an explicit parameter (implicitly using $_). This
135 is due to another bug in the Perl core, fixed in Perl 5.15.5, and is
136 inherent to the mechanism by which pure Perl code can hook "require".
137 The use of implicit $_ with "require" is rare, so although this state
138 of affairs is faulty it will actually work for most programs. Perl
139 versions 5.12.0 and greater, despite having the "require" hooking bug,
140 don't actually exhibit a problem with the pure Perl version of this
141 module, because with the lexical hint leakage bug fixed there is no
142 need for this module to hook "require".
143 There is a bug on Perl versions 5.15.5 to 5.15.7 affecting "do" which,
145 among other effects, causes "%^H" to leak into "do"ed files. It is not
146 the same bug that affected Perl 5.6 to 5.11. This module currently
147 does not work around this bug at all, but its test suite does detect
148 it. As a result, this module fails its test suite on those Perl
149 versions. This could change in future versions of this module.
150
152 perlpragma
153
155 Andrew Main (Zefram) <zefram@fysh.org>
156
158 Copyright (C) 2009, 2010, 2011, 2012, 2015, 2016, 2017, 2023 Andrew
159 Main (Zefram) <zefram@fysh.org>
160
162 This module is free software; you can redistribute it and/or modify it
163 under the same terms as Perl itself.
164perl v5.38.0 2023-07-20 Lexical::SealRequireHints(3pm)