0180 - A reviewed non-SEH routine is pinned to its own source text, not its whole file
Date: 2026-11-06
Area: build, windows, exceptions
Issue: #2111
Refines: ADR 0169
Context
ADR 0169's post-link step refuses any project text section whose routine name
looks like an exception handler unless the manifest classifies it. A
source-nonseh entry clears a reviewed ordinary routine. In manifest format 1
its SHA-256 covered the routine's whole source file, so any edit to that file
failed the i386-win32 build. Every one of the eight commits that touched the
manifest after SafeSEH landed only refreshed those hashes, and none of them
changed a routine's classification. Goccia.VM.pas holds eight of the
routines and is the engine file edited most often. Refreshing a whole-file hash
after an unrelated edit also teaches contributors to refresh it without
reviewing the routine, which weakens the review the pin exists for.
Decision
Manifest format 2 (FPC-SAFESEH 2) binds each source-nonseh digest to the
implementation of the routine its section names, from the first token of its
header through the semicolon after its final end. CRLF and CR line endings
are normalised to LF; comments and whitespace inside the routine stay in the
digest. A format 1 manifest is refused, not read as routine digests.
The locator in source/shared/FPCRoutineSource.pas finds the routine from the
section name and refuses, rather than falling back to a broader or empty span,
whenever it cannot be sure the text it hashes is the text that was compiled:
- It accepts unit-level routines and methods of plain types in a unit or program, and the source must declare the section's unit or program. Nested routines and methods of nested or generic types are refused.
- It does not decode the section's parameter suffix (
$crc…or the parameter types). The name must therefore have exactly one implementation in its scope: overloads are refused, and so is a nested routine with the same name as a reviewed unit-level routine. - It lexes the whole file in Delphi mode and parses it through the final
end.. Text it cannot parse, a routine keyword inside a statement block, another{$mode}and{$modeswitch nestedcomments}are refused, so no implementation can go unseen. - An include inside the routine is refused. Every other include is searched
as FPC 3.2.4 searches it. FPC tries the name, then
.inc,.ppand.pas. For each, it looks beside the includer, then in the compiler's working directory, then insource/units,source/sharedandsouffle(the-Fidirectories ofconfig.cfgand CI). On Linux and macOS it also tries the lowercased and uppercased name, which the locator tries on every host. An absolute name is read only from its own directory. The working directory is the repository root forbuild.pas, and the unit directory thatcompile-programs.pypasses to--apply. If a name matches files with different text, the include is refused, because FPC's choice would depend on where it ran. FPC searches an include's own includes beside the copy it read, so an include found in more than one directory may not include more.{$INCLUDEPATH},*names and names ending in.are refused. The include must contain no routine or module keyword, so it cannot hold an implementation the parse misses. The parse does not read included text, so an include must also leave the block structure as it found it. In a statement block, itsbegin,case,tryandasmblocks must close within it, in every branch of its conditionals. Anywhere else it may hold only directives and comments. An include that closed a record could otherwise hide the compiled routine from the parse. Includes inside an assembler block, and conditionals left open in an include file, are refused. Macros are refused. - The parse reads every branch of a conditional, so in the implementation
part each conditional group must leave the parse unchanged whichever branch
the compiler takes. A group must stay within one routine's statements at one
block depth, one declaration level or type body, or one uses clause, and at
declaration level each branch must begin and end next to
;or a section keyword. A dead branch therefore cannot hide the compiled routine, and the digest covers every branch inside the reviewed routine.
safeseh --digests [manifest] prints every entry with its routine's current
digest, line range and status, and never rewrites the manifest. Unknown
handler-like names, owner binding, and the RTL object hashes are unchanged.
Consequences
An edit outside the pinned routines needs no manifest change. An edited,
renamed or removed pinned routine still fails finalization and check, naming
the routine and its file. The contributor reviews the routine again before
copying its line from safeseh --digests.
The digest covers only the implementation. A declaration elsewhere, for example a calling convention in the interface or class body, and code elsewhere that could install the routine as a handler, are outside it. Format 1 also covered the rest of the same file, though not other files. The name rule remains a review checkpoint, not a proof that no frame registers the routine; that proof is the machine-code analysis #2111 leaves out of scope.
A construct the locator cannot parse fails the Win32 build of a file that has
a pinned routine, and the error says that the file cannot be parsed at that
line rather than that the routine changed. Fix it by restructuring the code or
by extending the locator with tests, never by weakening a refusal. Pull
requests build on Linux only, so FPCSafeSEH.Test checks every entry of the
repository manifest. An edited pinned routine, or a file the locator cannot
parse, then fails before it merges rather than on the Win32 build of main.
Win32 exception metadata owns the procedure.