Technisch artikel

Range check-fouten in Delphi PDF-bibliotheken: oorzaken

Een Delphi-programma stopt met ERangeError en de kale melding "Range check error", vaak in slechts één van uw twee buildconfiguraties. Delphi werpt deze exceptie wanneer code die met range checking is gecompileerd ({$R+}) een array of string buiten zijn grenzen indexeert, of een waarde opslaat die niet in het doelordinaaltype past. De oplossing hoort bijna altijd waar de slechte index of waarde werd berekend, en dat is zelden de regel waar de debugger stopt

Wat betekent "Range check error" in Delphi?

ERangeError komt uit controles die de compiler invoegt wanneer range checking aan staat. Met {$R+} (lange vorm {$RANGECHECKS ON}, of Project Options › Building › Delphi Compiler › Compiling › Range checking) wordt elk array- en string-subscript vergeleken met de gedeclareerde grenzen, en wordt elke toewijzing aan een kleiner ordinaal, subrange of enumeratievariabele vergeleken met het bereik van dat type. De standaardtoestand is {$R-}, en code die zo is gecompileerd bevat helemaal geen controles, dus een schrijfactie buiten de grenzen belandt gewoon in het geheugen ernaast. Een mislukte controle werpt ERangeError op met de resourcestring "Range check error" zodra SysUtils is gelinkt; een programma dat SysUtils nooit gebruikt, eindigt met runtime error 201. De compile-time-fout E1012 (Constant expression violates subrange bounds) dekt alleen indexen die de compiler als constante ziet; alles wat runtime wordt berekend, hangt af van {$R+}. De schakelaar werkt ook per unit: voorgecompileerde DCU's houden de toestand waarmee ze zijn gebouwd, en een {$R-} bovenaan een unit overschrijft de projectoptie voor die unit

Overflow checking is een aparte schakelaar met een aparte exceptie. {$Q+} ({$OVERFLOWCHECKS ON}) controleert integerrekenkunde zoals +, -, *, Inc en Dec en werpt EIntOverflow op wanneer een resultaat niet past; {$R+} controleert indexen en opslag. De twee raken elkaar in kleine typen. Byte-rekenkunde wordt geëvalueerd als Integer, dus B := B + 1 met B = 255 levert 256 op zonder enige overflow, en het is de opslag terug in de Byte die de range check laat falen. Inc(B) op dezelfde waarde is in plaats daarvan een overflow-gecontroleerde bewerking: met {$Q+} werpt hij EIntOverflow op, en met alleen {$R+} loopt hij stilletjes over naar 0. Welke configuraties deze schakelaars aan hebben, hangt af van de Delphi-versie en van hoe het project is aangemaakt. Lees de werkelijke waarden in Project Options voor elke buildconfiguratie voordat u een theorie vertrouwt over waarom de fout in één build verschijnt

De gebruikelijke oorzaken, met minimale reproducties

De meeste range check-fouten in echte Delphi-code vallen in een handjevol patronen, elk met een kleine, mechanische oplossing. Arrays zijn het meest voorkomende geval. Een statische array[0..9] accepteert indexen 0 tot 9, een dynamische array of TBytes accepteert 0..Length(A) - 1, en strings zijn 1-based, dus schrijf lussen tegen Low en High in plaats van hard gecodeerde grenzen. Het lege geval is waar code breekt. High van een lege dynamische array is -1, dus een lus for I := 0 to High(A) met een Integer-teller draait correct nul keer, terwijl A[High(A)] of A[Count - 1] om "het laatste element" op te halen index -1 leest. Verwante gevallen gedragen zich anders:

  • Containerklassen controleren hun eigen indexen, wat de {$R}-toestand ook is: TList en TStringList werpen EListError of EStringListError op, en TList<T> werpt EArgumentOutOfRangeException op
  • Aantallen die als Cardinal of DWORD uit een bestandsheader of een API komen, zijn bij nul gevaarlijk, want waartoe Count - 1 evalueert hangt af van hoe de compiler de expressie typeert; houd lustellers Integer, valideer het aantal één keer, converteer het, en test Count > 0 expliciet
procedure ArrayRepros(const Data: TBytes; Buf: Pointer);
var
  Last: Byte;
  P: PByte;
  I: Integer;
