-
Notifications
You must be signed in to change notification settings - Fork 12
/
Copy pathstabs.html
5513 lines (5192 loc) · 280 KB
/
stabs.html
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
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- Copyright (C) 1992-2024 Free Software Foundation, Inc.
Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon,
and David MacKenzie.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU
Free Documentation License". -->
<title>STABS</title>
<meta name="description" content="STABS">
<meta name="keywords" content="STABS">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="#Top" rel="start" title="Top">
<link href="#Symbol-Types-Index" rel="index" title="Symbol Types Index">
<link href="#SEC_Contents" rel="contents" title="Table of Contents">
<link href="#Overview" rel="next" title="Overview">
<style type="text/css">
<!--
a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
span:hover a.copiable-anchor {visibility: visible}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<h1 class="settitle" align="center">STABS</h1>
<p>This document describes the stabs debugging symbol tables.
</p>
<p>Copyright © 1992–2024 Free Software Foundation, Inc.
Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon,
and David MacKenzie.
</p>
<p>Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled “GNU
Free Documentation License”.
</p>
<div class="top" id="Top">
<div class="header">
<p>
Next: <a href="#Overview" accesskey="n" rel="next">Overview of Stabs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="The-_0022stabs_0022-representation-of-debugging-information"></span><h1 class="top">The "stabs" representation of debugging information</h1>
<p>This document describes the stabs debugging format.
</p>
<div class="Contents_element" id="SEC_Contents">
<h2 class="contents-heading">Table of Contents</h2>
<div class="contents">
<ul class="no-bullet">
<li><a id="toc-Overview-of-Stabs" href="#Overview">1 Overview of Stabs</a>
<ul class="no-bullet">
<li><a id="toc-Overview-of-Debugging-Information-Flow" href="#Flow">1.1 Overview of Debugging Information Flow</a></li>
<li><a id="toc-Overview-of-Stab-Format" href="#Stabs-Format">1.2 Overview of Stab Format</a></li>
<li><a id="toc-The-String-Field" href="#String-Field">1.3 The String Field</a></li>
<li><a id="toc-A-Simple-Example-in-C-Source" href="#C-Example">1.4 A Simple Example in C Source</a></li>
<li><a id="toc-The-Simple-Example-at-the-Assembly-Level" href="#Assembly-Code">1.5 The Simple Example at the Assembly Level</a></li>
</ul></li>
<li><a id="toc-Encoding-the-Structure-of-the-Program" href="#Program-Structure">2 Encoding the Structure of the Program</a>
<ul class="no-bullet">
<li><a id="toc-Main-Program-1" href="#Main-Program">2.1 Main Program</a></li>
<li><a id="toc-Paths-and-Names-of-the-Source-Files" href="#Source-Files">2.2 Paths and Names of the Source Files</a></li>
<li><a id="toc-Names-of-Include-Files" href="#Include-Files">2.3 Names of Include Files</a></li>
<li><a id="toc-Line-Numbers-1" href="#Line-Numbers">2.4 Line Numbers</a></li>
<li><a id="toc-Procedures-1" href="#Procedures">2.5 Procedures</a></li>
<li><a id="toc-Nested-Procedures-1" href="#Nested-Procedures">2.6 Nested Procedures</a></li>
<li><a id="toc-Block-Structure-1" href="#Block-Structure">2.7 Block Structure</a></li>
<li><a id="toc-Alternate-Entry-Points-1" href="#Alternate-Entry-Points">2.8 Alternate Entry Points</a></li>
</ul></li>
<li><a id="toc-Constants-1" href="#Constants">3 Constants</a></li>
<li><a id="toc-Variables-1" href="#Variables">4 Variables</a>
<ul class="no-bullet">
<li><a id="toc-Automatic-Variables-Allocated-on-the-Stack" href="#Stack-Variables">4.1 Automatic Variables Allocated on the Stack</a></li>
<li><a id="toc-Global-Variables-1" href="#Global-Variables">4.2 Global Variables</a></li>
<li><a id="toc-Register-Variables-1" href="#Register-Variables">4.3 Register Variables</a></li>
<li><a id="toc-Common-Blocks-1" href="#Common-Blocks">4.4 Common Blocks</a></li>
<li><a id="toc-Static-Variables" href="#Statics">4.5 Static Variables</a></li>
<li><a id="toc-Fortran-Based-Variables" href="#Based-Variables">4.6 Fortran Based Variables</a></li>
<li><a id="toc-Parameters-1" href="#Parameters">4.7 Parameters</a>
<ul class="no-bullet">
<li><a id="toc-Passing-Parameters-in-Registers" href="#Register-Parameters">4.7.1 Passing Parameters in Registers</a></li>
<li><a id="toc-Storing-Parameters-as-Local-Variables" href="#Local-Variable-Parameters">4.7.2 Storing Parameters as Local Variables</a></li>
<li><a id="toc-Passing-Parameters-by-Reference" href="#Reference-Parameters">4.7.3 Passing Parameters by Reference</a></li>
<li><a id="toc-Passing-Conformant-Array-Parameters" href="#Conformant-Arrays">4.7.4 Passing Conformant Array Parameters</a></li>
</ul></li>
</ul></li>
<li><a id="toc-Defining-Types" href="#Types">5 Defining Types</a>
<ul class="no-bullet">
<li><a id="toc-Builtin-Types-1" href="#Builtin-Types">5.1 Builtin Types</a>
<ul class="no-bullet">
<li><a id="toc-Traditional-Builtin-Types-1" href="#Traditional-Builtin-Types">5.1.1 Traditional Builtin Types</a>
<ul class="no-bullet">
<li><a id="toc-Traditional-Integer-Types-1" href="#Traditional-Integer-Types">5.1.1.1 Traditional Integer Types</a></li>
<li><a id="toc-Traditional-Other-Types-1" href="#Traditional-Other-Types">5.1.1.2 Traditional Other Types</a></li>
</ul></li>
<li><a id="toc-Defining-Builtin-Types-Using-Builtin-Type-Descriptors" href="#Builtin-Type-Descriptors">5.1.2 Defining Builtin Types Using Builtin Type Descriptors</a></li>
<li><a id="toc-Negative-Type-Numbers-1" href="#Negative-Type-Numbers">5.1.3 Negative Type Numbers</a></li>
</ul></li>
<li><a id="toc-Miscellaneous-Types-1" href="#Miscellaneous-Types">5.2 Miscellaneous Types</a></li>
<li><a id="toc-Cross_002dReferences-to-Other-Types" href="#Cross_002dReferences">5.3 Cross-References to Other Types</a></li>
<li><a id="toc-Subrange-Types" href="#Subranges">5.4 Subrange Types</a></li>
<li><a id="toc-Array-Types" href="#Arrays">5.5 Array Types</a></li>
<li><a id="toc-Strings-1" href="#Strings">5.6 Strings</a></li>
<li><a id="toc-Enumerations-1" href="#Enumerations">5.7 Enumerations</a></li>
<li><a id="toc-Structures-1" href="#Structures">5.8 Structures</a></li>
<li><a id="toc-Giving-a-Type-a-Name" href="#Typedefs">5.9 Giving a Type a Name</a></li>
<li><a id="toc-Unions-1" href="#Unions">5.10 Unions</a></li>
<li><a id="toc-Function-Types-1" href="#Function-Types">5.11 Function Types</a></li>
</ul></li>
<li><a id="toc-Representation-of-_0023define-and-_0023undef" href="#Macro-define-and-undefine">6 Representation of #define and #undef</a></li>
<li><a id="toc-Symbol-Information-in-Symbol-Tables" href="#Symbol-Tables">7 Symbol Information in Symbol Tables</a>
<ul class="no-bullet">
<li><a id="toc-Symbol-Table-Format-1" href="#Symbol-Table-Format">7.1 Symbol Table Format</a></li>
<li><a id="toc-Transformations-on-Symbol-Tables" href="#Transformations-On-Symbol-Tables">7.2 Transformations on Symbol Tables</a>
<ul class="no-bullet">
<li><a id="toc-Transformations-on-Static-Variables" href="#Transformations-On-Static-Variables">7.2.1 Transformations on Static Variables</a></li>
<li><a id="toc-Transformations-on-Global-Variables" href="#Transformations-On-Global-Variables">7.2.2 Transformations on Global Variables</a></li>
<li><a id="toc-Transformations-of-Stabs-in-separate-sections" href="#Stab-Section-Transformations">7.2.3 Transformations of Stabs in separate sections</a></li>
</ul></li>
</ul></li>
<li><a id="toc-GNU-C_002b_002b-Stabs" href="#Cplusplus">8 GNU C<tt>++</tt> Stabs</a>
<ul class="no-bullet">
<li><a id="toc-C_002b_002b-Class-Names" href="#Class-Names">8.1 C<tt>++</tt> Class Names</a></li>
<li><a id="toc-Defining-a-Symbol-Within-Another-Type" href="#Nested-Symbols">8.2 Defining a Symbol Within Another Type</a></li>
<li><a id="toc-Basic-Types-For-C_002b_002b" href="#Basic-Cplusplus-Types">8.3 Basic Types For C<tt>++</tt></a></li>
<li><a id="toc-Simple-Class-Definition" href="#Simple-Classes">8.4 Simple Class Definition</a></li>
<li><a id="toc-Class-Instance-1" href="#Class-Instance">8.5 Class Instance</a></li>
<li><a id="toc-Method-Definition" href="#Methods">8.6 Method Definition</a></li>
<li><a id="toc-The-_0023-Type-Descriptor" href="#Method-Type-Descriptor">8.7 The ‘<samp>#</samp>’ Type Descriptor</a></li>
<li><a id="toc-The-_0040-Type-Descriptor" href="#Member-Type-Descriptor">8.8 The ‘<samp>@</samp>’ Type Descriptor</a></li>
<li><a id="toc-Protections-1" href="#Protections">8.9 Protections</a></li>
<li><a id="toc-Method-Modifiers-_0028const_002c-volatile_002c-const-volatile_0029" href="#Method-Modifiers">8.10 Method Modifiers (<code>const</code>, <code>volatile</code>, <code>const volatile</code>)</a></li>
<li><a id="toc-Virtual-Methods-1" href="#Virtual-Methods">8.11 Virtual Methods</a></li>
<li><a id="toc-Inheritance-1" href="#Inheritance">8.12 Inheritance</a></li>
<li><a id="toc-Virtual-Base-Classes-1" href="#Virtual-Base-Classes">8.13 Virtual Base Classes</a></li>
<li><a id="toc-Static-Members-1" href="#Static-Members">8.14 Static Members</a></li>
</ul></li>
<li><a id="toc-Table-of-Stab-Types" href="#Stab-Types">Appendix A Table of Stab Types</a>
<ul class="no-bullet">
<li><a id="toc-Non_002dStab-Symbol-Types-1" href="#Non_002dStab-Symbol-Types">A.1 Non-Stab Symbol Types</a></li>
<li><a id="toc-Stab-Symbol-Types-1" href="#Stab-Symbol-Types">A.2 Stab Symbol Types</a></li>
</ul></li>
<li><a id="toc-Table-of-Symbol-Descriptors" href="#Symbol-Descriptors">Appendix B Table of Symbol Descriptors</a></li>
<li><a id="toc-Table-of-Type-Descriptors" href="#Type-Descriptors">Appendix C Table of Type Descriptors</a></li>
<li><a id="toc-Expanded-Reference-by-Stab-Type" href="#Expanded-Reference">Appendix D Expanded Reference by Stab Type</a>
<ul class="no-bullet">
<li><a id="toc-N_005fPC-1" href="#N_005fPC">D.1 N_PC</a></li>
<li><a id="toc-N_005fNSYMS-1" href="#N_005fNSYMS">D.2 N_NSYMS</a></li>
<li><a id="toc-N_005fNOMAP-1" href="#N_005fNOMAP">D.3 N_NOMAP</a></li>
<li><a id="toc-N_005fM2C-1" href="#N_005fM2C">D.4 N_M2C</a></li>
<li><a id="toc-N_005fBROWS-1" href="#N_005fBROWS">D.5 N_BROWS</a></li>
<li><a id="toc-N_005fDEFD-1" href="#N_005fDEFD">D.6 N_DEFD</a></li>
<li><a id="toc-N_005fEHDECL-1" href="#N_005fEHDECL">D.7 N_EHDECL</a></li>
<li><a id="toc-N_005fMOD2-1" href="#N_005fMOD2">D.8 N_MOD2</a></li>
<li><a id="toc-N_005fCATCH-1" href="#N_005fCATCH">D.9 N_CATCH</a></li>
<li><a id="toc-N_005fSSYM-1" href="#N_005fSSYM">D.10 N_SSYM</a></li>
<li><a id="toc-N_005fSCOPE-1" href="#N_005fSCOPE">D.11 N_SCOPE</a></li>
<li><a id="toc-Non_002dbase-registers-on-Gould-systems" href="#Gould">D.12 Non-base registers on Gould systems</a></li>
<li><a id="toc-N_005fLENG-1" href="#N_005fLENG">D.13 N_LENG</a></li>
</ul></li>
<li><a id="toc-Questions-and-Anomalies" href="#Questions">Appendix E Questions and Anomalies</a></li>
<li><a id="toc-Using-Stabs-in-Their-Own-Sections" href="#Stab-Sections">Appendix F Using Stabs in Their Own Sections</a>
<ul class="no-bullet">
<li><a id="toc-How-to-Embed-Stabs-in-Sections" href="#Stab-Section-Basics">F.1 How to Embed Stabs in Sections</a></li>
<li><a id="toc-Having-the-Linker-Relocate-Stabs-in-ELF" href="#ELF-Linker-Relocation">F.2 Having the Linker Relocate Stabs in ELF</a></li>
</ul></li>
<li><a id="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">Appendix G GNU Free Documentation License</a></li>
<li><a id="toc-Symbol-Types-Index-1" href="#Symbol-Types-Index" rel="index">Symbol Types Index</a></li>
</ul>
</div>
</div>
<hr>
<div class="chapter" id="Overview">
<div class="header">
<p>
Next: <a href="#Program-Structure" accesskey="n" rel="next">Encoding the Structure of the Program</a>, Previous: <a href="#Top" accesskey="p" rel="prev">The "stabs" representation of debugging information</a>, Up: <a href="#Top" accesskey="u" rel="up">The "stabs" representation of debugging information</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Overview-of-Stabs"></span><h2 class="chapter">1 Overview of Stabs</h2>
<p><em>Stabs</em> refers to a format for information that describes a program
to a debugger. This format was apparently invented by
Peter Kessler at
the University of California at Berkeley, for the <code>pdx</code> Pascal
debugger; the format has spread widely since then.
</p>
<p>This document is one of the few published sources of documentation on
stabs. It is believed to be comprehensive for stabs used by C. The
lists of symbol descriptors (see <a href="#Symbol-Descriptors">Table of Symbol Descriptors</a>) and type
descriptors (see <a href="#Type-Descriptors">Table of Type Descriptors</a>) are believed to be completely
comprehensive. Stabs for COBOL-specific features and for variant
records (used by Pascal and Modula-2) are poorly documented here.
</p>
<p>Other sources of information on stabs are <cite>Dbx and Dbxtool
Interfaces</cite>, 2nd edition, by Sun, 1988, and <cite>AIX Version 3.2 Files
Reference</cite>, Fourth Edition, September 1992, "dbx Stabstring Grammar" in
the a.out section, page 2-31. This document is believed to incorporate
the information from those two sources except where it explicitly directs
you to them for more information.
</p>
<ul class="section-toc">
<li><a href="#Flow" accesskey="1">Overview of Debugging Information Flow</a></li>
<li><a href="#Stabs-Format" accesskey="2">Overview of Stab Format</a></li>
<li><a href="#String-Field" accesskey="3">The String Field</a></li>
<li><a href="#C-Example" accesskey="4">A Simple Example in C Source</a></li>
<li><a href="#Assembly-Code" accesskey="5">The Simple Example at the Assembly Level</a></li>
</ul>
<hr>
<div class="section" id="Flow">
<div class="header">
<p>
Next: <a href="#Stabs-Format" accesskey="n" rel="next">Overview of Stab Format</a>, Up: <a href="#Overview" accesskey="u" rel="up">Overview of Stabs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Overview-of-Debugging-Information-Flow"></span><h3 class="section">1.1 Overview of Debugging Information Flow</h3>
<p>The GNU C compiler compiles C source in a <samp>.c</samp> file into assembly
language in a <samp>.s</samp> file, which the assembler translates into
a <samp>.o</samp> file, which the linker combines with other <samp>.o</samp> files and
libraries to produce an executable file.
</p>
<p>With the ‘<samp>-g</samp>’ option, GCC puts in the <samp>.s</samp> file additional
debugging information, which is slightly transformed by the assembler
and linker, and carried through into the final executable. This
debugging information describes features of the source file like line
numbers, the types and scopes of variables, and function names,
parameters, and scopes.
</p>
<p>For some object file formats, the debugging information is encapsulated
in assembler directives known collectively as <em>stab</em> (symbol table)
directives, which are interspersed with the generated code. Stabs are
the native format for debugging information in the a.out and XCOFF
object file formats. The GNU tools can also emit stabs in the COFF and
ECOFF object file formats.
</p>
<p>The assembler adds the information from stabs to the symbol information
it places by default in the symbol table and the string table of the
<samp>.o</samp> file it is building. The linker consolidates the <samp>.o</samp>
files into one executable file, with one symbol table and one string
table. Debuggers use the symbol and string tables in the executable as
a source of debugging information about the program.
</p>
<hr>
</div>
<div class="section" id="Stabs-Format">
<div class="header">
<p>
Next: <a href="#String-Field" accesskey="n" rel="next">The String Field</a>, Previous: <a href="#Flow" accesskey="p" rel="prev">Overview of Debugging Information Flow</a>, Up: <a href="#Overview" accesskey="u" rel="up">Overview of Stabs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Overview-of-Stab-Format"></span><h3 class="section">1.2 Overview of Stab Format</h3>
<p>There are three overall formats for stab assembler directives,
differentiated by the first word of the stab. The name of the directive
describes which combination of four possible data fields follows. It is
either <code>.stabs</code> (string), <code>.stabn</code> (number), or <code>.stabd</code>
(dot). IBM’s XCOFF assembler uses <code>.stabx</code> (and some other
directives such as <code>.file</code> and <code>.bi</code>) instead of
<code>.stabs</code>, <code>.stabn</code> or <code>.stabd</code>.
</p>
<p>The overall format of each class of stab is:
</p>
<div class="example">
<pre class="example">.stabs "<var>string</var>",<var>type</var>,<var>other</var>,<var>desc</var>,<var>value</var>
.stabn <var>type</var>,<var>other</var>,<var>desc</var>,<var>value</var>
.stabd <var>type</var>,<var>other</var>,<var>desc</var>
.stabx "<var>string</var>",<var>value</var>,<var>type</var>,<var>sdb-type</var>
</pre></div>
<p>For <code>.stabn</code> and <code>.stabd</code>, there is no <var>string</var> (the
<code>n_strx</code> field is zero; see <a href="#Symbol-Tables">Symbol Information in Symbol Tables</a>). For
<code>.stabd</code>, the <var>value</var> field is implicit and has the value of
the current file location. For <code>.stabx</code>, the <var>sdb-type</var> field
is unused for stabs and can always be set to zero. The <var>other</var>
field is almost always unused and can be set to zero.
</p>
<p>The number in the <var>type</var> field gives some basic information about
which type of stab this is (or whether it <em>is</em> a stab, as opposed
to an ordinary symbol). Each valid type number defines a different stab
type; further, the stab type defines the exact interpretation of, and
possible values for, any remaining <var>string</var>, <var>desc</var>, or
<var>value</var> fields present in the stab. See <a href="#Stab-Types">Table of Stab Types</a>, for a list
in numeric order of the valid <var>type</var> field values for stab directives.
</p>
<hr>
</div>
<div class="section" id="String-Field">
<div class="header">
<p>
Next: <a href="#C-Example" accesskey="n" rel="next">A Simple Example in C Source</a>, Previous: <a href="#Stabs-Format" accesskey="p" rel="prev">Overview of Stab Format</a>, Up: <a href="#Overview" accesskey="u" rel="up">Overview of Stabs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="The-String-Field"></span><h3 class="section">1.3 The String Field</h3>
<p>For most stabs the string field holds the meat of the
debugging information. The flexible nature of this field
is what makes stabs extensible. For some stab types the string field
contains only a name. For other stab types the contents can be a great
deal more complex.
</p>
<p>The overall format of the string field for most stab types is:
</p>
<div class="example">
<pre class="example">"<var>name</var>:<var>symbol-descriptor</var> <var>type-information</var>"
</pre></div>
<p><var>name</var> is the name of the symbol represented by the stab; it can
contain a pair of colons (see <a href="#Nested-Symbols">Defining a Symbol Within Another Type</a>). <var>name</var> can be
omitted, which means the stab represents an unnamed object. For
example, ‘<samp>:t10=*2</samp>’ defines type 10 as a pointer to type 2, but does
not give the type a name. Omitting the <var>name</var> field is supported by
AIX dbx and GDB after about version 4.8, but not other debuggers. GCC
sometimes uses a single space as the name instead of omitting the name
altogether; apparently that is supported by most debuggers.
</p>
<p>The <var>symbol-descriptor</var> following the ‘<samp>:</samp>’ is an alphabetic
character that tells more specifically what kind of symbol the stab
represents. If the <var>symbol-descriptor</var> is omitted, but type
information follows, then the stab represents a local variable. For a
list of symbol descriptors, see <a href="#Symbol-Descriptors">Table of Symbol Descriptors</a>. The ‘<samp>c</samp>’
symbol descriptor is an exception in that it is not followed by type
information. See <a href="#Constants">Constants</a>.
</p>
<p><var>type-information</var> is either a <var>type-number</var>, or
‘<samp><var>type-number</var>=</samp>’. A <var>type-number</var> alone is a type
reference, referring directly to a type that has already been defined.
</p>
<p>The ‘<samp><var>type-number</var>=</samp>’ form is a type definition, where the
number represents a new type which is about to be defined. The type
definition may refer to other types by number, and those type numbers
may be followed by ‘<samp>=</samp>’ and nested definitions. Also, the Lucid
compiler will repeat ‘<samp><var>type-number</var>=</samp>’ more than once if it
wants to define several type numbers at once.
</p>
<p>In a type definition, if the character that follows the equals sign is
non-numeric then it is a <var>type-descriptor</var>, and tells what kind of
type is about to be defined. Any other values following the
<var>type-descriptor</var> vary, depending on the <var>type-descriptor</var>.
See <a href="#Type-Descriptors">Table of Type Descriptors</a>, for a list of <var>type-descriptor</var> values. If
a number follows the ‘<samp>=</samp>’ then the number is a <var>type-reference</var>.
For a full description of types, <a href="#Types">Defining Types</a>.
</p>
<p>A <var>type-number</var> is often a single number. The GNU and Sun tools
additionally permit a <var>type-number</var> to be a pair
(<var>file-number</var>,<var>filetype-number</var>) (the parentheses appear in the
string, and serve to distinguish the two cases). The <var>file-number</var>
is 0 for the base source file, 1 for the first included file, 2 for the
next, and so on. The <var>filetype-number</var> is a number starting with
1 which is incremented for each new type defined in the file.
(Separating the file number and the type number permits the
<code>N_BINCL</code> optimization to succeed more often; see <a href="#Include-Files">Names of Include Files</a>).
</p>
<p>There is an AIX extension for type attributes. Following the ‘<samp>=</samp>’
are any number of type attributes. Each one starts with ‘<samp>@</samp>’ and
ends with ‘<samp>;</samp>’. Debuggers, including AIX’s dbx and GDB 4.10, skip
any type attributes they do not recognize. GDB 4.9 and other versions
of dbx may not do this. Because of a conflict with C<tt>++</tt>
(see <a href="#Cplusplus">GNU C<tt>++</tt> Stabs</a>), new attributes should not be defined which begin
with a digit, ‘<samp>(</samp>’, or ‘<samp>-</samp>’; GDB may be unable to distinguish
those from the C<tt>++</tt> type descriptor ‘<samp>@</samp>’. The attributes are:
</p>
<dl compact="compact">
<dt><span><code>a<var>boundary</var></code></span></dt>
<dd><p><var>boundary</var> is an integer specifying the alignment. I assume it
applies to all variables of this type.
</p>
</dd>
<dt><span><code>p<var>integer</var></code></span></dt>
<dd><p>Pointer class (for checking). Not sure what this means, or how
<var>integer</var> is interpreted.
</p>
</dd>
<dt><span><code>P</code></span></dt>
<dd><p>Indicate this is a packed type, meaning that structure fields or array
elements are placed more closely in memory, to save memory at the
expense of speed.
</p>
</dd>
<dt><span><code>s<var>size</var></code></span></dt>
<dd><p>Size in bits of a variable of this type. This is fully supported by GDB
4.11 and later.
</p>
</dd>
<dt><span><code>S</code></span></dt>
<dd><p>Indicate that this type is a string instead of an array of characters,
or a bitstring instead of a set. It doesn’t change the layout of the
data being represented, but does enable the debugger to know which type
it is.
</p>
</dd>
<dt><span><code>V</code></span></dt>
<dd><p>Indicate that this type is a vector instead of an array. The only
major difference between vectors and arrays is that vectors are
passed by value instead of by reference (vector coprocessor extension).
</p>
</dd>
</dl>
<p>All of this can make the string field quite long. All versions of GDB,
and some versions of dbx, can handle arbitrarily long strings. But many
versions of dbx (or assemblers or linkers, I’m not sure which)
cretinously limit the strings to about 80 characters, so compilers which
must work with such systems need to split the <code>.stabs</code> directive
into several <code>.stabs</code> directives. Each stab duplicates every field
except the string field. The string field of every stab except the last
is marked as continued with a backslash at the end (in the assembly code
this may be written as a double backslash, depending on the assembler).
Removing the backslashes and concatenating the string fields of each
stab produces the original, long string. Just to be incompatible (or so
they don’t have to worry about what the assembler does with
backslashes), AIX can use ‘<samp>?</samp>’ instead of backslash.
</p>
<hr>
</div>
<div class="section" id="C-Example">
<div class="header">
<p>
Next: <a href="#Assembly-Code" accesskey="n" rel="next">The Simple Example at the Assembly Level</a>, Previous: <a href="#String-Field" accesskey="p" rel="prev">The String Field</a>, Up: <a href="#Overview" accesskey="u" rel="up">Overview of Stabs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="A-Simple-Example-in-C-Source"></span><h3 class="section">1.4 A Simple Example in C Source</h3>
<p>To get the flavor of how stabs describe source information for a C
program, let’s look at the simple program:
</p>
<div class="example">
<pre class="example">main()
{
printf("Hello world");
}
</pre></div>
<p>When compiled with ‘<samp>-g</samp>’, the program above yields the following
<samp>.s</samp> file. Line numbers have been added to make it easier to refer
to parts of the <samp>.s</samp> file in the description of the stabs that
follows.
</p>
<hr>
</div>
<div class="section" id="Assembly-Code">
<div class="header">
<p>
Previous: <a href="#C-Example" accesskey="p" rel="prev">A Simple Example in C Source</a>, Up: <a href="#Overview" accesskey="u" rel="up">Overview of Stabs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="The-Simple-Example-at-the-Assembly-Level"></span><h3 class="section">1.5 The Simple Example at the Assembly Level</h3>
<p>This simple “hello world” example demonstrates several of the stab
types used to describe C language source files.
</p>
<div class="example">
<pre class="example">1 gcc2_compiled.:
2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
3 .stabs "hello.c",100,0,0,Ltext0
4 .text
5 Ltext0:
6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
7 .stabs "char:t2=r2;0;127;",128,0,0,0
8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
17 .stabs "float:t12=r1;4;0;",128,0,0,0
18 .stabs "double:t13=r1;8;0;",128,0,0,0
19 .stabs "long double:t14=r1;8;0;",128,0,0,0
20 .stabs "void:t15=15",128,0,0,0
21 .align 4
22 LC0:
23 .ascii "Hello, world!\12\0"
24 .align 4
25 .global _main
26 .proc 1
27 _main:
28 .stabn 68,0,4,LM1
29 LM1:
30 !#PROLOGUE# 0
31 save %sp,-136,%sp
32 !#PROLOGUE# 1
33 call ___main,0
34 nop
35 .stabn 68,0,5,LM2
36 LM2:
37 LBB2:
38 sethi %hi(LC0),%o1
39 or %o1,%lo(LC0),%o0
40 call _printf,0
41 nop
42 .stabn 68,0,6,LM3
43 LM3:
44 LBE2:
45 .stabn 68,0,6,LM4
46 LM4:
47 L1:
48 ret
49 restore
50 .stabs "main:F1",36,0,0,_main
51 .stabn 192,0,0,LBB2
52 .stabn 224,0,0,LBE2
</pre></div>
<hr>
</div>
</div>
<div class="chapter" id="Program-Structure">
<div class="header">
<p>
Next: <a href="#Constants" accesskey="n" rel="next">Constants</a>, Previous: <a href="#Overview" accesskey="p" rel="prev">Overview of Stabs</a>, Up: <a href="#Top" accesskey="u" rel="up">The "stabs" representation of debugging information</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Encoding-the-Structure-of-the-Program"></span><h2 class="chapter">2 Encoding the Structure of the Program</h2>
<p>The elements of the program structure that stabs encode include the name
of the main function, the names of the source and include files, the
line numbers, procedure names and types, and the beginnings and ends of
blocks of code.
</p>
<ul class="section-toc">
<li><a href="#Main-Program" accesskey="1">Main Program</a></li>
<li><a href="#Source-Files" accesskey="2">Paths and Names of the Source Files</a></li>
<li><a href="#Include-Files" accesskey="3">Names of Include Files</a></li>
<li><a href="#Line-Numbers" accesskey="4">Line Numbers</a></li>
<li><a href="#Procedures" accesskey="5">Procedures</a></li>
<li><a href="#Nested-Procedures" accesskey="6">Nested Procedures</a></li>
<li><a href="#Block-Structure" accesskey="7">Block Structure</a></li>
<li><a href="#Alternate-Entry-Points" accesskey="8">Alternate Entry Points</a></li>
</ul>
<hr>
<div class="section" id="Main-Program">
<div class="header">
<p>
Next: <a href="#Source-Files" accesskey="n" rel="next">Paths and Names of the Source Files</a>, Up: <a href="#Program-Structure" accesskey="u" rel="up">Encoding the Structure of the Program</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Main-Program-1"></span><h3 class="section">2.1 Main Program</h3>
<span id="index-N_005fMAIN"></span>
<p>Most languages allow the main program to have any name. The
<code>N_MAIN</code> stab type tells the debugger the name that is used in this
program. Only the string field is significant; it is the name of
a function which is the main program. Most C compilers do not use this
stab (they expect the debugger to assume that the name is <code>main</code>),
but some C compilers emit an <code>N_MAIN</code> stab for the <code>main</code>
function. I’m not sure how XCOFF handles this.
</p>
<hr>
</div>
<div class="section" id="Source-Files">
<div class="header">
<p>
Next: <a href="#Include-Files" accesskey="n" rel="next">Names of Include Files</a>, Previous: <a href="#Main-Program" accesskey="p" rel="prev">Main Program</a>, Up: <a href="#Program-Structure" accesskey="u" rel="up">Encoding the Structure of the Program</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Paths-and-Names-of-the-Source-Files"></span><h3 class="section">2.2 Paths and Names of the Source Files</h3>
<span id="index-N_005fSO"></span>
<p>Before any other stabs occur, there must be a stab specifying the source
file. This information is contained in a symbol of stab type
<code>N_SO</code>; the string field contains the name of the file. The
value of the symbol is the start address of the portion of the
text section corresponding to that file.
</p>
<p>Some compilers use the desc field to indicate the language of the
source file. Sun’s compilers started this usage, and the first
constants are derived from their documentation. Languages added
by gcc/gdb start at 0x32 to avoid conflict with languages Sun may
add in the future. A desc field with a value 0 indicates that no
language has been specified via this mechanism.
</p>
<dl compact="compact">
<dt><span><code>N_SO_AS</code> (0x1)</span></dt>
<dd><p>Assembly language
</p></dd>
<dt><span><code>N_SO_C</code> (0x2)</span></dt>
<dd><p>K&R traditional C
</p></dd>
<dt><span><code>N_SO_ANSI_C</code> (0x3)</span></dt>
<dd><p>ANSI C
</p></dd>
<dt><span><code>N_SO_CC</code> (0x4)</span></dt>
<dd><p>C++
</p></dd>
<dt><span><code>N_SO_FORTRAN</code> (0x5)</span></dt>
<dd><p>Fortran
</p></dd>
<dt><span><code>N_SO_PASCAL</code> (0x6)</span></dt>
<dd><p>Pascal
</p></dd>
<dt><span><code>N_SO_FORTRAN90</code> (0x7)</span></dt>
<dd><p>Fortran90
</p></dd>
<dt><span><code>N_SO_OBJC</code> (0x32)</span></dt>
<dd><p>Objective-C
</p></dd>
<dt><span><code>N_SO_OBJCPLUS</code> (0x33)</span></dt>
<dd><p>Objective-C++
</p></dd>
</dl>
<p>Some compilers (for example, GCC2 and SunOS4 <samp>/bin/cc</samp>) also
include the directory in which the source was compiled, in a second
<code>N_SO</code> symbol preceding the one containing the file name. This
symbol can be distinguished by the fact that it ends in a slash. Code
from the <code>cfront</code> C<tt>++</tt> compiler can have additional <code>N_SO</code> symbols for
nonexistent source files after the <code>N_SO</code> for the real source file;
these are believed to contain no useful information.
</p>
<p>For example:
</p>
<div class="example">
<pre class="example">.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 # <span class="roman">100 is N_SO</span>
.stabs "hello.c",100,0,0,Ltext0
.text
Ltext0:
</pre></div>
<span id="index-C_005fFILE"></span>
<p>Instead of <code>N_SO</code> symbols, XCOFF uses a <code>.file</code> assembler
directive which assembles to a <code>C_FILE</code> symbol; explaining this in
detail is outside the scope of this document.
</p>
<p>If it is useful to indicate the end of a source file, this is done with
an <code>N_SO</code> symbol with an empty string for the name. The value is
the address of the end of the text section for the file. For some
systems, there is no indication of the end of a source file, and you
just need to figure it ended when you see an <code>N_SO</code> for a different
source file, or a symbol ending in <code>.o</code> (which at least some
linkers insert to mark the start of a new <code>.o</code> file).
</p>
<hr>
</div>
<div class="section" id="Include-Files">
<div class="header">
<p>
Next: <a href="#Line-Numbers" accesskey="n" rel="next">Line Numbers</a>, Previous: <a href="#Source-Files" accesskey="p" rel="prev">Paths and Names of the Source Files</a>, Up: <a href="#Program-Structure" accesskey="u" rel="up">Encoding the Structure of the Program</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Names-of-Include-Files"></span><h3 class="section">2.3 Names of Include Files</h3>
<p>There are several schemes for dealing with include files: the
traditional <code>N_SOL</code> approach, Sun’s <code>N_BINCL</code> approach, and the
XCOFF <code>C_BINCL</code> approach (which despite the similar name has little in
common with <code>N_BINCL</code>).
</p>
<span id="index-N_005fSOL"></span>
<p>An <code>N_SOL</code> symbol specifies which include file subsequent symbols
refer to. The string field is the name of the file and the value is the
text address corresponding to the end of the previous include file and
the start of this one. To specify the main source file again, use an
<code>N_SOL</code> symbol with the name of the main source file.
</p>
<span id="index-N_005fBINCL"></span>
<span id="index-N_005fEINCL"></span>
<span id="index-N_005fEXCL"></span>
<p>The <code>N_BINCL</code> approach works as follows. An <code>N_BINCL</code> symbol
specifies the start of an include file. In an object file, only the
string is significant; the linker puts data into some of the other
fields. The end of the include file is marked by an <code>N_EINCL</code>
symbol (which has no string field). In an object file, there is no
significant data in the <code>N_EINCL</code> symbol. <code>N_BINCL</code> and
<code>N_EINCL</code> can be nested.
</p>
<p>If the linker detects that two source files have identical stabs between
an <code>N_BINCL</code> and <code>N_EINCL</code> pair (as will generally be the case
for a header file), then it only puts out the stabs once. Each
additional occurrence is replaced by an <code>N_EXCL</code> symbol. I believe
the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
ones which supports this feature.
</p>
<p>A linker which supports this feature will set the value of a
<code>N_BINCL</code> symbol to the total of all the characters in the stabs
strings included in the header file, omitting any file numbers. The
value of an <code>N_EXCL</code> symbol is the same as the value of the
<code>N_BINCL</code> symbol it replaces. This information can be used to
match up <code>N_EXCL</code> and <code>N_BINCL</code> symbols which have the same
filename. The <code>N_EINCL</code> value, and the values of the other and
description fields for all three, appear to always be zero.
</p>
<span id="index-C_005fBINCL"></span>
<span id="index-C_005fEINCL"></span>
<p>For the start of an include file in XCOFF, use the <samp>.bi</samp> assembler
directive, which generates a <code>C_BINCL</code> symbol. A <samp>.ei</samp>
directive, which generates a <code>C_EINCL</code> symbol, denotes the end of
the include file. Both directives are followed by the name of the
source file in quotes, which becomes the string for the symbol.
The value of each symbol, produced automatically by the assembler
and linker, is the offset into the executable of the beginning
(inclusive, as you’d expect) or end (inclusive, as you would not expect)
of the portion of the COFF line table that corresponds to this include
file. <code>C_BINCL</code> and <code>C_EINCL</code> do not nest.
</p>
<hr>
</div>
<div class="section" id="Line-Numbers">
<div class="header">
<p>
Next: <a href="#Procedures" accesskey="n" rel="next">Procedures</a>, Previous: <a href="#Include-Files" accesskey="p" rel="prev">Names of Include Files</a>, Up: <a href="#Program-Structure" accesskey="u" rel="up">Encoding the Structure of the Program</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Line-Numbers-1"></span><h3 class="section">2.4 Line Numbers</h3>
<span id="index-N_005fSLINE"></span>
<p>An <code>N_SLINE</code> symbol represents the start of a source line. The
desc field contains the line number and the value contains the code
address for the start of that source line. On most machines the address
is absolute; for stabs in sections (see <a href="#Stab-Sections">Using Stabs in Their Own Sections</a>), it is
relative to the function in which the <code>N_SLINE</code> symbol occurs.
</p>
<span id="index-N_005fDSLINE"></span>
<span id="index-N_005fBSLINE"></span>
<p>GNU documents <code>N_DSLINE</code> and <code>N_BSLINE</code> symbols for line
numbers in the data or bss segments, respectively. They are identical
to <code>N_SLINE</code> but are relocated differently by the linker. They
were intended to be used to describe the source location of a variable
declaration, but I believe that GCC2 actually puts the line number in
the desc field of the stab for the variable itself. GDB has been
ignoring these symbols (unless they contain a string field) since
at least GDB 3.5.
</p>
<p>For single source lines that generate discontiguous code, such as flow
of control statements, there may be more than one line number entry for
the same source line. In this case there is a line number entry at the
start of each code range, each with the same line number.
</p>
<p>XCOFF does not use stabs for line numbers. Instead, it uses COFF line
numbers (which are outside the scope of this document). Standard COFF
line numbers cannot deal with include files, but in XCOFF this is fixed
with the <code>C_BINCL</code> method of marking include files (see <a href="#Include-Files">Names of Include Files</a>).
</p>
<hr>
</div>
<div class="section" id="Procedures">
<div class="header">
<p>
Next: <a href="#Nested-Procedures" accesskey="n" rel="next">Nested Procedures</a>, Previous: <a href="#Line-Numbers" accesskey="p" rel="prev">Line Numbers</a>, Up: <a href="#Program-Structure" accesskey="u" rel="up">Encoding the Structure of the Program</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Procedures-1"></span><h3 class="section">2.5 Procedures</h3>
<span id="index-N_005fFUN_002c-for-functions"></span>
<span id="index-N_005fFNAME"></span>
<span id="index-N_005fSTSYM_002c-for-functions-_0028Sun-acc_0029"></span>
<span id="index-N_005fGSYM_002c-for-functions-_0028Sun-acc_0029"></span>
<p>All of the following stabs normally use the <code>N_FUN</code> symbol type.
However, Sun’s <code>acc</code> compiler on SunOS4 uses <code>N_GSYM</code> and
<code>N_STSYM</code>, which means that the value of the stab for the function
is useless and the debugger must get the address of the function from
the non-stab symbols instead. On systems where non-stab symbols have
leading underscores, the stabs will lack underscores and the debugger
needs to know about the leading underscore to match up the stab and the
non-stab symbol. BSD Fortran is said to use <code>N_FNAME</code> with the
same restriction; the value of the symbol is not useful (I’m not sure it
really does use this, because GDB doesn’t handle this and no one has
complained).
</p>
<span id="index-C_005fFUN"></span>
<p>A function is represented by an ‘<samp>F</samp>’ symbol descriptor for a global
(extern) function, and ‘<samp>f</samp>’ for a static (local) function. For
a.out, the value of the symbol is the address of the start of the
function; it is already relocated. For stabs in ELF, the SunPRO
compiler version 2.0.1 and GCC put out an address which gets relocated
by the linker. In a future release SunPRO is planning to put out zero,
in which case the address can be found from the ELF (non-stab) symbol.
Because looking things up in the ELF symbols would probably be slow, I’m
not sure how to find which symbol of that name is the right one, and
this doesn’t provide any way to deal with nested functions, it would
probably be better to make the value of the stab an address relative to
the start of the file, or just absolute. See <a href="#ELF-Linker-Relocation">Having the Linker Relocate Stabs in ELF</a> for more information on linker relocation of stabs in ELF
files. For XCOFF, the stab uses the <code>C_FUN</code> storage class and the
value of the stab is meaningless; the address of the function can be
found from the csect symbol (XTY_LD/XMC_PR).
</p>
<p>The type information of the stab represents the return type of the
function; thus ‘<samp>foo:f5</samp>’ means that foo is a function returning type
5. There is no need to try to get the line number of the start of the
function from the stab for the function; it is in the next
<code>N_SLINE</code> symbol.
</p>
<p>Some compilers (such as Sun’s Solaris compiler) support an extension for
specifying the types of the arguments. I suspect this extension is not
used for old (non-prototyped) function definitions in C. If the
extension is in use, the type information of the stab for the function
is followed by type information for each argument, with each argument
preceded by ‘<samp>;</samp>’. An argument type of 0 means that additional
arguments are being passed, whose types and number may vary (‘<samp>...</samp>’
in ANSI C). GDB has tolerated this extension (parsed the syntax, if not
necessarily used the information) since at least version 4.8; I don’t
know whether all versions of dbx tolerate it. The argument types given
here are not redundant with the symbols for the formal parameters
(see <a href="#Parameters">Parameters</a>); they are the types of the arguments as they are
passed, before any conversions might take place. For example, if a C
function which is declared without a prototype takes a <code>float</code>
argument, the value is passed as a <code>double</code> but then converted to a
<code>float</code>. Debuggers need to use the types given in the arguments
when printing values, but when calling the function they need to use the
types given in the symbol defining the function.
</p>
<p>If the return type and types of arguments of a function which is defined
in another source file are specified (i.e., a function prototype in ANSI
C), traditionally compilers emit no stab; the only way for the debugger
to find the information is if the source file where the function is
defined was also compiled with debugging symbols. As an extension the
Solaris compiler uses symbol descriptor ‘<samp>P</samp>’ followed by the return
type of the function, followed by the arguments, each preceded by
‘<samp>;</samp>’, as in a stab with symbol descriptor ‘<samp>f</samp>’ or ‘<samp>F</samp>’.
This use of symbol descriptor ‘<samp>P</samp>’ can be distinguished from its use
for register parameters (see <a href="#Register-Parameters">Passing Parameters in Registers</a>) by the fact that it has
symbol type <code>N_FUN</code>.
</p>
<p>The AIX documentation also defines symbol descriptor ‘<samp>J</samp>’ as an
internal function. I assume this means a function nested within another
function. It also says symbol descriptor ‘<samp>m</samp>’ is a module in
Modula-2 or extended Pascal.
</p>
<p>Procedures (functions which do not return values) are represented as
functions returning the <code>void</code> type in C. I don’t see why this couldn’t
be used for all languages (inventing a <code>void</code> type for this purpose if
necessary), but the AIX documentation defines ‘<samp>I</samp>’, ‘<samp>P</samp>’, and
‘<samp>Q</samp>’ for internal, global, and static procedures, respectively.
These symbol descriptors are unusual in that they are not followed by
type information.
</p>
<p>The following example shows a stab for a function <code>main</code> which
returns type number <code>1</code>. The <code>_main</code> specified for the value
is a reference to an assembler label which is used to fill in the start
address of the function.
</p>
<div class="example">
<pre class="example">.stabs "main:F1",36,0,0,_main # <span class="roman">36 is N_FUN</span>
</pre></div>
<p>The stab representing a procedure is located immediately following the
code of the procedure. This stab is in turn directly followed by a
group of other stabs describing elements of the procedure. These other
stabs describe the procedure’s parameters, its block local variables, and
its block structure.
</p>
<p>If functions can appear in different sections, then the debugger may not
be able to find the end of a function. Recent versions of GCC will mark
the end of a function with an <code>N_FUN</code> symbol with an empty string
for the name. The value is the address of the end of the current
function. Without such a symbol, there is no indication of the address
of the end of a function, and you must assume that it ended at the
starting address of the next function or at the end of the text section
for the program.
</p>
<hr>
</div>
<div class="section" id="Nested-Procedures">
<div class="header">
<p>
Next: <a href="#Block-Structure" accesskey="n" rel="next">Block Structure</a>, Previous: <a href="#Procedures" accesskey="p" rel="prev">Procedures</a>, Up: <a href="#Program-Structure" accesskey="u" rel="up">Encoding the Structure of the Program</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Nested-Procedures-1"></span><h3 class="section">2.6 Nested Procedures</h3>
<p>For any of the symbol descriptors representing procedures, after the
symbol descriptor and the type information is optionally a scope
specifier. This consists of a comma, the name of the procedure, another
comma, and the name of the enclosing procedure. The first name is local
to the scope specified, and seems to be redundant with the name of the
symbol (before the ‘<samp>:</samp>’). This feature is used by GCC, and
presumably Pascal, Modula-2, etc., compilers, for nested functions.
</p>
<p>If procedures are nested more than one level deep, only the immediately
containing scope is specified. For example, this code:
</p>
<div class="example">
<pre class="example">int
foo (int x)
{
int bar (int y)
{
int baz (int z)
{
return x + y + z;
}
return baz (x + 2 * y);
}
return x + bar (3 * x);
}
</pre></div>
<p>produces the stabs:
</p>
<div class="example">
<pre class="example">.stabs "baz:f1,baz,bar",36,0,0,_baz.15 # <span class="roman">36 is N_FUN</span>
.stabs "bar:f1,bar,foo",36,0,0,_bar.12
.stabs "foo:F1",36,0,0,_foo
</pre></div>
<hr>
</div>
<div class="section" id="Block-Structure">
<div class="header">
<p>
Next: <a href="#Alternate-Entry-Points" accesskey="n" rel="next">Alternate Entry Points</a>, Previous: <a href="#Nested-Procedures" accesskey="p" rel="prev">Nested Procedures</a>, Up: <a href="#Program-Structure" accesskey="u" rel="up">Encoding the Structure of the Program</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Block-Structure-1"></span><h3 class="section">2.7 Block Structure</h3>
<span id="index-N_005fLBRAC"></span>
<span id="index-N_005fRBRAC"></span>
<p>The program’s block structure is represented by the <code>N_LBRAC</code> (left
brace) and the <code>N_RBRAC</code> (right brace) stab types. The variables
defined inside a block precede the <code>N_LBRAC</code> symbol for most
compilers, including GCC. Other compilers, such as the Convex, Acorn
RISC machine, and Sun <code>acc</code> compilers, put the variables after the
<code>N_LBRAC</code> symbol. The values of the <code>N_LBRAC</code> and
<code>N_RBRAC</code> symbols are the start and end addresses of the code of
the block, respectively. For most machines, they are relative to the
starting address of this source file. For the Gould NP1, they are
absolute. For stabs in sections (see <a href="#Stab-Sections">Using Stabs in Their Own Sections</a>), they are
relative to the function in which they occur.
</p>
<p>The <code>N_LBRAC</code> and <code>N_RBRAC</code> stabs that describe the block
scope of a procedure are located after the <code>N_FUN</code> stab that
represents the procedure itself.
</p>
<p>Sun documents the desc field of <code>N_LBRAC</code> and
<code>N_RBRAC</code> symbols as containing the nesting level of the block.
However, dbx seems to not care, and GCC always sets desc to
zero.
</p>
<span id="index-_002ebb"></span>
<span id="index-_002ebe"></span>
<span id="index-C_005fBLOCK"></span>
<p>For XCOFF, block scope is indicated with <code>C_BLOCK</code> symbols. If the
name of the symbol is ‘<samp>.bb</samp>’, then it is the beginning of the block;
if the name of the symbol is ‘<samp>.be</samp>’; it is the end of the block.
</p>
<hr>
</div>
<div class="section" id="Alternate-Entry-Points">
<div class="header">
<p>
Previous: <a href="#Block-Structure" accesskey="p" rel="prev">Block Structure</a>, Up: <a href="#Program-Structure" accesskey="u" rel="up">Encoding the Structure of the Program</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Alternate-Entry-Points-1"></span><h3 class="section">2.8 Alternate Entry Points</h3>
<span id="index-N_005fENTRY"></span>
<span id="index-C_005fENTRY"></span>
<p>Some languages, like Fortran, have the ability to enter procedures at
some place other than the beginning. One can declare an alternate entry
point. The <code>N_ENTRY</code> stab is for this; however, the Sun FORTRAN
compiler doesn’t use it. According to AIX documentation, only the name
of a <code>C_ENTRY</code> stab is significant; the address of the alternate
entry point comes from the corresponding external symbol. A previous
revision of this document said that the value of an <code>N_ENTRY</code> stab
was the address of the alternate entry point, but I don’t know the
source for that information.
</p>
<hr>
</div>
</div>
<div class="chapter" id="Constants">
<div class="header">
<p>
Next: <a href="#Variables" accesskey="n" rel="next">Variables</a>, Previous: <a href="#Program-Structure" accesskey="p" rel="prev">Encoding the Structure of the Program</a>, Up: <a href="#Top" accesskey="u" rel="up">The "stabs" representation of debugging information</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<span id="Constants-1"></span><h2 class="chapter">3 Constants</h2>
<p>The ‘<samp>c</samp>’ symbol descriptor indicates that this stab represents a
constant. This symbol descriptor is an exception to the general rule
that symbol descriptors are followed by type information. Instead, it
is followed by ‘<samp>=</samp>’ and one of the following:
</p>
<dl compact="compact">