技术文章

Delphi 中的范围检查错误:原因与修复

Delphi 程序带着 ERangeError 和一句光秃秃的 "Range check error" 停下来,而且常常只在两个构建配置中的一个里出现。当代码在开启范围检查({$R+})的情况下编译,索引落到数组或字符串边界之外,或者把一个装不进目标序数类型的值存进去,Delphi 就会抛这个异常。修复几乎总该落在算出坏索引或坏值的地方,而那里很少是调试器停下的那一行

Delphi 里的 "Range check error" 是什么意思?

ERangeError 来自编译器在范围检查开启时插入的检查。{$R+}(长写法 {$RANGECHECKS ON},或 Project Options › Building › Delphi Compiler › Compiling › Range checking)之下,每个数组与字符串下标都会对着声明的边界比一遍,每次向更小的序数、子界或枚举变量的赋值都会对着该类型的范围比一遍。默认状态是 {$R-},这样编译出来的代码完全不含检查,越界写入就直接落到隔壁的内存里。检查失败且链接了 SysUtils 时,抛出带资源字符串 "Range check error" 的 ERangeError;从不用 SysUtils 的程序则以运行时错误 201 终止。编译期错误 E1012(Constant expression violates subrange bounds)只覆盖编译器看得见的常量索引;一切运行时算出来的值都取决于 {$R+}。这个开关还能按单元生效:预编译 DCU 保留编译时的状态,单元顶部的 {$R-} 会为该单元覆盖工程选项

溢出检查是另一个开关,配另一个异常。{$Q+}({$OVERFLOWCHECKS ON})检查 +、-、*、Inc、Dec 这类整数算术,结果装不下时抛 EIntOverflow;{$R+} 检查的是索引和存储。两者在小类型上交汇。Byte 算术按 Integer 求值,所以 B := B + 1 在 B = 255 时算出 256 而没有任何溢出,是把结果存回 Byte 的那一下触发了范围检查。同一个值上的 Inc(B) 却是溢出检查操作:{$Q+} 之下抛 EIntOverflow,只开 {$R+} 时静默回绕到 0。哪些配置开着这些开关,取决于 Delphi 版本和工程的创建方式。在对「为什么错误只出现在某个构建」下结论之前,先去 Project Options 里读每个构建配置的实际值

常见病因,附最小复现

真实 Delphi 代码里的范围检查错误大多落进几种模式,每种都有小而机械的修法。数组是最常见的情形。静态 array[0..9] 接受 0 到 9 的索引,动态数组或 TBytes 接受 0..Length(A) - 1,字符串从 1 起算,所以循环要对着 Low 和 High 写,别硬编码界限。空集合是代码翻车的地方:空动态数组的 High 是 -1,所以用 Integer 计数器的 for I := 0 to High(A) 循环正确地跑零次,而用来取「最后一个元素」的 A[High(A)] 或 A[Count - 1] 读的是索引 -1。相关情形表现各异:

  • 容器类自己检查索引,与 {$R} 状态无关:TList 和 TStringList 抛 EListError 或 EStringListError,TList<T> 抛 EArgumentOutOfRangeException
  • 从文件头或 API 进来、类型是 Cardinal 或 DWORD 的计数在为零时很危险,因为 Count - 1 求出什么取决于编译器如何定型表达式;循环计数器保持 Integer,计数只验证一次、验证完就转换,并显式测试 Count > 0
procedure ArrayRepros(const Data: TBytes; Buf: Pointer);
var
  Last: Byte;
  P: PByte;
  I: Integer;
begin
  // 空数组:High(Data) = -1,所以这读取 Data[-1]
  Last := Data[High(Data)];               // {$R+} 下抛 ERangeError

  // 修复:取最后元素前先测长度
  if Length(Data) > 0 then
    Last := Data[High(Data)];

  // TByteArray 声明为 array[0..32767] of Byte,所以 {$R+} 下
  // 即使 Buf 里装着几 MB,超过 32767 的索引也会失败
  I := 40000;
  Last := PByteArray(Buf)^[I];            // I = 40000 时抛 ERangeError

  // 修复:直接索引真实缓冲区,或用 PByte 算术
  P := PByte(Buf);
  Inc(P, I);
  Last := P^;                             // 无范围检查,I 的校验自己做
end;

PByteArray 这个案例能坑到老手,因为声明的边界与缓冲区毫无关系。Delphi 的 SysUtils 和 Free Pascal 的都把 TByteArray 声明为 array[0..32767] of Byte——一个源于 16 位时代的 32 KB 窗口。{$R+} 之下,检查拿你的索引和 32767 比,于是在 100 KB 流里的合法偏移也抛 ERangeError;{$R-} 之下没有检查,越过缓冲区真实末尾的索引永远不会被抓到。直接索引 TBytes 本身得到的是对实际长度的检查,这让它成为更好的默认选择。PByte 算术完全不在范围检查之内,用它就得配一个对着缓冲区大小的显式测试