begin
  // Lege array: High(Data) = -1, dus dit leest Data[-1]
  Last := Data[High(Data)];               // ERangeError onder {$R+}

  // Oplossing: test de lengte voordat u om het laatste element vraagt
  if Length(Data) > 0 then
    Last := Data[High(Data)];

  // TByteArray is gedeclareerd als array[0..32767] of Byte, dus onder {$R+}
  // faalt elke index boven 32767, ook als Buf megabytes bevat
  I := 40000;
  Last := PByteArray(Buf)^[I];            // ERangeError bij I = 40000

  // Oplossing: indexeer de echte buffer, of gebruik PByte-rekenkunde
  P := PByte(Buf);
  Inc(P, I);
  Last := P^;                             // geen range check, dus valideer I zelf
end;

Het PByteArray-geval vangt ervaren ontwikkelaars, want de gedeclareerde grens heeft niets met de buffer te maken. Zowel de SysUtils van Delphi als die van Free Pascal declareert TByteArray als array[0..32767] of Byte, een venster van 32 KB dat teruggaat op 16-bits code. Onder {$R+} vergelijkt de controle uw index met 32767, dus een geldige offset in een stream van 100 KB werpt ERangeError op; onder {$R-} is er geen controle en wordt een index voorbij het echte einde van de buffer nooit opgemerkt. De TBytes zelf indexeren geeft u een controle tegen de werkelijke lengte, en dat maakt het de betere standaardkeuze. PByte-rekenkunde wordt helemaal niet range-gecontroleerd. Koppel er een expliciete test tegen de buffergrootte aan

Ordinale opslag is de andere grote familie. 256 aan een Byte toewijzen, 70000 aan een Word, of 13 aan een subrange 1..12 laat de controle falen, en hetzelfde geldt voor het toewijzen van een negatieve Integer aan een Cardinal. Delphi evalueert gemengde signed- en unsigned-32-bits-operanden als Int64, dus de rekenkunde zelf klopt meestal en de fout verschijnt bij de opslag, wat u wijst op de variabele waarvan het type te smal is. Harde typecasts zijn het gat in dit net: Byte(I), Cardinal(I) en TMyEnum(I) genereren geen range check en kappen of herinterpreteren stilletjes. Wanneer een 32-bits waarde uit een bestand een enum-lid kiest, vergelijk hem dan als Cardinal met Ord(High(TMyEnum)) vóór de cast

var
  B: Byte;
  C: Cardinal;
  I: Integer;
  Addr: Integer;
  Obj: TObject;
begin
  B := 255;
  B := B + 1;            // geëvalueerd als Integer 256, opslag faalt: ERangeError

  I := -1;
  C := I;                // negatief in Cardinal: ERangeError
  C := Cardinal(I);      // harde cast: geen controle, C = 4294967295

  // Win64: pointers zijn 8 bytes, Integer blijft 4
  Obj := TObject.Create;
  Addr := NativeInt(Obj);  // Integer: faalt boven 2 GB (Cardinal: boven 4 GB)
  // Oplossing: houd pointer-grote waarden in NativeInt / NativeUInt
end;

// Modulo-2^32-rekenkunde die zich onder Delphi en FPC hetzelfde gedraagt
function AddMod32(A, B: Cardinal): Cardinal; inline;
begin
  Result := Cardinal((UInt64(A) + UInt64(B)) and $FFFFFFFF);
end;

Win64 voegt een pointergrote variant op dezelfde fout toe. Pointer, NativeInt, TComponent.Tag (een NativeInt sinds XE2), LPARAM en WPARAM zijn op Win64 allemaal 8 bytes, terwijl Integer, Longint en Cardinal op 4 blijven. Een adres opslaan via een range-gecontroleerde toewijzing werpt ERangeError op zodra het adres buiten het bereik van het doeltype ligt: boven 2 GB voor Integer, boven 4 GB voor Cardinal. Het opslaan via een harde cast kapt het af en veroorzaakt later een access violation. Kleine testprogramma's alloceren vaak laag in de adresruimte, dus deze klasse bugs toont zich eerder in langlopende processen dan in unittests. Declareer alles wat een pointer, een handle of een message-parameter bevat als NativeInt of NativeUInt. De Longint- en pointervalkuilen op Linux64 volgen dezelfde logica voor LP64-targets, waar Longint zelf van grootte verandert

