forked from project-jedi/jcl
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathDebug.dtx
2356 lines (2350 loc) · 86.1 KB
/
Debug.dtx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@@Debugging.Diagnostics
<GROUP Debugging>
<TITLE Diagnostics>
<TOPICORDER 100>
--------------------------------------------------------------------------------
@@Debugging.Exceptframeinforoutines
<GROUP Debugging>
<TITLE Except frame info routines>
<TOPICORDER 200>
--------------------------------------------------------------------------------
@@Debugging.Exceptionhooking
<GROUP Debugging>
<TITLE Exception hooking>
<TOPICORDER 300>
--------------------------------------------------------------------------------
@@Debugging.Helpers
<GROUP Debugging>
<TITLE Helpers>
<TOPICORDER 400>
--------------------------------------------------------------------------------
@@Debugging.Miscellanuous
<GROUP Debugging>
<TITLE Miscellanuous>
<TOPICORDER 500>
--------------------------------------------------------------------------------
@@Debugging.SourceLocations
<GROUP Debugging>
<TITLE Source Locations>
<TOPICORDER 600>
--------------------------------------------------------------------------------
@@Debugging.SourceLocations.BinaryDebugData
<GROUP Debugging.SourceLocations>
<TITLE Binary Debug Data>
<TOPICORDER 100>
--------------------------------------------------------------------------------
@@Debugging.SourceLocations.MapParsers
<GROUP Debugging.SourceLocations>
<TITLE Map Parsers>
<TOPICORDER 200>
--------------------------------------------------------------------------------
@@Debugging.Stackinforoutines
<GROUP Debugging>
<TITLE Stack info routines>
<TOPICORDER 700>
--------------------------------------------------------------------------------
@@Debugging.Trackingroutines
<GROUP Debugging>
<TITLE Tracking routines>
<TOPICORDER 800>
--------------------------------------------------------------------------------
@@IsHandleValid
<GROUP Debugging.Miscellanuous>
Summary:
Tests whether a handle is valid.
Description:
The IsHandleValid determines whether a handle is valid. The handle can point to
any kind of Win32 object such as a file, mutex or console screen buffer. Note that
the result of this function is only an indication of whether the handle points
to a valid object. Since handles are reused by Win32 it is possible that the
handle actually points to a different object than you thought. More reason to
always set handles to 0 or INVALID_HANDLE_VALUE immediately after you close it.
Parameters:
Handle - The handle to test for validity.
Result:
If the specified handle is valid the function returns True. If the specified
handle is invalid the function returns False.
Donator:
Marcel van Brakel
--------------------------------------------------------------------------------
@@IsDebuggerAttached
<GROUP Debugging.Miscellanuous>
Summary:
Determines whether the calling process is running under the context of a debugger.
Description:
The IsDebuggerAttached function determines whether the calling process is running
under the context of a debugger. Unlike the IsDebuggerPresent API function, this
one also functions correctly under Windows 95.
Result:
If the current process is running in the context of a debugger, the return value is True.
If the current process is not running in the context of a debugger, the return value is False.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@EnableCrashOnCtrlScroll
<GROUP Debugging.Miscellanuous>
Summary:
Enables manually crashing Windows.
Description:
EnableCrashOnCtrlScroll enables crashing Windows 2000 using the keyboard. After
this has been enabled you can bugcheck Windows 2000 by holding down the right
control key and pressing the scroll key twice. On the second press Windows will
bugcheck with code 0x000000E2. Note that this function simply modifies a registry
entry, to actually enable this 'feature' you must reboot first.
Parameters:
Enable - If set to True the crash on ctrl scroll 'feature' is enabled, if set to False it is disabled.
Result:
If the function succeeds it returns True, otherwise it returns False.
Donator:
Marcel van Brakel
--------------------------------------------------------------------------------
@@AssertKindOf
<GROUP Debugging.Diagnostics>
Summary:
Asserts that an object is of a specified class.
Description:
AssertKindOf asserts that the specified object is of the specified type or inherits
from that type. If this is not the case the function triggers an assertion failure.
The overloaded procedure allows you to directly specify a class type instead of
a class name.
Parameters:
ClassName - Name of the class to test Obj for.
Obj - The object to test.
Donator:
Marcel van Brakel
--------------------------------------------------------------------------------
@@Trace
<GROUP Debugging.Diagnostics>
Summary:
Sends a message to the debugger.
Description:
Trace sends the specified message to the debugger.
Parameters:
Msg - The message to send to the debugger.
Notes:
If you are running your application under the control of the debugger you can view these messages using the event log dialog, 'View | Debug Windows | Event Log'. If the application is not running under the debugger the message is sent to the system debugger. If there is no system debugger active the function does nothing.
See also:
TraceFmt
TraceLoc
TraceLocFmt
Donator:
Marcel van Brakel
--------------------------------------------------------------------------------
@@TraceFmt
<GROUP Debugging.Diagnostics>
Summary:
Sends a formatted message to the debugger.
Description:
TraceFmt sends a message, formatted from the supplied format string and
arguments array, to the debugger. The function uses the VCL Format() function
to format the string and therefore you can use this function exactly like you
would use Format(). See the Delphi help file for more information.
Parameters:
Fmt - Controls the formatting of the message.
Args - Arguments formatted under control of the Fmt string.
Notes:
If you are running your application under the control of the debugger you can view these messages using the event log dialog, 'View | Debug Windows | Event Log'. If the application is not running under the debugger the message is sent to the system debugger. If there is no system debugger active the function does nothing.
See also:
Trace
TraceLoc
TraceLocFmt
Donator:
Marcel van Brakel
--------------------------------------------------------------------------------
@@TraceLoc
<GROUP Debugging.Diagnostics>
Summary:
Sends a message to the debugger including location information.
Description:
TraceLoc sends the specified message to the debugger but first prepends it with
the source file location from which TraceLoc is called. For example, when calling
TraceLoc from a method called TForm1.Button1Click located in unit1.pas like
this: TraceLoc('Trace me.') the resulting string sent to the debugger will be:
unit.pas:123 (TForm1.ButtonClick) "Trace me."
assuming the TraceLoc statement is on line 123 in the source. Note that this
function requires a detailed map file!
Parameters:
Msg - The message to send to the debugger.
Notes:
If you are running your application under the control of the debugger you can view these messages using the event log dialog, 'View | Debug Windows | Event Log'. If the application is not running under the debugger the message is sent to the system debugger. If there is no system debugger active the function does nothing.
See also:
Trace
TraceFmt
TraceLocFmt
Donator:
Marcel van Brakel
--------------------------------------------------------------------------------
@@TraceLocFmt
<GROUP Debugging.Diagnostics>
Summary:
Sends a formatted message to the debugger prepending it with location information.
Description:
TraceFmt sends a message, formatted from the supplied format string and
arguments array, to the debugger, but first prepends it with the source file location
information. The function uses the VCL Format() function to format the string and
therefore you can use this function exactly like you would use Format().
See the Delphi help file for more information. See TraceLoc for an
example output.
Parameters:
Fmt - Controls the formatting of the message.
Args - Arguments formatted under control of the Fmt string.
Notes:
If you are running your application under the control of the debugger you can view these messages using the event log dialog, 'View | Debug Windows | Event Log'. If the application is not running under the debugger the message is sent to the system debugger. If there is no system debugger active the function does nothing.
See also:
Trace
TraceFmt
TraceLoc
Donator:
Marcel van Brakel
--------------------------------------------------------------------------------
@@TJclMapAddress
<GROUP Debugging.SourceLocations.MapParsers>
Summary:
Holds location information.
Description:
TJclMapAddress holds location information in notifiers of the map parsers.
Donator:
Petr Vones
@@TJclMapAddress.Segment
Segment number of item.
@@TJclMapAddress.Offset
Offset of item.
--------------------------------------------------------------------------------
@@PJclMapString
<GROUP Debugging.SourceLocations.MapParsers>
Summary:
A map-file string.
Description:
PJclMapString holds a map-file specific string. Use the MapStringToString class
function to convert it to a normal string.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser
<GROUP Debugging.SourceLocations.MapParsers>
Summary:
Abstract Map parser.
Description:
TJclAbstractMapParser is an abstract base class for a MAP-file parser.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.ClassTableItem
Summary:
Handler for a class item.
Description:
ClassTableItem is a handler for a class item (eg. CODE, DATA or BSS class) in
the map file. It get's called by the Parse method when it finds a class table item.
Parameters:
Address - Address of the class item.
Len - Length of the class item.
SectionName - Section name of the class item (eg. ".text").
GroupName - Class name of the class item (eg. "CODE").
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.SegmentItem
Summary:
Handler for a segment item (i.e.. a Delphi unit).
Description:
SegmentItem is a handler for a segment item (i.e.. a Delphi unit) in the map file.
It gets called by the Parse method when it finds a segment item.
Parameters:
Address - Address of the segment item.
Len - Length of the segment item.
GroupName - Class name of the segment item (eg. "CODE").
UnitName - Delphi unit name of the segment item (eg. "System").
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.PublicsByNameItem
Summary:
Handler for a public item in the publics by name section.
Description:
PublicsByNameItem is a handler for a public item (eg. a procedure) in the "Publics
By Name" section of the map file.
It gets called by the Parse method when it finds a public item in the "Publics
By Name" section.
Parameters:
Address - Address of the public item.
Name - Name of the public item.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.PublicsByValueItem
Summary:
Handler for a public item in the publics by value section.
Description:
PublicsByValueItem is a handler for a public item (eg. a procedure) in the "Publics
By Value" section of the map file.
It gets called by the Parse method when it finds a public item in the "Publics
By Value" section.
Parameters:
Address - Address of the public item.
Name - Name of the public item.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.LineNumberUnitItem
Summary:
Handler for a unit declaration in the lines section.
Description:
LineNumberUnitItem is a handler for a unit declaration in the lines section
of the map file. It gets called by the Parse method when it finds a unit
declaration in the lines section.
Parameters:
UnitName - Name of the unit.
UnitFileName - Name of the source file.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.LineNumbersItem
Summary:
Handler for a line declaration in the lines section.
Description:
LineNumbers is a handler for a line declaration in the lines section
of the map file. It gets called by the Parse method when it finds a unit
declaration in the lines section.
Parameters:
LineNumber - Line number for the item.
Address - Starting address for the line number.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.Create
Summary:
Creates an instance of TJclAbstractMapParser.
Description:
The Create method instantiates a map-parser object. Since TJclAbstractMapParser
is an abstract base class, you should not Create an instance of
TJclAbstractMapParser directly, but rather of a descendant.
If the specified file exists, a TJclFileMappingStream will be assigned to
the Stream property, referencing the map file.
Parameters:
MapFileName - Name of the map-file to associate with the parser.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.Destroy
Summary:
Destroys an instance of TJclAbstractMapParser.
Description:
Destroy frees up all internal objects before freeing this instance.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.Parse
Summary:
Parses the map file.
Description:
Parse parses the map file specified referenced by the Stream property. It calls
different methods for items found in the file. Descendants override these methods
to store it in an internal structure.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.MapStringToStr
Summary:
Translates map file specific strings to a normal string.
Description:
MapStringToStr translates map file specific strings to a normal string.
If MapString points to an opening bracket, it returns the text starting
at the next character up to the closing bracket or a Carriage Return, whichever
comes first.
If MapString does not point to an opening bracket, it returns the text from
the current location up to the next space, a carriage return or a closing bracket.
Parameters:
MapString - String to translate.
Result:
If MapString = nil the function returns an empty string, otherwise it returns
translated version of the string.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.Stream
Summary:
A stream referencing the map file.
Description:
Stream holds the a reference to the map file assigned by the Create method.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.LinkerBug
Summary:
Is the linker bug found in the map.
Description:
LinkerBug holds a flag to determine if the linker bug is found in the map file.
The bug appears if a unit has >64K of data after the code and another unit
follows. The solution is to move the data to a separate unit.
See also:
LinkerBugUnit
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclAbstractMapParser.LinkerBugUnitName
Summary:
Unit name of where the linker bug occured.
Description:
LinkerBugUnit holds the name of the unit containing the linker bug. If there's
no linker bug present (ie. LinkerBug = False) LinkerBugUnit is empty.
See also:
LinkerBug
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapParser
<GROUP Debugging.SourceLocations.MapParsers>
Summary:
Generic map file parser.
Description:
TJclMapParser is a class for a generic MAP-file parser. Items are reported to
the user through event calls.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapParser.OnClassTable
Summary:
Event handler for a class item.
Description:
OnClassTable is the event handler for a class item in the map file. It get's called by
the ClassTableItem method when the parser finds a class table item.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapParser.OnSegment
Summary:
Event handler for a segment item (i.e.. a Delphi unit).
Description:
OnSegment is the event handler for a segment item (i.e.. a Delphi unit) in the map file.
It gets called by the SegmentItem method when the parser finds a segment item.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapParser.OnPublicsByName
Summary:
Event handler for a public item in the publics by name section.
Description:
OnPublicsByName is the event handler for a public item (eg. a procedure) in the "Publics
By Name" section of the map file.
It gets called by the PublicsByNameItem method when the parser finds a public item in
the "Publics By Name" section.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapParser.OnPublicsByValue
Summary:
Event handler for a public item in the publics by value section.
Description:
OnPublicsByValue is the event handler for a public item (eg. a procedure) in the "Publics
By Value" section of the map file.
It gets called by the PublicsByValueItem method when the parser finds a public item in
the "Publics By Value" section.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapParser.OnLineNumberUnit
Summary:
Event handler for a unit declaration in the lines section.
Description:
OnLineNumberUnit is the event handler for a unit declaration in the lines section
of the map file. It gets called by the LineNumberUnitItem method when the parser
finds a unit declaration in the lines section.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapParser.OnLineNumbers
Summary:
Event handler for a line declaration in the lines section.
Description:
OnLineNumbers is the event handler for a line declaration in the lines section
of the map file. It gets called by the LineNumbers method when the parser finds
a unit declaration in the lines section.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapScanner
<GROUP Debugging.SourceLocations.MapParsers>
Summary:
Generic map file parser.
Description:
TJclMapScanner is a map file scanner. The class scans the map file and holds the
result for later reference.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapScanner.Scan
Summary:
Scans the map file.
Description:
Scan scans the map file specified by Create and stores the result for later
reference.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapScanner.Create
Summary:
Creates an instance of TJclMapScanner.
Description:
The Create method instantiates a map-file scanner object. After calling the
inherited Create from TJclAbstractMapParser,
the scan method will be called to scan the file.
Parameters:
MapFileName - Name of the map-file to associate with the parser.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapScanner.LineNumberFromAddr
Summary:
Returns the line number for an address.
Description:
LineNumberFromAddr returns the line number for the specified address.
Parameters:
Addr - Address to get line number for.
Result:
The line number for the specified address.
See also:
ModuleNameFromAddr
ModuleStartFromAddr
ProcNameFromAddr
SourceNameFromAddr
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapScanner.ModuleNameFromAddr
Summary:
Returns the Delphi unit name for an address.
Description:
ModuleNameFromAddr returns the Delphi unit name for the specified address.
Parameters:
Addr - Address to get unit name for.
Result:
The Delphi unit name for the specified address.
See also:
LineNumberFromAddr
ModuleStartFromAddr
ProcNameFromAddr
SourceNameFromAddr
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapScanner.ModuleStartFromAddr
Summary:
Returns the starting address of a module given an address.
Description:
ModuleStartFromAddr returns the starting address of the Delphi unit that contains
the specified address.
Parameters:
Addr - Address to get unit start for.
Result:
The starting address of the Delphi unit that contains the specified address.
See also:
LineNumberFromAddr
ModuleNameFromAddr
ProcNameFromAddr
SourceNameFromAddr
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapScanner.ProcNameFromAddr
Summary:
Returns the procedure name for an address.
Description:
ProcNameFromAddr returns the procedure name for the specified address.
Parameters:
Addr - Address to get procedure name for.
Result:
The procedure name for the specified address.
See also:
LineNumberFromAddr
ModuleNameFromAddr
ModuleStartFromAddr
SourceNameFromAddr
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclMapScanner.SourceNameFromAddr
Summary:
Returns the source file name for an address.
Description:
SourceNameFromAddr returns the source-file name for the specified address.
Parameters:
Addr - Address to get procedure name for.
Result:
The source file name for the specified address.
See also:
LineNumberFromAddr
ModuleNameFromAddr
ModuleStartFromAddr
ProcNameFromAddr
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@JclDbgDataSignature
<GROUP Debugging.SourceLocations.BinaryDebugData>
Summary:
Signature of Jcl Binary Debug Data.
Description:
JclDbgDataSignature is the signature of the Jcl Binary Debug Data.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@JclDbgDataResName
<GROUP Debugging.SourceLocations.BinaryDebugData>
Summary:
Resource name for binary debug data.
Description:
JclDbgDataResName is the resource name for Jcl Binary Debug Data.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@JclDbgFileExtension
<GROUP Debugging.SourceLocations.BinaryDebugData>
Summary:
File extension for a Jcl Binary Debug File.
Description:
JclDbgFileExtension is the extension for Jcl Binary Debug Data File.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugGenerator
<GROUP Debugging.SourceLocations.BinaryDebugData>
Summary:
Generates a binary version of a map file.
Description:
TJclBinDebugGenerator translates the text based map file created by the linker into
a smaller, binary version. The result is saved in a memory stream.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugGenerator.CreateData
Summary:
Translates the map file.
Description:
CreateData translates the text based map file into a binary version and stores it
in a memorystream, referenced by the DataStream
property. CreateData gets called by the Create method automatically.
Literal strings are compressed into a 6-bit character, which results in a compression of
3:4. Furthermore, it doesn't store spaces and integers are stored as integer values (always
4 bytes instead of 8-byte hex-string). This results in a considerable savings on
needed space.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugGenerator.Create
Summary:
Creates an instance of TJclBinDebugGenerator.
Description:
The Create method instantiates a binary debug generator object. After calling the
inherited Create from TJclMapScanner,
the CreateData method will be called to convert the text-based map file to a
binary version.
Parameters:
MapFileName - Name of the map-file to associate with the parser.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugGenerator.CalculateCheckSum
Summary:
Calculates the checksum of the binary data.
Description:
CalculateChecksum calculates the checksum of the binary debug data.
Result:
If the checksum could be calculated the function returns True, otherwise it returns
False.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugGenerator.DataStream
Summary:
A memory stream holding the translation result.
Description:
DataStream holds the result of the translation.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugScanner
<GROUP Debugging.SourceLocations.BinaryDebugData>
Summary:
Scans a binary version of a map file.
Description:
TJclBinDebugScanner is like the TJclMapScanner except that it scans a binary map
file. The binary file can be generated from a text-based map file by instantiating
a TJclBinDebugGenerator-object
and saving the DataStream to a file.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugScanner.Create
Summary:
Creates an instance of TJclBinDebugScanner.
Description:
The Create method instantiates a binary debug scanner object. After instantiating
and assigning the stream, the format is checked. You can use the ValidFormat-property
to check if the stream actually contains binary debug data.
Parameters:
AStream - Stream with binary debug data.
CacheData - If set to true, data read from the stream is internally cached.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugScanner.IsModuleNameValid
Summary:
Checks if the given filename is a valid name for the module.
Description:
IsModuleNameValid checks if the given filename is a valid name for the module.
Parameters:
Name - Filename to check.
Result:
If the specified filename belongs to this module the function returns True,
otherwise it returns False.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugScanner.LineNumberFromAddr
Summary:
Returns the line number for an address.
Description:
LineNumberFromAddr returns the line number for the specified address.
Parameters:
Addr - Address to get line number for.
Result:
The line number for the specified address.
See also:
ModuleNameFromAddr
ModuleStartFromAddr
ProcNameFromAddr
SourceNameFromAddr
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugScanner.ModuleNameFromAddr
Summary:
Returns the Delphi unit name for an address.
Description:
ModuleNameFromAddr returns the Delphi unit name for the specified address.
Parameters:
Addr - Address to get unit name for.
Result:
The Delphi unit name for the specified address.
See also:
LineNumberFromAddr
ModuleStartFromAddr
ProcNameFromAddr
SourceNameFromAddr
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugScanner.ModuleStartFromAddr
Summary:
Returns the starting address of a module given an address.
Description:
ModuleStartFromAddr returns the starting address of the Delphi unit that contains
the specified address.
Parameters:
Addr - Address to get unit start for.
Result:
The starting address of the Delphi unit that contains the specified address.
See also:
LineNumberFromAddr
ModuleNameFromAddr
ProcNameFromAddr
SourceNameFromAddr
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugScanner.ProcNameFromAddr
Summary:
Returns the procedure name for an address.
Description:
ProcNameFromAddr returns the procedure name for the specified address.
Parameters:
Addr - Address to get procedure name for.
Result:
The procedure name for the specified address.
See also:
LineNumberFromAddr
ModuleNameFromAddr
ModuleStartFromAddr
SourceNameFromAddr
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugScanner.SourceNameFromAddr
Summary:
Returns the source file name for an address.
Description:
SourceNameFromAddr returns the source-file name for the specified address.
Result:
The source file name for the specified address.
See also:
LineNumberFromAddr
ModuleNameFromAddr
ModuleStartFromAddr
ProcNameFromAddr
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclBinDebugScanner.ValidFormat
Summary:
Flag to check validity of data.
Description:
ValidFormat is true if the data in the specified stream is valid binary debug data.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@ConvertMapFileToJdbgFile
<GROUP Debugging.SourceLocations.BinaryDebugData>
Summary:
Converts a text based MAP file to a Jcl binary debug file.
Description:
ConvertMapFileToJdbgFile convert the specified text based map file to a Jcl binary
debug file.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclLocationInfo
<GROUP Debugging.SourceLocations>
Summary:
Location info structure.
Description:
TJclLocationInfo is the structure returned in various routines and methods that
request location info for a specific address.
Donator:
Petr Vones
@@TJclLocationInfo.Address
Nearest address of the request.
@@TJclLocationInfo.UnitName
Name of the Delphi unit the address is located in.
@@TJclLocationInfo.ProcedureName
Name of the procedure for the address.
@@TJclLocationInfo.LineNumber
Line-number for the address.
@@TJclLocationInfo.SourceName
Name of the source file for the address.
@@TJclLocationInfo.DebugInfo
Other usefull information for the address. See TJclDebugInfoSource for more information.
--------------------------------------------------------------------------------
@@TJclDebugInfoSource
<GROUP Debugging.SourceLocations>
Summary:
Debug info location item.
Description:
TJclDebugInfoSource is an abstract base class to hold location information.
Instances of descendants are created by the TJclDebugInfoList-object.
Descendants should override the InitializeSource
and GetLocationInfo methods.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoSource.InitializeSource
Summary:
Initializes the object.
Description:
InitializeSource initializes the object.
Result:
If the function succeeds it returns True, otherwise it returns False.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoSource.Create
Summary:
Instantiates a DebugInfoSource object.
Description:
Create instantiates a TJclDebugInfoSource object and links it to a specific
module. TJclDebugInfoSource is an abstract base class and you should never
instantiate a TJclDebugSource directly, but rather a descendant.
Parameters:
AModule - Module handle to create debug info for.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoSource.GetLocationInfo
Summary:
Retreives information on a specified address.
Description:
GetLocationInfo retreives information for the address specified by the Addr
parameter and returns it through the Info parameter.
Parameters:
Addr - Address to get information on
Info - Structure that holds information on the address, if address belongs to this object
Result:
If the specified address exists within the module represented by this object the
function returns True and Info will hold the information for the specified address.
If the address does not exist within the module, the function returns False.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoSource.Module
Summary:
Module referenced by this object.
Description:
Module holds the module handle this instance has been created for.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoSource.FileName
Summary:
File name for the module referenced by this object.
Description:
FileName holds the file name of the module this instance has been created for.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoList
<GROUP Debugging.SourceLocations>
Summary:
Holds a list of debug info items
Description:
TJclDebugInfoList holds a list of TJclDebugInfoSource
items requested. Items are created when needed, not when the list is created.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoList.CreateDebugInfo
Summary:
Creates a TJclDebugInfoSource descendant for a module.
Description:
CreateDebugInfo will atempt to create a TJclDebugInfoSource
for the given module and initializes it. The method tries to obtain the following types in order:
* Text-based map file
* Jcl Binary debug data resource
* Module export table
If initialization failed for all supported types nil will be returned, otherwise
it will return the first that initialized correctly.
Parameters:
Module - Module handle to create debug info for.
Result:
If debug info could be obtained for the specified module, a TJclDebugInfoSource
descendant will be returned, otherwise it returns nil.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoList.GetLocationInfo
Summary:
Retreives information on a specified address.
Description:
GetLocationInfo retreives information for the address specified by the Addr
parameter and returns it through the Info parameter.
Parameters:
Addr - Address to get information on.
Info - Structure that holds information on the address, if address belongs to any module in the current process.
Result:
If the specified address exists within the curent process the function returns True
and Info will hold the information for the specified address. If the address does
not exist within the current process, the function returns False.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@DebugInfoAvailable
<GROUP Debugging.SourceLocations>
Summary:
Determines if debug info for a module is available.
Description:
DebugInfoAvailable checks if the specified module has debug information.
Parameters:
Module - Handle of module to check for debug information.
Result:
If the specified module has debug information the function returns True, otherwise
False will be returned.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoList.ItemFromModule
Summary:
Gets a DebugInfo item for the specified module.
Description:
ItemFromModule returns a TJclDebugInfoSource-item for the specified module. If the item
hasn't been created, it will try to do so.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoList.Items
Summary:
Returns the debug info item at the specified index.
Description:
Items returns the TJclDebugInfoSource-item at the specified index.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoMap
<GROUP Debugging.SourceLocations>
Summary:
Debug info location item for text-base map files.
Description:
TJclDebugInfoMap is the class to hold location information by scanning
a text-based map file. It uses a TJclMapScanner object to do so.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoBinary
<GROUP Debugging.SourceLocations>
Summary:
Debug info location item for Jcl binary debug data.
Description:
TJclDebugInfoBinary is the class to hold location information by scanning
a Jcl binary debug data resource. It uses a TJclBinDebugScanner object to do so.
Donator:
Petr Vones
--------------------------------------------------------------------------------
@@TJclDebugInfoExports
<GROUP Debugging.SourceLocations>
Summary:
Debug info location item for module export table.
Description:
TJclDebugInfoExports is the class to hold location information by scanning
a export table for the PE-image. It uses a TJclPeBorImage object to do so.
Donator:
Petr Vones
--------------------------------------------------------------------------------