序数存储是另一大类。把 256 赋给 Byte、70000 赋给 Word、13 赋给 1..12 子界都会挂,把负的 Integer 赋给 Cardinal 也一样。Delphi 把带符号与无符号混合的 32 位操作数按 Int64 求值,所以算术本身通常没错,错误出现在存储那一步——这恰好指向那个类型太窄的变量。硬类型转型是这张网的漏洞:Byte(I)、Cardinal(I)、TMyEnum(I) 不生成任何范围检查,静默截断或重解释。当一个从文件读出的 32 位值要挑选枚举成员时,先把它当 Cardinal 与 Ord(High(TMyEnum)) 比较再转型

var
  B: Byte;
  C: Cardinal;
  I: Integer;
  Addr: Integer;
  Obj: TObject;
begin
  B := 255;
  B := B + 1;            // 按 Integer 求值得 256,存储时失败:ERangeError

  I := -1;
  C := I;                // 负数存进 Cardinal:ERangeError
  C := Cardinal(I);      // 硬转型:无检查,C = 4294967295

  // Win64:指针 8 字节,Integer 仍是 4
  Obj := TObject.Create;
  Addr := NativeInt(Obj);  // Integer:超过 2 GB 失败(Cardinal:超过 4 GB)
  // 修复:指针大小的值放 NativeInt / NativeUInt
end;

// 必须在 Delphi 和 FPC 下行为一致的模 2^32 加法
function AddMod32(A, B: Cardinal): Cardinal; inline;
begin
  Result := Cardinal((UInt64(A) + UInt64(B)) and $FFFFFFFF);
end;

Win64 还带来同一错误的指针宽度变体。Win64 上 Pointer、NativeInt、TComponent.Tag(自 XE2 起是 NativeInt)、LPARAM 和 WPARAM 都是 8 字节,而 Integer、Longint、Cardinal 仍是 4。经由带范围检查的赋值去存一个地址,一旦地址超出目标类型的范围就抛 ERangeError:Integer 是 2 GB 以上,Cardinal 是 4 GB 以上。经硬转型去存则截断它,晚些时候以 access violation 的形式爆发。小测试程序常常分配在地址空间的低位,所以这类 bug 倾向于出现在长期运行的进程里而不是单元测试里。凡是持有指针、句柄或消息参数的声明,都用 NativeInt 或 NativeUInt。Linux64 上的 Longint 与指针陷阱对 LP64 目标遵循同样的逻辑,那里 Longint 本身会变尺寸

为什么错误只在 Debug 出现,或者只在 FPC 下出现?

只在单一构建里出现的范围检查错误,几乎总是真实的越界访问,只不过另一个构建没在检查。带着 {$R-} 的 Release 构建对同一个坏索引毫无怨言地跑过去,读邻居的内存或把它改坏——这比异常更糟。Free Pascal 另有一套开关。{$mode delphi} 改语言语法与语义,但不打开任何检查;FPC 的范围检查来自 {$R+} 或命令行选项 -Cr,溢出检查来自 -Co,Lazarus 把它摆在 Project Options › Compiler Options › Debugging。FPC 还按原生整数宽度或更大来求值整数表达式,一个在 32 位 Delphi 里静默回绕的表达式,在 64 位 FPC 目标上可能算出超过 High(Cardinal) 的值,存回 Cardinal 就挂了。我们自己的 SHA-256 代码就撞上过:写成普通 Cardinal 加法的模 232 加法,在开检查的 FPC 构建里抛 Range check error。像上面的 AddMod32 那样用 UInt64 求和再掩码,两个编译器的输出逐字节一致,也不必给整个单元关检查。这类可移植性陷阱的更多案例收在只在 FPC 下碰巧能跑的 Delphi 代码里

让调试器停在抛错的那一行

找范围检查错误最快的办法,是让 IDE 调试器在它上面断下来,然后沿调用栈往上走到算出坏值的代码。异常标记的是检查触发点,病因通常在下面几帧:

  1. 用开着范围检查的 Debug 配置运行,并确认 ERangeError 不在调试器选项 Language Exceptions 页的忽略列表里
  2. 对话框报告 "raised exception class ERangeError with message 'Range check error'" 时,选 Break 并打开 Call Stack 窗口;顶帧之下的各帧显示索引或值的来路
  3. 如果顶帧在 RTL 或 VCL 里,打开 "Use debug .dcus" 让那些帧解析到源码
  4. 在计算索引的赋值上设条件断点(例如 Index < 0),比异常早一步抓住错误
  5. 只发生在客户机器上的错误,出货的构建带着范围检查加一个栈回溯日志器,比如 madExcept、EurekaLog 或 JCL Debug,它会把同样的调用栈写进日志文件

该不该把范围检查关掉?