Waarom verschijnt de fout alleen in Debug, of alleen onder FPC?

Een range check-fout die in slechts één build verschijnt, is bijna altijd een echte toegang buiten de grenzen die de andere build niet controleert. Release-builds met {$R-} draaien dezelfde foutieve index zonder klacht en lezen ofwel het geheugen van een buurman of corrumperen het, wat erger is dan de exceptie. Free Pascal voegt eigen schakelaars toe. {$mode delphi} verandert taalsyntaxis en -semantiek maar zet geen enkele controle aan; range checking onder FPC komt uit {$R+} of de command-line-optie -Cr, en overflow checking uit -Co, die Lazarus toont onder Project Options › Compiler Options › Debugging. FPC evalueert integerexpressies bovendien in de native integergrootte of groter, dus een expressie die stilletjes overloopt in 32-bits Delphi kan op een 64-bits FPC-target een waarde boven High(Cardinal) opleveren, en het terug opslaan in de Cardinal laat de controle falen. Wij troffen precies dit in onze eigen SHA-256-code: de modulo-232-optellingen, geschreven als gewone Cardinal-sommen, gaven Range check error in een gecontroleerde FPC-build. Optellen in UInt64 en maskeren, zoals AddMod32 hierboven doet, houdt de output byte voor byte identiek op beide compilers zonder de controles voor de hele unit uit te zetten. Meer portabiliteitsvalkuilen van dit soort zijn verzameld in Delphi-code die onder FPC alleen per toeval werkt

De debugger op de regel laten stoppen die de fout opwierp

De snelste manier om een range check-fout te vinden is de IDE-debugger erop te laten breken en de call stack op te lopen naar de code die de slechte waarde produceerde. De exceptie markeert waar de controle afging. De oorzaak zit meestal een paar frames lager:

  1. Draai de Debug-configuratie met range checking aan, en zorg dat ERangeError niet in de genegeerde lijst staat op de pagina Language Exceptions van de debuggeropties
  2. Als het dialoogvenster meldt "raised exception class ERangeError with message 'Range check error'", kies dan Break en open het venster Call Stack; de frames onder de bovenste tonen waar de index of waarde vandaan kwam
  3. Zitten de bovenste frames in de RTL of VCL, zet dan "Use debug .dcus" aan zodat die frames naar broncode resolven
  4. Zet een conditioneel breekpunt op de toewijzing die de index berekent (bijvoorbeeld Index < 0) om de fout één stap eerder te vangen dan de exceptie doet
  5. Voor fouten die alleen op de machine van een klant optreden: lever de build met range checking aan plus een stack-trace-logger zoals madExcept, EurekaLog of JCL Debug, die dezelfde call stack naar een logbestand schrijft

Moet u range checking uitzetten?

Houd range checking aan in elke Debug- en CI-build, en zet hem alleen lokaal uit, rond een gemeten hete lus waarvan u de grenzen zelf valideert. Hem globaal uitzetten verwijdert de bug niet; het verwijdert het rapport. Een klassiek voorbeeld is een hex-formatteringsroutine die SetLength(Result, 16) aanroept en de tekens 17 tot en met 24 wegschrijft: onder {$R+} faalt hij onmiddellijk, onder {$R-} schrijft hij bij elke aanroep acht tekens voorbij het einde van de string, in welk heapgeheugen erop volgt, en crasht hij veel later ergens ongerelateerd. Als een routine echt te heet is voor controles, scope de wijziging dan correct. {$R-} gevolgd door {$R+} oogt netjes maar forceert checking aan voor de rest van de unit, ook als het project hem uit had, dus bewaar en herstel de vorige toestand, en houd het ongecontroleerde gebied beperkt tot één kleine routine waarvan de aanroepers de grenzen afdwingen

{$IFOPT R+}
  {$DEFINE RANGECHECKS_WERE_ON}
  {$R-}
{$ENDIF}
procedure XorBlock(Dst, Src: PByte; Count: Integer);
var
  I: Integer;
begin
  // Aanroepers garanderen dat Count in beide buffers past; één keer buiten de lus gecontroleerd
  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}

Range check-fouten in PDF-parseercode

Code die PDF-bestanden parseert is extra kwetsbaar, want bijna elk getal dat hij als index gebruikt komt uit het bestand zelf. Byte-offsets in de kruisverwijzingstabel, /Length-waarden van streams, veldbreedtes in de /W-array van een cross-reference stream (ISO 32000-1 §7.5.8), objectaantallen en /ByteRange-entries in handtekeningen zijn allemaal onbetrouwbaar in een misvormd of vijandig bestand. Een naïeve bewaking zoals if A + B > Length(Data) faalt tegen een vervalste /ByteRange [9223372036854775807 1 0 0]: met overflow checking uit loopt A + B over naar een negatieve Int64, de test slaagt, en Data[A] faalt later. Test elke waarde tegen de resterende lengte ((A >= 0) and (B >= 0) and (A <= Len) and (B <= Len - A)) zodat geen enkele optelling kan overlopen. Samengestelde bewakingen verbergen nog een valkuil. Delphi evalueert and met short-circuit van links naar rechts, maar een alleenstaande bovengrenstest verwerpt geen negatieve index, want -1 < Length(FPages) is True; de signed-ondergrens moet vóór de bovengrens worden getest

// Oogt veilig, maar een negatieve PageIndex passeert de bovengrenstest:
//   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]);
Stroomdiagram van een Delphi range check-fout waarbij een negatieve DestIndex een eenzijdige grenscontrole omzeilt en ERangeError opwerpt bij de arraytoegang, vergeleken met de gecorrigeerde volgorde van de bewaking die veilig short-circuit
Onder $R+ wordt elk subscript tijdens runtime gecontroleerd, dus een negatieve index overleeft een kale bovengrenstest en gaat af bij de arraytoegang zelf. De ondertekende ondergrens eerst testen laat short-circuit-evaluatie hem afwijzen voordat er ook maar één element wordt aangeraakt

De bewaking stopt de crash maar verklaart niet waarom de index verkeerd was, en in pagina-afhandelingscode is de gebruikelijke reden een mismatch tussen twee volgordes. ISO 32000-1 §7.7.3 definieert de paginavolgorde via de Kids-arrays van de paginaboom; objectnummers en byte-offsets zeggen er niets over, en object 20 kan pagina 1 bevatten terwijl object 3 pagina 2 bevat. Code die zijn paginalijst opbouwt door objecten in bestandsvolgorde te scannen, werkt op elk document waarvan de generator de pagina's op volgorde schreef, en gaat mis op het eerste document waar dat niet zo is, zoals een bewerkt bestand met een later toegevoegd voorblad. Indexen die aanroepers in weergavevolgorde berekenen landen op de verkeerde pagina of voorbij het einde van de lijst. De casestudy over PDF-paginavolgorde laat zien hoe u de mismatch met qpdf bevestigt en de paginalijst opnieuw opbouwt vanuit de paginaboom

Delphi-diagram dat de opslagvolgorde van PDF-objecten zoals ontdekt door een kruisverwijzingsscan afzet tegen de weergavevolgorde die wordt hersteld door de Kids-array van de paginaboom vanuit de catalog te doorlopen
Sequentiële scans nummeren pagina's in de volgorde die de schrijver koos, terwijl viewers de Kids-array van de paginaboom volgen. De pagina-array opbouwen uit de doorloop van de catalog houdt de indices van de aanroeper uitgelijnd en binnen bereik

Om deze fouten uit uw eigen parser te schudden: bouw hem met {$R+} en {$Q+} en draai hem over een gevarieerd corpus: bestanden van Word, LaTeX, scannerfirmware, splits-en-voeg-samen-hulpprogramma's en een paar bewust afgekapte. Elk bestand dat een exceptie uitlokt is een datapunt over een aanname die uw code maakt, dus fix de aanname één keer in plaats van een per-generator speciaal geval toe te voegen dat op de volgende bron op het verkeerde moment afgaat. Voor code die een PDF-bibliotheek aanroept: behandel het paginaaantal van de bibliotheek als gezaghebbend. In de HotPDF Delphi PDF-component geeft LoadFromFile het paginaaantal van het geladen document terug en rapporteert LoadedPageCount het daarna; pagina-indexen volgen de weergavevolgorde van de paginaboom, dus 0..LoadedPageCount - 1 is het veilige bereik voor elke index die u uit externe data afleidt