每个 Debug 和 CI 构建都保持范围检查开启,只在局部、在你自己验证边界的实测热点循环周围关它。全局关掉不会移除 bug,只是移除了报告。一个经典例子是调用 SetLength(Result, 16) 却写第 17 到 24 个字符的十六进制格式化例程:{$R+} 之下立刻失败,{$R-} 之下每次调用都往字符串末尾之外写八个字符,写进后面跟着的任何堆内存,很久之后在毫不相干的地方崩溃。例程真的热到检查都嫌贵时,把改动圈对范围。{$R-} 后跟 {$R+} 看着整齐,却会强行给单元剩余部分打开检查,哪怕工程原本关着;正确做法是保存并恢复之前的状态,并把无检查区域限定在一个完整的小例程里,由它的调用者保证边界

{$IFOPT R+}
  {$DEFINE RANGECHECKS_WERE_ON}
  {$R-}
{$ENDIF}
procedure XorBlock(Dst, Src: PByte; Count: Integer);
var
  I: Integer;
begin
  // 调用方保证 Count 在两个缓冲区之内;循环外一次性检查
  for I := 0 to Count - 1 do
    Dst[I] := Dst[I] xor Src[I];
end;
{$IFDEF RANGECHECKS_WERE_ON}
  {$UNDEF RANGECHECKS_WERE_ON}
  {$R+}
{$ENDIF}

PDF 解析代码里的范围检查错误

解析 PDF 文件的代码格外暴露,因为它拿来当索引用的几乎每个数字都来自文件本身。交叉引用表里的字节偏移、流的 /Length 值、交叉引用流 /W 数组里的字段宽度(ISO 32000-1 §7.5.8)、对象计数和签名里的 /ByteRange 条目,在畸形或恶意文件里全是不可信的。天真的守卫如 if A + B > Length(Data),对一份精心构造的 /ByteRange [9223372036854775807 1 0 0] 就会失守:溢出检查关着时 A + B 回绕成负的 Int64,测试通过,Data[A] 在后面才失败。把每个值对着剩余长度测((A >= 0) and (B >= 0) and (A <= Len) and (B <= Len - A)),任何加法就都回绕不了。复合守卫还藏着另一个陷阱。Delphi 的 and 从左到右短路,但只有上界测试并不能拒绝负索引,因为 -1 < Length(FPages) 是 True;带符号的下界必须先于上界测试

// 看着安全,但负的 PageIndex 能通过上界检查:
//   if FDocOpen and (PageIndex < Length(FPages)) and
//      (FPages[PageIndex].PageObj <> nil) then ...

if (PageIndex >= 0) and (PageIndex < Length(FPages)) then
begin
  if FDocOpen and (FPages[PageIndex].PageObj <> nil) then
    Result := FPages[PageIndex].PageObj
  else
    Result := nil;
end
else
  raise ERangeError.CreateFmt(
    'Page index %d is out of range (0..%d)',
    [PageIndex, Length(FPages) - 1]);
Delphi 范围检查错误流程图:负的 DestIndex 绕过单边边界检查并在数组访问处引发 ERangeError,对比可安全短路的修正守护顺序
在 $R+ 下 RTL 于运行时校验每个下标,负索引能通过单纯的上界检查,在数组访问处才爆发。先检查带符号的下界,让短路求值在任何元素被触碰之前将其拒绝

守卫挡住了崩溃,却解释不了索引为什么是错的,而在页面处理代码里,常见的原因是两套顺序对不上。ISO 32000-1 §7.7.3 用页面树的 Kids 数组定义页序;对象号和字节偏移对页序只字未提,对象 20 可以装着第 1 页而对象 3 装着第 2 页。按文件顺序扫对象来搭页面清单的代码,在所有生成器按顺序写页面的文档上都正常,在任何一份没按顺序写的文档上出错——比如后来加过封面页的编辑文件。调用者按显示顺序算出的索引,要么落在错误的页面上,要么越过清单末尾。PDF 页序案例研究演示了如何用 qpdf 证实错位、如何从页面树重建页面清单

Delphi 示意图:对比由交叉引用扫描发现的 PDF 对象存储顺序与从 catalog 沿页面树 Kids 数组遍历恢复的显示顺序
顺序扫描按写入器任选的顺序编号页面,而阅读器遵循页面树的 Kids 数组。从 Catalog 遍历构建页面数组,调用方索引才能对齐且不越界

想把这些错误从自己的解析器里抖落出来,用 {$R+} 和 {$Q+} 构建它,然后拿一份多样的语料跑过去:Word、LaTeX、扫描仪固件、拆分合并工具产出的文件,再添几份故意截断的。每个触发异常的文件都是一个数据点,暴露你代码做出的一条假设;把假设修一次,别加那种针对特定生成器的特例——它会在下一份来源上于错误的时刻触发。对调用 PDF 库的代码,把库的页面计数当作权威。在 HotPDF Delphi PDF component 里,LoadFromFile 返回已加载文档的页数,LoadedPageCount 事后报告它;页索引跟随页面树的显示顺序,所以从外部数据推导的任何索引,0..LoadedPageCount - 1 都是安全范围