OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [gdb-5.0/] [gdb/] [doc/] [stabs.texinfo] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 106 markom
\input texinfo
2
@setfilename stabs.info
3
 
4
@c @finalout
5
 
6
@ifinfo
7
@format
8
START-INFO-DIR-ENTRY
9
* Stabs: (stabs).                 The "stabs" debugging information format.
10
END-INFO-DIR-ENTRY
11
@end format
12
@end ifinfo
13
 
14
@ifinfo
15
This document describes the stabs debugging symbol tables.
16
 
17
Copyright 1992, 93, 94, 95, 97, 1998 Free Software Foundation, Inc.
18
Contributed by Cygnus Support.  Written by Julia Menapace, Jim Kingdon,
19
and David MacKenzie.
20
 
21
Permission is granted to make and distribute verbatim copies of
22
this manual provided the copyright notice and this permission notice
23
are preserved on all copies.
24
 
25
@ignore
26
Permission is granted to process this file through Tex and print the
27
results, provided the printed document carries copying permission
28
notice identical to this one except for the removal of this paragraph
29
(this paragraph not being relevant to the printed manual).
30
 
31
@end ignore
32
Permission is granted to copy or distribute modified versions of this
33
manual under the terms of the GPL (for which purpose this text may be
34
regarded as a program in the language TeX).
35
@end ifinfo
36
 
37
@setchapternewpage odd
38
@settitle STABS
39
@titlepage
40
@title The ``stabs'' debug format
41
@author Julia Menapace, Jim Kingdon, David MacKenzie
42
@author Cygnus Support
43
@page
44
@tex
45
\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
46
\xdef\manvers{\$Revision: 1.1.1.1 $}  % For use in headers, footers too
47
{\parskip=0pt
48
\hfill Cygnus Support\par
49
\hfill \manvers\par
50
\hfill \TeX{}info \texinfoversion\par
51
}
52
@end tex
53
 
54
@vskip 0pt plus 1filll
55
Copyright @copyright{} 1992, 93, 94, 95, 97, 1998 Free Software Foundation, Inc.
56
Contributed by Cygnus Support.
57
 
58
Permission is granted to make and distribute verbatim copies of
59
this manual provided the copyright notice and this permission notice
60
are preserved on all copies.
61
 
62
@end titlepage
63
 
64
@ifinfo
65
@node Top
66
@top The "stabs" representation of debugging information
67
 
68
This document describes the stabs debugging format.
69
 
70
@menu
71
* Overview::                    Overview of stabs
72
* Program Structure::           Encoding of the structure of the program
73
* Constants::                   Constants
74
* Variables::
75
* Types::                       Type definitions
76
* Symbol Tables::               Symbol information in symbol tables
77
* Cplusplus::                   Stabs specific to C++
78
* Stab Types::                  Symbol types in a.out files
79
* Symbol Descriptors::          Table of symbol descriptors
80
* Type Descriptors::            Table of type descriptors
81
* Expanded Reference::          Reference information by stab type
82
* Questions::                   Questions and anomolies
83
* Stab Sections::               In some object file formats, stabs are
84
                                in sections.
85
* Symbol Types Index::          Index of symbolic stab symbol type names.
86
@end menu
87
@end ifinfo
88
 
89
 
90
@node Overview
91
@chapter Overview of Stabs
92
 
93
@dfn{Stabs} refers to a format for information that describes a program
94
to a debugger.  This format was apparently invented by
95
Peter Kessler at
96
the University of California at Berkeley, for the @code{pdx} Pascal
97
debugger; the format has spread widely since then.
98
 
99
This document is one of the few published sources of documentation on
100
stabs.  It is believed to be comprehensive for stabs used by C.  The
101
lists of symbol descriptors (@pxref{Symbol Descriptors}) and type
102
descriptors (@pxref{Type Descriptors}) are believed to be completely
103
comprehensive.  Stabs for COBOL-specific features and for variant
104
records (used by Pascal and Modula-2) are poorly documented here.
105
 
106
@c FIXME: Need to document all OS9000 stuff in GDB; see all references
107
@c to os9k_stabs in stabsread.c.
108
 
109
Other sources of information on stabs are @cite{Dbx and Dbxtool
110
Interfaces}, 2nd edition, by Sun, 1988, and @cite{AIX Version 3.2 Files
111
Reference}, Fourth Edition, September 1992, "dbx Stabstring Grammar" in
112
the a.out section, page 2-31.  This document is believed to incorporate
113
the information from those two sources except where it explicitly directs
114
you to them for more information.
115
 
116
@menu
117
* Flow::                        Overview of debugging information flow
118
* Stabs Format::                Overview of stab format
119
* String Field::                The string field
120
* C Example::                   A simple example in C source
121
* Assembly Code::               The simple example at the assembly level
122
@end menu
123
 
124
@node Flow
125
@section Overview of Debugging Information Flow
126
 
127
The GNU C compiler compiles C source in a @file{.c} file into assembly
128
language in a @file{.s} file, which the assembler translates into
129
a @file{.o} file, which the linker combines with other @file{.o} files and
130
libraries to produce an executable file.
131
 
132
With the @samp{-g} option, GCC puts in the @file{.s} file additional
133
debugging information, which is slightly transformed by the assembler
134
and linker, and carried through into the final executable.  This
135
debugging information describes features of the source file like line
136
numbers, the types and scopes of variables, and function names,
137
parameters, and scopes.
138
 
139
For some object file formats, the debugging information is encapsulated
140
in assembler directives known collectively as @dfn{stab} (symbol table)
141
directives, which are interspersed with the generated code.  Stabs are
142
the native format for debugging information in the a.out and XCOFF
143
object file formats.  The GNU tools can also emit stabs in the COFF and
144
ECOFF object file formats.
145
 
146
The assembler adds the information from stabs to the symbol information
147
it places by default in the symbol table and the string table of the
148
@file{.o} file it is building.  The linker consolidates the @file{.o}
149
files into one executable file, with one symbol table and one string
150
table.  Debuggers use the symbol and string tables in the executable as
151
a source of debugging information about the program.
152
 
153
@node Stabs Format
154
@section Overview of Stab Format
155
 
156
There are three overall formats for stab assembler directives,
157
differentiated by the first word of the stab.  The name of the directive
158
describes which combination of four possible data fields follows.  It is
159
either @code{.stabs} (string), @code{.stabn} (number), or @code{.stabd}
160
(dot).  IBM's XCOFF assembler uses @code{.stabx} (and some other
161
directives such as @code{.file} and @code{.bi}) instead of
162
@code{.stabs}, @code{.stabn} or @code{.stabd}.
163
 
164
The overall format of each class of stab is:
165
 
166
@example
167
.stabs "@var{string}",@var{type},@var{other},@var{desc},@var{value}
168
.stabn @var{type},@var{other},@var{desc},@var{value}
169
.stabd @var{type},@var{other},@var{desc}
170
.stabx "@var{string}",@var{value},@var{type},@var{sdb-type}
171
@end example
172
 
173
@c what is the correct term for "current file location"?  My AIX
174
@c assembler manual calls it "the value of the current location counter".
175
For @code{.stabn} and @code{.stabd}, there is no @var{string} (the
176
@code{n_strx} field is zero; see @ref{Symbol Tables}).  For
177
@code{.stabd}, the @var{value} field is implicit and has the value of
178
the current file location.  For @code{.stabx}, the @var{sdb-type} field
179
is unused for stabs and can always be set to zero.  The @var{other}
180
field is almost always unused and can be set to zero.
181
 
182
The number in the @var{type} field gives some basic information about
183
which type of stab this is (or whether it @emph{is} a stab, as opposed
184
to an ordinary symbol).  Each valid type number defines a different stab
185
type; further, the stab type defines the exact interpretation of, and
186
possible values for, any remaining @var{string}, @var{desc}, or
187
@var{value} fields present in the stab.  @xref{Stab Types}, for a list
188
in numeric order of the valid @var{type} field values for stab directives.
189
 
190
@node String Field
191
@section The String Field
192
 
193
For most stabs the string field holds the meat of the
194
debugging information.  The flexible nature of this field
195
is what makes stabs extensible.  For some stab types the string field
196
contains only a name.  For other stab types the contents can be a great
197
deal more complex.
198
 
199
The overall format of the string field for most stab types is:
200
 
201
@example
202
"@var{name}:@var{symbol-descriptor} @var{type-information}"
203
@end example
204
 
205
@var{name} is the name of the symbol represented by the stab; it can
206
contain a pair of colons (@pxref{Nested Symbols}).  @var{name} can be
207
omitted, which means the stab represents an unnamed object.  For
208
example, @samp{:t10=*2} defines type 10 as a pointer to type 2, but does
209
not give the type a name.  Omitting the @var{name} field is supported by
210
AIX dbx and GDB after about version 4.8, but not other debuggers.  GCC
211
sometimes uses a single space as the name instead of omitting the name
212
altogether; apparently that is supported by most debuggers.
213
 
214
The @var{symbol-descriptor} following the @samp{:} is an alphabetic
215
character that tells more specifically what kind of symbol the stab
216
represents. If the @var{symbol-descriptor} is omitted, but type
217
information follows, then the stab represents a local variable.  For a
218
list of symbol descriptors, see @ref{Symbol Descriptors}.  The @samp{c}
219
symbol descriptor is an exception in that it is not followed by type
220
information.  @xref{Constants}.
221
 
222
@var{type-information} is either a @var{type-number}, or
223
@samp{@var{type-number}=}.  A @var{type-number} alone is a type
224
reference, referring directly to a type that has already been defined.
225
 
226
The @samp{@var{type-number}=} form is a type definition, where the
227
number represents a new type which is about to be defined.  The type
228
definition may refer to other types by number, and those type numbers
229
may be followed by @samp{=} and nested definitions.  Also, the Lucid
230
compiler will repeat @samp{@var{type-number}=} more than once if it
231
wants to define several type numbers at once.
232
 
233
In a type definition, if the character that follows the equals sign is
234
non-numeric then it is a @var{type-descriptor}, and tells what kind of
235
type is about to be defined.  Any other values following the
236
@var{type-descriptor} vary, depending on the @var{type-descriptor}.
237
@xref{Type Descriptors}, for a list of @var{type-descriptor} values.  If
238
a number follows the @samp{=} then the number is a @var{type-reference}.
239
For a full description of types, @ref{Types}.
240
 
241
A @var{type-number} is often a single number.  The GNU and Sun tools
242
additionally permit a @var{type-number} to be a pair
243
(@var{file-number},@var{filetype-number}) (the parentheses appear in the
244
string, and serve to distinguish the two cases).  The @var{file-number}
245
is a number starting with 1 which is incremented for each seperate
246
source file in the compilation (e.g., in C, each header file gets a
247
different number).  The @var{filetype-number} is a number starting with
248
1 which is incremented for each new type defined in the file.
249
(Separating the file number and the type number permits the
250
@code{N_BINCL} optimization to succeed more often; see @ref{Include
251
Files}).
252
 
253
There is an AIX extension for type attributes.  Following the @samp{=}
254
are any number of type attributes.  Each one starts with @samp{@@} and
255
ends with @samp{;}.  Debuggers, including AIX's dbx and GDB 4.10, skip
256
any type attributes they do not recognize.  GDB 4.9 and other versions
257
of dbx may not do this.  Because of a conflict with C++
258
(@pxref{Cplusplus}), new attributes should not be defined which begin
259
with a digit, @samp{(}, or @samp{-}; GDB may be unable to distinguish
260
those from the C++ type descriptor @samp{@@}.  The attributes are:
261
 
262
@table @code
263
@item a@var{boundary}
264
@var{boundary} is an integer specifying the alignment.  I assume it
265
applies to all variables of this type.
266
 
267
@item p@var{integer}
268
Pointer class (for checking).  Not sure what this means, or how
269
@var{integer} is interpreted.
270
 
271
@item P
272
Indicate this is a packed type, meaning that structure fields or array
273
elements are placed more closely in memory, to save memory at the
274
expense of speed.
275
 
276
@item s@var{size}
277
Size in bits of a variable of this type.  This is fully supported by GDB
278
4.11 and later.
279
 
280
@item S
281
Indicate that this type is a string instead of an array of characters,
282
or a bitstring instead of a set.  It doesn't change the layout of the
283
data being represented, but does enable the debugger to know which type
284
it is.
285
@end table
286
 
287
All of this can make the string field quite long.  All versions of GDB,
288
and some versions of dbx, can handle arbitrarily long strings.  But many
289
versions of dbx (or assemblers or linkers, I'm not sure which)
290
cretinously limit the strings to about 80 characters, so compilers which
291
must work with such systems need to split the @code{.stabs} directive
292
into several @code{.stabs} directives.  Each stab duplicates every field
293
except the string field.  The string field of every stab except the last
294
is marked as continued with a backslash at the end (in the assembly code
295
this may be written as a double backslash, depending on the assembler).
296
Removing the backslashes and concatenating the string fields of each
297
stab produces the original, long string.  Just to be incompatible (or so
298
they don't have to worry about what the assembler does with
299
backslashes), AIX can use @samp{?} instead of backslash.
300
 
301
@node C Example
302
@section A Simple Example in C Source
303
 
304
To get the flavor of how stabs describe source information for a C
305
program, let's look at the simple program:
306
 
307
@example
308
main()
309
@{
310
        printf("Hello world");
311
@}
312
@end example
313
 
314
When compiled with @samp{-g}, the program above yields the following
315
@file{.s} file.  Line numbers have been added to make it easier to refer
316
to parts of the @file{.s} file in the description of the stabs that
317
follows.
318
 
319
@node Assembly Code
320
@section The Simple Example at the Assembly Level
321
 
322
This simple ``hello world'' example demonstrates several of the stab
323
types used to describe C language source files.
324
 
325
@example
326
1  gcc2_compiled.:
327
2  .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
328
3  .stabs "hello.c",100,0,0,Ltext0
329
4  .text
330
5  Ltext0:
331
6  .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
332
7  .stabs "char:t2=r2;0;127;",128,0,0,0
333
8  .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
334
9  .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
335
10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
336
11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
337
12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
338
13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
339
14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
340
15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
341
16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
342
17 .stabs "float:t12=r1;4;0;",128,0,0,0
343
18 .stabs "double:t13=r1;8;0;",128,0,0,0
344
19 .stabs "long double:t14=r1;8;0;",128,0,0,0
345
20 .stabs "void:t15=15",128,0,0,0
346
21      .align 4
347
22 LC0:
348
23      .ascii "Hello, world!\12\0"
349
24      .align 4
350
25      .global _main
351
26      .proc 1
352
27 _main:
353
28 .stabn 68,0,4,LM1
354
29 LM1:
355
30      !#PROLOGUE# 0
356
31      save %sp,-136,%sp
357
32      !#PROLOGUE# 1
358
33      call ___main,0
359
34      nop
360
35 .stabn 68,0,5,LM2
361
36 LM2:
362
37 LBB2:
363
38      sethi %hi(LC0),%o1
364
39      or %o1,%lo(LC0),%o0
365
40      call _printf,0
366
41      nop
367
42 .stabn 68,0,6,LM3
368
43 LM3:
369
44 LBE2:
370
45 .stabn 68,0,6,LM4
371
46 LM4:
372
47 L1:
373
48      ret
374
49      restore
375
50 .stabs "main:F1",36,0,0,_main
376
51 .stabn 192,0,0,LBB2
377
52 .stabn 224,0,0,LBE2
378
@end example
379
 
380
@node Program Structure
381
@chapter Encoding the Structure of the Program
382
 
383
The elements of the program structure that stabs encode include the name
384
of the main function, the names of the source and include files, the
385
line numbers, procedure names and types, and the beginnings and ends of
386
blocks of code.
387
 
388
@menu
389
* Main Program::                Indicate what the main program is
390
* Source Files::                The path and name of the source file
391
* Include Files::               Names of include files
392
* Line Numbers::
393
* Procedures::
394
* Nested Procedures::
395
* Block Structure::
396
* Alternate Entry Points::      Entering procedures except at the beginning.
397
@end menu
398
 
399
@node Main Program
400
@section Main Program
401
 
402
@findex N_MAIN
403
Most languages allow the main program to have any name.  The
404
@code{N_MAIN} stab type tells the debugger the name that is used in this
405
program.  Only the string field is significant; it is the name of
406
a function which is the main program.  Most C compilers do not use this
407
stab (they expect the debugger to assume that the name is @code{main}),
408
but some C compilers emit an @code{N_MAIN} stab for the @code{main}
409
function.  I'm not sure how XCOFF handles this.
410
 
411
@node Source Files
412
@section Paths and Names of the Source Files
413
 
414
@findex N_SO
415
Before any other stabs occur, there must be a stab specifying the source
416
file.  This information is contained in a symbol of stab type
417
@code{N_SO}; the string field contains the name of the file.  The
418
value of the symbol is the start address of the portion of the
419
text section corresponding to that file.
420
 
421
With the Sun Solaris2 compiler, the desc field contains a
422
source-language code.
423
@c Do the debuggers use it?  What are the codes? -djm
424
 
425
Some compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also
426
include the directory in which the source was compiled, in a second
427
@code{N_SO} symbol preceding the one containing the file name.  This
428
symbol can be distinguished by the fact that it ends in a slash.  Code
429
from the @code{cfront} C++ compiler can have additional @code{N_SO} symbols for
430
nonexistent source files after the @code{N_SO} for the real source file;
431
these are believed to contain no useful information.
432
 
433
For example:
434
 
435
@example
436
.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0     # @r{100 is N_SO}
437
.stabs "hello.c",100,0,0,Ltext0
438
        .text
439
Ltext0:
440
@end example
441
 
442
@findex C_FILE
443
Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler
444
directive which assembles to a @code{C_FILE} symbol; explaining this in
445
detail is outside the scope of this document.
446
 
447
@c FIXME: Exactly when should the empty N_SO be used?  Why?
448
If it is useful to indicate the end of a source file, this is done with
449
an @code{N_SO} symbol with an empty string for the name.  The value is
450
the address of the end of the text section for the file.  For some
451
systems, there is no indication of the end of a source file, and you
452
just need to figure it ended when you see an @code{N_SO} for a different
453
source file, or a symbol ending in @code{.o} (which at least some
454
linkers insert to mark the start of a new @code{.o} file).
455
 
456
@node Include Files
457
@section Names of Include Files
458
 
459
There are several schemes for dealing with include files: the
460
traditional @code{N_SOL} approach, Sun's @code{N_BINCL} approach, and the
461
XCOFF @code{C_BINCL} approach (which despite the similar name has little in
462
common with @code{N_BINCL}).
463
 
464
@findex N_SOL
465
An @code{N_SOL} symbol specifies which include file subsequent symbols
466
refer to.  The string field is the name of the file and the value is the
467
text address corresponding to the end of the previous include file and
468
the start of this one.  To specify the main source file again, use an
469
@code{N_SOL} symbol with the name of the main source file.
470
 
471
@findex N_BINCL
472
@findex N_EINCL
473
@findex N_EXCL
474
The @code{N_BINCL} approach works as follows.  An @code{N_BINCL} symbol
475
specifies the start of an include file.  In an object file, only the
476
string is significant; the linker puts data into some of the other
477
fields.  The end of the include file is marked by an @code{N_EINCL}
478
symbol (which has no string field).  In an object file, there is no
479
significant data in the @code{N_EINCL} symbol.  @code{N_BINCL} and
480
@code{N_EINCL} can be nested.
481
 
482
If the linker detects that two source files have identical stabs between
483
an @code{N_BINCL} and @code{N_EINCL} pair (as will generally be the case
484
for a header file), then it only puts out the stabs once.  Each
485
additional occurance is replaced by an @code{N_EXCL} symbol.  I believe
486
the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
487
ones which supports this feature.
488
 
489
A linker which supports this feature will set the value of a
490
@code{N_BINCL} symbol to the total of all the characters in the stabs
491
strings included in the header file, omitting any file numbers.  The
492
value of an @code{N_EXCL} symbol is the same as the value of the
493
@code{N_BINCL} symbol it replaces.  This information can be used to
494
match up @code{N_EXCL} and @code{N_BINCL} symbols which have the same
495
filename.  The @code{N_EINCL} value, and the values of the other and
496
description fields for all three, appear to always be zero.
497
 
498
@findex C_BINCL
499
@findex C_EINCL
500
For the start of an include file in XCOFF, use the @file{.bi} assembler
501
directive, which generates a @code{C_BINCL} symbol.  A @file{.ei}
502
directive, which generates a @code{C_EINCL} symbol, denotes the end of
503
the include file.  Both directives are followed by the name of the
504
source file in quotes, which becomes the string for the symbol.
505
The value of each symbol, produced automatically by the assembler
506
and linker, is the offset into the executable of the beginning
507
(inclusive, as you'd expect) or end (inclusive, as you would not expect)
508
of the portion of the COFF line table that corresponds to this include
509
file.  @code{C_BINCL} and @code{C_EINCL} do not nest.
510
 
511
@node Line Numbers
512
@section Line Numbers
513
 
514
@findex N_SLINE
515
An @code{N_SLINE} symbol represents the start of a source line.  The
516
desc field contains the line number and the value contains the code
517
address for the start of that source line.  On most machines the address
518
is absolute; for stabs in sections (@pxref{Stab Sections}), it is
519
relative to the function in which the @code{N_SLINE} symbol occurs.
520
 
521
@findex N_DSLINE
522
@findex N_BSLINE
523
GNU documents @code{N_DSLINE} and @code{N_BSLINE} symbols for line
524
numbers in the data or bss segments, respectively.  They are identical
525
to @code{N_SLINE} but are relocated differently by the linker.  They
526
were intended to be used to describe the source location of a variable
527
declaration, but I believe that GCC2 actually puts the line number in
528
the desc field of the stab for the variable itself.  GDB has been
529
ignoring these symbols (unless they contain a string field) since
530
at least GDB 3.5.
531
 
532
For single source lines that generate discontiguous code, such as flow
533
of control statements, there may be more than one line number entry for
534
the same source line.  In this case there is a line number entry at the
535
start of each code range, each with the same line number.
536
 
537
XCOFF does not use stabs for line numbers.  Instead, it uses COFF line
538
numbers (which are outside the scope of this document).  Standard COFF
539
line numbers cannot deal with include files, but in XCOFF this is fixed
540
with the @code{C_BINCL} method of marking include files (@pxref{Include
541
Files}).
542
 
543
@node Procedures
544
@section Procedures
545
 
546
@findex N_FUN, for functions
547
@findex N_FNAME
548
@findex N_STSYM, for functions (Sun acc)
549
@findex N_GSYM, for functions (Sun acc)
550
All of the following stabs normally use the @code{N_FUN} symbol type.
551
However, Sun's @code{acc} compiler on SunOS4 uses @code{N_GSYM} and
552
@code{N_STSYM}, which means that the value of the stab for the function
553
is useless and the debugger must get the address of the function from
554
the non-stab symbols instead.  On systems where non-stab symbols have
555
leading underscores, the stabs will lack underscores and the debugger
556
needs to know about the leading underscore to match up the stab and the
557
non-stab symbol.  BSD Fortran is said to use @code{N_FNAME} with the
558
same restriction; the value of the symbol is not useful (I'm not sure it
559
really does use this, because GDB doesn't handle this and no one has
560
complained).
561
 
562
@findex C_FUN
563
A function is represented by an @samp{F} symbol descriptor for a global
564
(extern) function, and @samp{f} for a static (local) function.  For
565
a.out, the value of the symbol is the address of the start of the
566
function; it is already relocated.  For stabs in ELF, the SunPRO
567
compiler version 2.0.1 and GCC put out an address which gets relocated
568
by the linker.  In a future release SunPRO is planning to put out zero,
569
in which case the address can be found from the ELF (non-stab) symbol.
570
Because looking things up in the ELF symbols would probably be slow, I'm
571
not sure how to find which symbol of that name is the right one, and
572
this doesn't provide any way to deal with nested functions, it would
573
probably be better to make the value of the stab an address relative to
574
the start of the file, or just absolute.  See @ref{ELF Linker
575
Relocation} for more information on linker relocation of stabs in ELF
576
files.  For XCOFF, the stab uses the @code{C_FUN} storage class and the
577
value of the stab is meaningless; the address of the function can be
578
found from the csect symbol (XTY_LD/XMC_PR).
579
 
580
The type information of the stab represents the return type of the
581
function; thus @samp{foo:f5} means that foo is a function returning type
582
5.  There is no need to try to get the line number of the start of the
583
function from the stab for the function; it is in the next
584
@code{N_SLINE} symbol.
585
 
586
@c FIXME: verify whether the "I suspect" below is true or not.
587
Some compilers (such as Sun's Solaris compiler) support an extension for
588
specifying the types of the arguments.  I suspect this extension is not
589
used for old (non-prototyped) function definitions in C.  If the
590
extension is in use, the type information of the stab for the function
591
is followed by type information for each argument, with each argument
592
preceded by @samp{;}.  An argument type of 0 means that additional
593
arguments are being passed, whose types and number may vary (@samp{...}
594
in ANSI C).  GDB has tolerated this extension (parsed the syntax, if not
595
necessarily used the information) since at least version 4.8; I don't
596
know whether all versions of dbx tolerate it.  The argument types given
597
here are not redundant with the symbols for the formal parameters
598
(@pxref{Parameters}); they are the types of the arguments as they are
599
passed, before any conversions might take place.  For example, if a C
600
function which is declared without a prototype takes a @code{float}
601
argument, the value is passed as a @code{double} but then converted to a
602
@code{float}.  Debuggers need to use the types given in the arguments
603
when printing values, but when calling the function they need to use the
604
types given in the symbol defining the function.
605
 
606
If the return type and types of arguments of a function which is defined
607
in another source file are specified (i.e., a function prototype in ANSI
608
C), traditionally compilers emit no stab; the only way for the debugger
609
to find the information is if the source file where the function is
610
defined was also compiled with debugging symbols.  As an extension the
611
Solaris compiler uses symbol descriptor @samp{P} followed by the return
612
type of the function, followed by the arguments, each preceded by
613
@samp{;}, as in a stab with symbol descriptor @samp{f} or @samp{F}.
614
This use of symbol descriptor @samp{P} can be distinguished from its use
615
for register parameters (@pxref{Register Parameters}) by the fact that it has
616
symbol type @code{N_FUN}.
617
 
618
The AIX documentation also defines symbol descriptor @samp{J} as an
619
internal function.  I assume this means a function nested within another
620
function.  It also says symbol descriptor @samp{m} is a module in
621
Modula-2 or extended Pascal.
622
 
623
Procedures (functions which do not return values) are represented as
624
functions returning the @code{void} type in C.  I don't see why this couldn't
625
be used for all languages (inventing a @code{void} type for this purpose if
626
necessary), but the AIX documentation defines @samp{I}, @samp{P}, and
627
@samp{Q} for internal, global, and static procedures, respectively.
628
These symbol descriptors are unusual in that they are not followed by
629
type information.
630
 
631
The following example shows a stab for a function @code{main} which
632
returns type number @code{1}.  The @code{_main} specified for the value
633
is a reference to an assembler label which is used to fill in the start
634
address of the function.
635
 
636
@example
637
.stabs "main:F1",36,0,0,_main      # @r{36 is N_FUN}
638
@end example
639
 
640
The stab representing a procedure is located immediately following the
641
code of the procedure.  This stab is in turn directly followed by a
642
group of other stabs describing elements of the procedure.  These other
643
stabs describe the procedure's parameters, its block local variables, and
644
its block structure.
645
 
646
If functions can appear in different sections, then the debugger may not
647
be able to find the end of a function.  Recent versions of GCC will mark
648
the end of a function with an @code{N_FUN} symbol with an empty string
649
for the name.  The value is the address of the end of the current
650
function.  Without such a symbol, there is no indication of the address
651
of the end of a function, and you must assume that it ended at the
652
starting address of the next function or at the end of the text section
653
for the program.
654
 
655
@node Nested Procedures
656
@section Nested Procedures
657
 
658
For any of the symbol descriptors representing procedures, after the
659
symbol descriptor and the type information is optionally a scope
660
specifier.  This consists of a comma, the name of the procedure, another
661
comma, and the name of the enclosing procedure.  The first name is local
662
to the scope specified, and seems to be redundant with the name of the
663
symbol (before the @samp{:}).  This feature is used by GCC, and
664
presumably Pascal, Modula-2, etc., compilers, for nested functions.
665
 
666
If procedures are nested more than one level deep, only the immediately
667
containing scope is specified.  For example, this code:
668
 
669
@example
670
int
671
foo (int x)
672
@{
673
  int bar (int y)
674
    @{
675
      int baz (int z)
676
        @{
677
          return x + y + z;
678
        @}
679
      return baz (x + 2 * y);
680
    @}
681
  return x + bar (3 * x);
682
@}
683
@end example
684
 
685
@noindent
686
produces the stabs:
687
 
688
@example
689
.stabs "baz:f1,baz,bar",36,0,0,_baz.15         # @r{36 is N_FUN}
690
.stabs "bar:f1,bar,foo",36,0,0,_bar.12
691
.stabs "foo:F1",36,0,0,_foo
692
@end example
693
 
694
@node Block Structure
695
@section Block Structure
696
 
697
@findex N_LBRAC
698
@findex N_RBRAC
699
@c For GCC 2.5.8 or so stabs-in-coff, these are absolute instead of
700
@c function relative (as documented below).  But GDB has never been able
701
@c to deal with that (it had wanted them to be relative to the file, but
702
@c I just fixed that (between GDB 4.12 and 4.13)), so it is function
703
@c relative just like ELF and SOM and the below documentation.
704
The program's block structure is represented by the @code{N_LBRAC} (left
705
brace) and the @code{N_RBRAC} (right brace) stab types.  The variables
706
defined inside a block precede the @code{N_LBRAC} symbol for most
707
compilers, including GCC.  Other compilers, such as the Convex, Acorn
708
RISC machine, and Sun @code{acc} compilers, put the variables after the
709
@code{N_LBRAC} symbol.  The values of the @code{N_LBRAC} and
710
@code{N_RBRAC} symbols are the start and end addresses of the code of
711
the block, respectively.  For most machines, they are relative to the
712
starting address of this source file.  For the Gould NP1, they are
713
absolute.  For stabs in sections (@pxref{Stab Sections}), they are
714
relative to the function in which they occur.
715
 
716
The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block
717
scope of a procedure are located after the @code{N_FUN} stab that
718
represents the procedure itself.
719
 
720
Sun documents the desc field of @code{N_LBRAC} and
721
@code{N_RBRAC} symbols as containing the nesting level of the block.
722
However, dbx seems to not care, and GCC always sets desc to
723
zero.
724
 
725
@findex .bb
726
@findex .be
727
@findex C_BLOCK
728
For XCOFF, block scope is indicated with @code{C_BLOCK} symbols.  If the
729
name of the symbol is @samp{.bb}, then it is the beginning of the block;
730
if the name of the symbol is @samp{.be}; it is the end of the block.
731
 
732
@node Alternate Entry Points
733
@section Alternate Entry Points
734
 
735
@findex N_ENTRY
736
@findex C_ENTRY
737
Some languages, like Fortran, have the ability to enter procedures at
738
some place other than the beginning.  One can declare an alternate entry
739
point.  The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN
740
compiler doesn't use it.  According to AIX documentation, only the name
741
of a @code{C_ENTRY} stab is significant; the address of the alternate
742
entry point comes from the corresponding external symbol.  A previous
743
revision of this document said that the value of an @code{N_ENTRY} stab
744
was the address of the alternate entry point, but I don't know the
745
source for that information.
746
 
747
@node Constants
748
@chapter Constants
749
 
750
The @samp{c} symbol descriptor indicates that this stab represents a
751
constant.  This symbol descriptor is an exception to the general rule
752
that symbol descriptors are followed by type information.  Instead, it
753
is followed by @samp{=} and one of the following:
754
 
755
@table @code
756
@item b @var{value}
757
Boolean constant.  @var{value} is a numeric value; I assume it is 0 for
758
false or 1 for true.
759
 
760
@item c @var{value}
761
Character constant.  @var{value} is the numeric value of the constant.
762
 
763
@item e @var{type-information} , @var{value}
764
Constant whose value can be represented as integral.
765
@var{type-information} is the type of the constant, as it would appear
766
after a symbol descriptor (@pxref{String Field}).  @var{value} is the
767
numeric value of the constant.  GDB 4.9 does not actually get the right
768
value if @var{value} does not fit in a host @code{int}, but it does not
769
do anything violent, and future debuggers could be extended to accept
770
integers of any size (whether unsigned or not).  This constant type is
771
usually documented as being only for enumeration constants, but GDB has
772
never imposed that restriction; I don't know about other debuggers.
773
 
774
@item i @var{value}
775
Integer constant.  @var{value} is the numeric value.  The type is some
776
sort of generic integer type (for GDB, a host @code{int}); to specify
777
the type explicitly, use @samp{e} instead.
778
 
779
@item r @var{value}
780
Real constant.  @var{value} is the real value, which can be @samp{INF}
781
(optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet
782
NaN (not-a-number), or @samp{SNAN} for a signalling NaN.  If it is a
783
normal number the format is that accepted by the C library function
784
@code{atof}.
785
 
786
@item s @var{string}
787
String constant.  @var{string} is a string enclosed in either @samp{'}
788
(in which case @samp{'} characters within the string are represented as
789
@samp{\'} or @samp{"} (in which case @samp{"} characters within the
790
string are represented as @samp{\"}).
791
 
792
@item S @var{type-information} , @var{elements} , @var{bits} , @var{pattern}
793
Set constant.  @var{type-information} is the type of the constant, as it
794
would appear after a symbol descriptor (@pxref{String Field}).
795
@var{elements} is the number of elements in the set (does this means
796
how many bits of @var{pattern} are actually used, which would be
797
redundant with the type, or perhaps the number of bits set in
798
@var{pattern}?  I don't get it), @var{bits} is the number of bits in the
799
constant (meaning it specifies the length of @var{pattern}, I think),
800
and @var{pattern} is a hexadecimal representation of the set.  AIX
801
documentation refers to a limit of 32 bytes, but I see no reason why
802
this limit should exist.  This form could probably be used for arbitrary
803
constants, not just sets; the only catch is that @var{pattern} should be
804
understood to be target, not host, byte order and format.
805
@end table
806
 
807
The boolean, character, string, and set constants are not supported by
808
GDB 4.9, but it ignores them.  GDB 4.8 and earlier gave an error
809
message and refused to read symbols from the file containing the
810
constants.
811
 
812
The above information is followed by @samp{;}.
813
 
814
@node Variables
815
@chapter Variables
816
 
817
Different types of stabs describe the various ways that variables can be
818
allocated: on the stack, globally, in registers, in common blocks,
819
statically, or as arguments to a function.
820
 
821
@menu
822
* Stack Variables::             Variables allocated on the stack.
823
* Global Variables::            Variables used by more than one source file.
824
* Register Variables::          Variables in registers.
825
* Common Blocks::               Variables statically allocated together.
826
* Statics::                     Variables local to one source file.
827
* Based Variables::             Fortran pointer based variables.
828
* Parameters::                  Variables for arguments to functions.
829
@end menu
830
 
831
@node Stack Variables
832
@section Automatic Variables Allocated on the Stack
833
 
834
If a variable's scope is local to a function and its lifetime is only as
835
long as that function executes (C calls such variables
836
@dfn{automatic}), it can be allocated in a register (@pxref{Register
837
Variables}) or on the stack.
838
 
839
@findex N_LSYM, for stack variables
840
@findex C_LSYM
841
Each variable allocated on the stack has a stab with the symbol
842
descriptor omitted.  Since type information should begin with a digit,
843
@samp{-}, or @samp{(}, only those characters precluded from being used
844
for symbol descriptors.  However, the Acorn RISC machine (ARM) is said
845
to get this wrong: it puts out a mere type definition here, without the
846
preceding @samp{@var{type-number}=}.  This is a bad idea; there is no
847
guarantee that type descriptors are distinct from symbol descriptors.
848
Stabs for stack variables use the @code{N_LSYM} stab type, or
849
@code{C_LSYM} for XCOFF.
850
 
851
The value of the stab is the offset of the variable within the
852
local variables.  On most machines this is an offset from the frame
853
pointer and is negative.  The location of the stab specifies which block
854
it is defined in; see @ref{Block Structure}.
855
 
856
For example, the following C code:
857
 
858
@example
859
int
860
main ()
861
@{
862
  int x;
863
@}
864
@end example
865
 
866
produces the following stabs:
867
 
868
@example
869
.stabs "main:F1",36,0,0,_main   # @r{36 is N_FUN}
870
.stabs "x:1",128,0,0,-12        # @r{128 is N_LSYM}
871
.stabn 192,0,0,LBB2             # @r{192 is N_LBRAC}
872
.stabn 224,0,0,LBE2             # @r{224 is N_RBRAC}
873
@end example
874
 
875
See @ref{Procedures} for more information on the @code{N_FUN} stab, and
876
@ref{Block Structure} for more information on the @code{N_LBRAC} and
877
@code{N_RBRAC} stabs.
878
 
879
@node Global Variables
880
@section Global Variables
881
 
882
@findex N_GSYM
883
@findex C_GSYM
884
@c FIXME: verify for sure that it really is C_GSYM on XCOFF
885
A variable whose scope is not specific to just one source file is
886
represented by the @samp{G} symbol descriptor.  These stabs use the
887
@code{N_GSYM} stab type (C_GSYM for XCOFF).  The type information for
888
the stab (@pxref{String Field}) gives the type of the variable.
889
 
890
For example, the following source code:
891
 
892
@example
893
char g_foo = 'c';
894
@end example
895
 
896
@noindent
897
yields the following assembly code:
898
 
899
@example
900
.stabs "g_foo:G2",32,0,0,0     # @r{32 is N_GSYM}
901
     .global _g_foo
902
     .data
903
_g_foo:
904
     .byte 99
905
@end example
906
 
907
The address of the variable represented by the @code{N_GSYM} is not
908
contained in the @code{N_GSYM} stab.  The debugger gets this information
909
from the external symbol for the global variable.  In the example above,
910
the @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to
911
produce an external symbol.
912
 
913
Some compilers, like GCC, output @code{N_GSYM} stabs only once, where
914
the variable is defined.  Other compilers, like SunOS4 /bin/cc, output a
915
@code{N_GSYM} stab for each compilation unit which references the
916
variable.
917
 
918
@node Register Variables
919
@section Register Variables
920
 
921
@findex N_RSYM
922
@findex C_RSYM
923
@c According to an old version of this manual, AIX uses C_RPSYM instead
924
@c of C_RSYM.  I am skeptical; this should be verified.
925
Register variables have their own stab type, @code{N_RSYM}
926
(@code{C_RSYM} for XCOFF), and their own symbol descriptor, @samp{r}.
927
The stab's value is the number of the register where the variable data
928
will be stored.
929
@c .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc)
930
 
931
AIX defines a separate symbol descriptor @samp{d} for floating point
932
registers.  This seems unnecessary; why not just just give floating
933
point registers different register numbers?  I have not verified whether
934
the compiler actually uses @samp{d}.
935
 
936
If the register is explicitly allocated to a global variable, but not
937
initialized, as in:
938
 
939
@example
940
register int g_bar asm ("%g5");
941
@end example
942
 
943
@noindent
944
then the stab may be emitted at the end of the object file, with
945
the other bss symbols.
946
 
947
@node Common Blocks
948
@section Common Blocks
949
 
950
A common block is a statically allocated section of memory which can be
951
referred to by several source files.  It may contain several variables.
952
I believe Fortran is the only language with this feature.
953
 
954
@findex N_BCOMM
955
@findex N_ECOMM
956
@findex C_BCOMM
957
@findex C_ECOMM
958
A @code{N_BCOMM} stab begins a common block and an @code{N_ECOMM} stab
959
ends it.  The only field that is significant in these two stabs is the
960
string, which names a normal (non-debugging) symbol that gives the
961
address of the common block.  According to IBM documentation, only the
962
@code{N_BCOMM} has the name of the common block (even though their
963
compiler actually puts it both places).
964
 
965
@findex N_ECOML
966
@findex C_ECOML
967
The stabs for the members of the common block are between the
968
@code{N_BCOMM} and the @code{N_ECOMM}; the value of each stab is the
969
offset within the common block of that variable.  IBM uses the
970
@code{C_ECOML} stab type, and there is a corresponding @code{N_ECOML}
971
stab type, but Sun's Fortran compiler uses @code{N_GSYM} instead.  The
972
variables within a common block use the @samp{V} symbol descriptor (I
973
believe this is true of all Fortran variables).  Other stabs (at least
974
type declarations using @code{C_DECL}) can also be between the
975
@code{N_BCOMM} and the @code{N_ECOMM}.
976
 
977
@node Statics
978
@section Static Variables
979
 
980
Initialized static variables are represented by the @samp{S} and
981
@samp{V} symbol descriptors.  @samp{S} means file scope static, and
982
@samp{V} means procedure scope static.  One exception: in XCOFF, IBM's
983
xlc compiler always uses @samp{V}, and whether it is file scope or not
984
is distinguished by whether the stab is located within a function.
985
 
986
@c This is probably not worth mentioning; it is only true on the sparc
987
@c for `double' variables which although declared const are actually in
988
@c the data segment (the text segment can't guarantee 8 byte alignment).
989
@c (although GCC
990
@c 2.4.5 has a bug in that it uses @code{N_FUN}, so neither dbx nor GDB can
991
@c find the variables)
992
@findex N_STSYM
993
@findex N_LCSYM
994
@findex N_FUN, for variables
995
@findex N_ROSYM
996
In a.out files, @code{N_STSYM} means the data section, @code{N_FUN}
997
means the text section, and @code{N_LCSYM} means the bss section.  For
998
those systems with a read-only data section separate from the text
999
section (Solaris), @code{N_ROSYM} means the read-only data section.
1000
 
1001
For example, the source lines:
1002
 
1003
@example
1004
static const int var_const = 5;
1005
static int var_init = 2;
1006
static int var_noinit;
1007
@end example
1008
 
1009
@noindent
1010
yield the following stabs:
1011
 
1012
@example
1013
.stabs "var_const:S1",36,0,0,_var_const      # @r{36 is N_FUN}
1014
@dots{}
1015
.stabs "var_init:S1",38,0,0,_var_init        # @r{38 is N_STSYM}
1016
@dots{}
1017
.stabs "var_noinit:S1",40,0,0,_var_noinit    # @r{40 is N_LCSYM}
1018
@end example
1019
 
1020
@findex C_STSYM
1021
@findex C_BSTAT
1022
@findex C_ESTAT
1023
In XCOFF files, the stab type need not indicate the section;
1024
@code{C_STSYM} can be used for all statics.  Also, each static variable
1025
is enclosed in a static block.  A @code{C_BSTAT} (emitted with a
1026
@samp{.bs} assembler directive) symbol begins the static block; its
1027
value is the symbol number of the csect symbol whose value is the
1028
address of the static block, its section is the section of the variables
1029
in that static block, and its name is @samp{.bs}.  A @code{C_ESTAT}
1030
(emitted with a @samp{.es} assembler directive) symbol ends the static
1031
block; its name is @samp{.es} and its value and section are ignored.
1032
 
1033
In ECOFF files, the storage class is used to specify the section, so the
1034
stab type need not indicate the section.
1035
 
1036
In ELF files, for the SunPRO compiler version 2.0.1, symbol descriptor
1037
@samp{S} means that the address is absolute (the linker relocates it)
1038
and symbol descriptor @samp{V} means that the address is relative to the
1039
start of the relevant section for that compilation unit.  SunPRO has
1040
plans to have the linker stop relocating stabs; I suspect that their the
1041
debugger gets the address from the corresponding ELF (not stab) symbol.
1042
I'm not sure how to find which symbol of that name is the right one.
1043
The clean way to do all this would be to have a the value of a symbol
1044
descriptor @samp{S} symbol be an offset relative to the start of the
1045
file, just like everything else, but that introduces obvious
1046
compatibility problems.  For more information on linker stab relocation,
1047
@xref{ELF Linker Relocation}.
1048
 
1049
@node Based Variables
1050
@section Fortran Based Variables
1051
 
1052
Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature
1053
which allows allocating arrays with @code{malloc}, but which avoids
1054
blurring the line between arrays and pointers the way that C does.  In
1055
stabs such a variable uses the @samp{b} symbol descriptor.
1056
 
1057
For example, the Fortran declarations
1058
 
1059
@example
1060
real foo, foo10(10), foo10_5(10,5)
1061
pointer (foop, foo)
1062
pointer (foo10p, foo10)
1063
pointer (foo105p, foo10_5)
1064
@end example
1065
 
1066
produce the stabs
1067
 
1068
@example
1069
foo:b6
1070
foo10:bar3;1;10;6
1071
foo10_5:bar3;1;5;ar3;1;10;6
1072
@end example
1073
 
1074
In this example, @code{real} is type 6 and type 3 is an integral type
1075
which is the type of the subscripts of the array (probably
1076
@code{integer}).
1077
 
1078
The @samp{b} symbol descriptor is like @samp{V} in that it denotes a
1079
statically allocated symbol whose scope is local to a function; see
1080
@xref{Statics}.  The value of the symbol, instead of being the address
1081
of the variable itself, is the address of a pointer to that variable.
1082
So in the above example, the value of the @code{foo} stab is the address
1083
of a pointer to a real, the value of the @code{foo10} stab is the
1084
address of a pointer to a 10-element array of reals, and the value of
1085
the @code{foo10_5} stab is the address of a pointer to a 5-element array
1086
of 10-element arrays of reals.
1087
 
1088
@node Parameters
1089
@section Parameters
1090
 
1091
Formal parameters to a function are represented by a stab (or sometimes
1092
two; see below) for each parameter.  The stabs are in the order in which
1093
the debugger should print the parameters (i.e., the order in which the
1094
parameters are declared in the source file).  The exact form of the stab
1095
depends on how the parameter is being passed.
1096
 
1097
@findex N_PSYM
1098
@findex C_PSYM
1099
Parameters passed on the stack use the symbol descriptor @samp{p} and
1100
the @code{N_PSYM} symbol type (or @code{C_PSYM} for XCOFF).  The value
1101
of the symbol is an offset used to locate the parameter on the stack;
1102
its exact meaning is machine-dependent, but on most machines it is an
1103
offset from the frame pointer.
1104
 
1105
As a simple example, the code:
1106
 
1107
@example
1108
main (argc, argv)
1109
     int argc;
1110
     char **argv;
1111
@end example
1112
 
1113
produces the stabs:
1114
 
1115
@example
1116
.stabs "main:F1",36,0,0,_main                 # @r{36 is N_FUN}
1117
.stabs "argc:p1",160,0,0,68                   # @r{160 is N_PSYM}
1118
.stabs "argv:p20=*21=*2",160,0,0,72
1119
@end example
1120
 
1121
The type definition of @code{argv} is interesting because it contains
1122
several type definitions.  Type 21 is pointer to type 2 (char) and
1123
@code{argv} (type 20) is pointer to type 21.
1124
 
1125
@c FIXME: figure out what these mean and describe them coherently.
1126
The following symbol descriptors are also said to go with @code{N_PSYM}.
1127
The value of the symbol is said to be an offset from the argument
1128
pointer (I'm not sure whether this is true or not).
1129
 
1130
@example
1131
pP (<<??>>)
1132
pF Fortran function parameter
1133
X  (function result variable)
1134
@end example
1135
 
1136
@menu
1137
* Register Parameters::
1138
* Local Variable Parameters::
1139
* Reference Parameters::
1140
* Conformant Arrays::
1141
@end menu
1142
 
1143
@node Register Parameters
1144
@subsection Passing Parameters in Registers
1145
 
1146
If the parameter is passed in a register, then traditionally there are
1147
two symbols for each argument:
1148
 
1149
@example
1150
.stabs "arg:p1" . . .       ; N_PSYM
1151
.stabs "arg:r1" . . .       ; N_RSYM
1152
@end example
1153
 
1154
Debuggers use the second one to find the value, and the first one to
1155
know that it is an argument.
1156
 
1157
@findex C_RPSYM
1158
@findex N_RSYM, for parameters
1159
Because that approach is kind of ugly, some compilers use symbol
1160
descriptor @samp{P} or @samp{R} to indicate an argument which is in a
1161
register.  Symbol type @code{C_RPSYM} is used in XCOFF and @code{N_RSYM}
1162
is used otherwise.  The symbol's value is the register number.  @samp{P}
1163
and @samp{R} mean the same thing; the difference is that @samp{P} is a
1164
GNU invention and @samp{R} is an IBM (XCOFF) invention.  As of version
1165
4.9, GDB should handle either one.
1166
 
1167
There is at least one case where GCC uses a @samp{p} and @samp{r} pair
1168
rather than @samp{P}; this is where the argument is passed in the
1169
argument list and then loaded into a register.
1170
 
1171
According to the AIX documentation, symbol descriptor @samp{D} is for a
1172
parameter passed in a floating point register.  This seems
1173
unnecessary---why not just use @samp{R} with a register number which
1174
indicates that it's a floating point register?  I haven't verified
1175
whether the system actually does what the documentation indicates.
1176
 
1177
@c FIXME: On the hppa this is for any type > 8 bytes, I think, and not
1178
@c for small structures (investigate).
1179
On the sparc and hppa, for a @samp{P} symbol whose type is a structure
1180
or union, the register contains the address of the structure.  On the
1181
sparc, this is also true of a @samp{p} and @samp{r} pair (using Sun
1182
@code{cc}) or a @samp{p} symbol.  However, if a (small) structure is
1183
really in a register, @samp{r} is used.  And, to top it all off, on the
1184
hppa it might be a structure which was passed on the stack and loaded
1185
into a register and for which there is a @samp{p} and @samp{r} pair!  I
1186
believe that symbol descriptor @samp{i} is supposed to deal with this
1187
case (it is said to mean "value parameter by reference, indirect
1188
access"; I don't know the source for this information), but I don't know
1189
details or what compilers or debuggers use it, if any (not GDB or GCC).
1190
It is not clear to me whether this case needs to be dealt with
1191
differently than parameters passed by reference (@pxref{Reference Parameters}).
1192
 
1193
@node Local Variable Parameters
1194
@subsection Storing Parameters as Local Variables
1195
 
1196
There is a case similar to an argument in a register, which is an
1197
argument that is actually stored as a local variable.  Sometimes this
1198
happens when the argument was passed in a register and then the compiler
1199
stores it as a local variable.  If possible, the compiler should claim
1200
that it's in a register, but this isn't always done.
1201
 
1202
If a parameter is passed as one type and converted to a smaller type by
1203
the prologue (for example, the parameter is declared as a @code{float},
1204
but the calling conventions specify that it is passed as a
1205
@code{double}), then GCC2 (sometimes) uses a pair of symbols.  The first
1206
symbol uses symbol descriptor @samp{p} and the type which is passed.
1207
The second symbol has the type and location which the parameter actually
1208
has after the prologue.  For example, suppose the following C code
1209
appears with no prototypes involved:
1210
 
1211
@example
1212
void
1213
subr (f)
1214
     float f;
1215
@{
1216
@end example
1217
 
1218
if @code{f} is passed as a double at stack offset 8, and the prologue
1219
converts it to a float in register number 0, then the stabs look like:
1220
 
1221
@example
1222
.stabs "f:p13",160,0,3,8   # @r{160 is @code{N_PSYM}, here 13 is @code{double}}
1223
.stabs "f:r12",64,0,3,0    # @r{64 is @code{N_RSYM}, here 12 is @code{float}}
1224
@end example
1225
 
1226
In both stabs 3 is the line number where @code{f} is declared
1227
(@pxref{Line Numbers}).
1228
 
1229
@findex N_LSYM, for parameter
1230
GCC, at least on the 960, has another solution to the same problem.  It
1231
uses a single @samp{p} symbol descriptor for an argument which is stored
1232
as a local variable but uses @code{N_LSYM} instead of @code{N_PSYM}.  In
1233
this case, the value of the symbol is an offset relative to the local
1234
variables for that function, not relative to the arguments; on some
1235
machines those are the same thing, but not on all.
1236
 
1237
@c This is mostly just background info; the part that logically belongs
1238
@c here is the last sentence.
1239
On the VAX or on other machines in which the calling convention includes
1240
the number of words of arguments actually passed, the debugger (GDB at
1241
least) uses the parameter symbols to keep track of whether it needs to
1242
print nameless arguments in addition to the formal parameters which it
1243
has printed because each one has a stab.  For example, in
1244
 
1245
@example
1246
extern int fprintf (FILE *stream, char *format, @dots{});
1247
@dots{}
1248
fprintf (stdout, "%d\n", x);
1249
@end example
1250
 
1251
there are stabs for @code{stream} and @code{format}.  On most machines,
1252
the debugger can only print those two arguments (because it has no way
1253
of knowing that additional arguments were passed), but on the VAX or
1254
other machines with a calling convention which indicates the number of
1255
words of arguments, the debugger can print all three arguments.  To do
1256
so, the parameter symbol (symbol descriptor @samp{p}) (not necessarily
1257
@samp{r} or symbol descriptor omitted symbols) needs to contain the
1258
actual type as passed (for example, @code{double} not @code{float} if it
1259
is passed as a double and converted to a float).
1260
 
1261
@node Reference Parameters
1262
@subsection Passing Parameters by Reference
1263
 
1264
If the parameter is passed by reference (e.g., Pascal @code{VAR}
1265
parameters), then the symbol descriptor is @samp{v} if it is in the
1266
argument list, or @samp{a} if it in a register.  Other than the fact
1267
that these contain the address of the parameter rather than the
1268
parameter itself, they are identical to @samp{p} and @samp{R},
1269
respectively.  I believe @samp{a} is an AIX invention; @samp{v} is
1270
supported by all stabs-using systems as far as I know.
1271
 
1272
@node Conformant Arrays
1273
@subsection Passing Conformant Array Parameters
1274
 
1275
@c Is this paragraph correct?  It is based on piecing together patchy
1276
@c information and some guesswork
1277
Conformant arrays are a feature of Modula-2, and perhaps other
1278
languages, in which the size of an array parameter is not known to the
1279
called function until run-time.  Such parameters have two stabs: a
1280
@samp{x} for the array itself, and a @samp{C}, which represents the size
1281
of the array.  The value of the @samp{x} stab is the offset in the
1282
argument list where the address of the array is stored (it this right?
1283
it is a guess); the value of the @samp{C} stab is the offset in the
1284
argument list where the size of the array (in elements? in bytes?) is
1285
stored.
1286
 
1287
@node Types
1288
@chapter Defining Types
1289
 
1290
The examples so far have described types as references to previously
1291
defined types, or defined in terms of subranges of or pointers to
1292
previously defined types.  This chapter describes the other type
1293
descriptors that may follow the @samp{=} in a type definition.
1294
 
1295
@menu
1296
* Builtin Types::               Integers, floating point, void, etc.
1297
* Miscellaneous Types::         Pointers, sets, files, etc.
1298
* Cross-References::            Referring to a type not yet defined.
1299
* Subranges::                   A type with a specific range.
1300
* Arrays::                      An aggregate type of same-typed elements.
1301
* Strings::                     Like an array but also has a length.
1302
* Enumerations::                Like an integer but the values have names.
1303
* Structures::                  An aggregate type of different-typed elements.
1304
* Typedefs::                    Giving a type a name.
1305
* Unions::                      Different types sharing storage.
1306
* Function Types::
1307
@end menu
1308
 
1309
@node Builtin Types
1310
@section Builtin Types
1311
 
1312
Certain types are built in (@code{int}, @code{short}, @code{void},
1313
@code{float}, etc.); the debugger recognizes these types and knows how
1314
to handle them.  Thus, don't be surprised if some of the following ways
1315
of specifying builtin types do not specify everything that a debugger
1316
would need to know about the type---in some cases they merely specify
1317
enough information to distinguish the type from other types.
1318
 
1319
The traditional way to define builtin types is convolunted, so new ways
1320
have been invented to describe them.  Sun's @code{acc} uses special
1321
builtin type descriptors (@samp{b} and @samp{R}), and IBM uses negative
1322
type numbers.  GDB accepts all three ways, as of version 4.8; dbx just
1323
accepts the traditional builtin types and perhaps one of the other two
1324
formats.  The following sections describe each of these formats.
1325
 
1326
@menu
1327
* Traditional Builtin Types::   Put on your seatbelts and prepare for kludgery
1328
* Builtin Type Descriptors::    Builtin types with special type descriptors
1329
* Negative Type Numbers::       Builtin types using negative type numbers
1330
@end menu
1331
 
1332
@node Traditional Builtin Types
1333
@subsection Traditional Builtin Types
1334
 
1335
This is the traditional, convoluted method for defining builtin types.
1336
There are several classes of such type definitions: integer, floating
1337
point, and @code{void}.
1338
 
1339
@menu
1340
* Traditional Integer Types::
1341
* Traditional Other Types::
1342
@end menu
1343
 
1344
@node Traditional Integer Types
1345
@subsubsection Traditional Integer Types
1346
 
1347
Often types are defined as subranges of themselves.  If the bounding values
1348
fit within an @code{int}, then they are given normally.  For example:
1349
 
1350
@example
1351
.stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0    # @r{128 is N_LSYM}
1352
.stabs "char:t2=r2;0;127;",128,0,0,0
1353
@end example
1354
 
1355
Builtin types can also be described as subranges of @code{int}:
1356
 
1357
@example
1358
.stabs "unsigned short:t6=r1;0;65535;",128,0,0,0
1359
@end example
1360
 
1361
If the lower bound of a subrange is 0 and the upper bound is -1,
1362
the type is an unsigned integral type whose bounds are too
1363
big to describe in an @code{int}.  Traditionally this is only used for
1364
@code{unsigned int} and @code{unsigned long}:
1365
 
1366
@example
1367
.stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
1368
@end example
1369
 
1370
For larger types, GCC 2.4.5 puts out bounds in octal, with one or more
1371
leading zeroes.  In this case a negative bound consists of a number
1372
which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in
1373
the number (except the sign bit), and a positive bound is one which is a
1374
1 bit for each bit in the number (except possibly the sign bit).  All
1375
known versions of dbx and GDB version 4 accept this (at least in the
1376
sense of not refusing to process the file), but GDB 3.5 refuses to read
1377
the whole file containing such symbols.  So GCC 2.3.3 did not output the
1378
proper size for these types.  As an example of octal bounds, the string
1379
fields of the stabs for 64 bit integer types look like:
1380
 
1381
@c .stabs directives, etc., omitted to make it fit on the page.
1382
@example
1383
long int:t3=r1;001000000000000000000000;000777777777777777777777;
1384
long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777;
1385
@end example
1386
 
1387
If the lower bound of a subrange is 0 and the upper bound is negative,
1388
the type is an unsigned integral type whose size in bytes is the
1389
absolute value of the upper bound.  I believe this is a Convex
1390
convention for @code{unsigned long long}.
1391
 
1392
If the lower bound of a subrange is negative and the upper bound is 0,
1393
the type is a signed integral type whose size in bytes is
1394
the absolute value of the lower bound.  I believe this is a Convex
1395
convention for @code{long long}.  To distinguish this from a legitimate
1396
subrange, the type should be a subrange of itself.  I'm not sure whether
1397
this is the case for Convex.
1398
 
1399
@node Traditional Other Types
1400
@subsubsection Traditional Other Types
1401
 
1402
If the upper bound of a subrange is 0 and the lower bound is positive,
1403
the type is a floating point type, and the lower bound of the subrange
1404
indicates the number of bytes in the type:
1405
 
1406
@example
1407
.stabs "float:t12=r1;4;0;",128,0,0,0
1408
.stabs "double:t13=r1;8;0;",128,0,0,0
1409
@end example
1410
 
1411
However, GCC writes @code{long double} the same way it writes
1412
@code{double}, so there is no way to distinguish.
1413
 
1414
@example
1415
.stabs "long double:t14=r1;8;0;",128,0,0,0
1416
@end example
1417
 
1418
Complex types are defined the same way as floating-point types; there is
1419
no way to distinguish a single-precision complex from a double-precision
1420
floating-point type.
1421
 
1422
The C @code{void} type is defined as itself:
1423
 
1424
@example
1425
.stabs "void:t15=15",128,0,0,0
1426
@end example
1427
 
1428
I'm not sure how a boolean type is represented.
1429
 
1430
@node Builtin Type Descriptors
1431
@subsection Defining Builtin Types Using Builtin Type Descriptors
1432
 
1433
This is the method used by Sun's @code{acc} for defining builtin types.
1434
These are the type descriptors to define builtin types:
1435
 
1436
@table @code
1437
@c FIXME: clean up description of width and offset, once we figure out
1438
@c what they mean
1439
@item b @var{signed} @var{char-flag} @var{width} ; @var{offset} ; @var{nbits} ;
1440
Define an integral type.  @var{signed} is @samp{u} for unsigned or
1441
@samp{s} for signed.  @var{char-flag} is @samp{c} which indicates this
1442
is a character type, or is omitted.  I assume this is to distinguish an
1443
integral type from a character type of the same size, for example it
1444
might make sense to set it for the C type @code{wchar_t} so the debugger
1445
can print such variables differently (Solaris does not do this).  Sun
1446
sets it on the C types @code{signed char} and @code{unsigned char} which
1447
arguably is wrong.  @var{width} and @var{offset} appear to be for small
1448
objects stored in larger ones, for example a @code{short} in an
1449
@code{int} register.  @var{width} is normally the number of bytes in the
1450
type.  @var{offset} seems to always be zero.  @var{nbits} is the number
1451
of bits in the type.
1452
 
1453
Note that type descriptor @samp{b} used for builtin types conflicts with
1454
its use for Pascal space types (@pxref{Miscellaneous Types}); they can
1455
be distinguished because the character following the type descriptor
1456
will be a digit, @samp{(}, or @samp{-} for a Pascal space type, or
1457
@samp{u} or @samp{s} for a builtin type.
1458
 
1459
@item w
1460
Documented by AIX to define a wide character type, but their compiler
1461
actually uses negative type numbers (@pxref{Negative Type Numbers}).
1462
 
1463
@item R @var{fp-type} ; @var{bytes} ;
1464
Define a floating point type.  @var{fp-type} has one of the following values:
1465
 
1466
@table @code
1467
@item 1 (NF_SINGLE)
1468
IEEE 32-bit (single precision) floating point format.
1469
 
1470
@item 2 (NF_DOUBLE)
1471
IEEE 64-bit (double precision) floating point format.
1472
 
1473
@item 3 (NF_COMPLEX)
1474
@item 4 (NF_COMPLEX16)
1475
@item 5 (NF_COMPLEX32)
1476
@c "GDB source" really means @file{include/aout/stab_gnu.h}, but trying
1477
@c to put that here got an overfull hbox.
1478
These are for complex numbers.  A comment in the GDB source describes
1479
them as Fortran @code{complex}, @code{double complex}, and
1480
@code{complex*16}, respectively, but what does that mean?  (i.e., Single
1481
precision?  Double precison?).
1482
 
1483
@item 6 (NF_LDOUBLE)
1484
Long double.  This should probably only be used for Sun format
1485
@code{long double}, and new codes should be used for other floating
1486
point formats (@code{NF_DOUBLE} can be used if a @code{long double} is
1487
really just an IEEE double, of course).
1488
@end table
1489
 
1490
@var{bytes} is the number of bytes occupied by the type.  This allows a
1491
debugger to perform some operations with the type even if it doesn't
1492
understand @var{fp-type}.
1493
 
1494
@item g @var{type-information} ; @var{nbits}
1495
Documented by AIX to define a floating type, but their compiler actually
1496
uses negative type numbers (@pxref{Negative Type Numbers}).
1497
 
1498
@item c @var{type-information} ; @var{nbits}
1499
Documented by AIX to define a complex type, but their compiler actually
1500
uses negative type numbers (@pxref{Negative Type Numbers}).
1501
@end table
1502
 
1503
The C @code{void} type is defined as a signed integral type 0 bits long:
1504
@example
1505
.stabs "void:t19=bs0;0;0",128,0,0,0
1506
@end example
1507
The Solaris compiler seems to omit the trailing semicolon in this case.
1508
Getting sloppy in this way is not a swift move because if a type is
1509
embedded in a more complex expression it is necessary to be able to tell
1510
where it ends.
1511
 
1512
I'm not sure how a boolean type is represented.
1513
 
1514
@node Negative Type Numbers
1515
@subsection Negative Type Numbers
1516
 
1517
This is the method used in XCOFF for defining builtin types.
1518
Since the debugger knows about the builtin types anyway, the idea of
1519
negative type numbers is simply to give a special type number which
1520
indicates the builtin type.  There is no stab defining these types.
1521
 
1522
There are several subtle issues with negative type numbers.
1523
 
1524
One is the size of the type.  A builtin type (for example the C types
1525
@code{int} or @code{long}) might have different sizes depending on
1526
compiler options, the target architecture, the ABI, etc.  This issue
1527
doesn't come up for IBM tools since (so far) they just target the
1528
RS/6000; the sizes indicated below for each size are what the IBM
1529
RS/6000 tools use.  To deal with differing sizes, either define separate
1530
negative type numbers for each size (which works but requires changing
1531
the debugger, and, unless you get both AIX dbx and GDB to accept the
1532
change, introduces an incompatibility), or use a type attribute
1533
(@pxref{String Field}) to define a new type with the appropriate size
1534
(which merely requires a debugger which understands type attributes,
1535
like AIX dbx or GDB).  For example,
1536
 
1537
@example
1538
.stabs "boolean:t10=@@s8;-16",128,0,0,0
1539
@end example
1540
 
1541
defines an 8-bit boolean type, and
1542
 
1543
@example
1544
.stabs "boolean:t10=@@s64;-16",128,0,0,0
1545
@end example
1546
 
1547
defines a 64-bit boolean type.
1548
 
1549
A similar issue is the format of the type.  This comes up most often for
1550
floating-point types, which could have various formats (particularly
1551
extended doubles, which vary quite a bit even among IEEE systems).
1552
Again, it is best to define a new negative type number for each
1553
different format; changing the format based on the target system has
1554
various problems.  One such problem is that the Alpha has both VAX and
1555
IEEE floating types.  One can easily imagine one library using the VAX
1556
types and another library in the same executable using the IEEE types.
1557
Another example is that the interpretation of whether a boolean is true
1558
or false can be based on the least significant bit, most significant
1559
bit, whether it is zero, etc., and different compilers (or different
1560
options to the same compiler) might provide different kinds of boolean.
1561
 
1562
The last major issue is the names of the types.  The name of a given
1563
type depends @emph{only} on the negative type number given; these do not
1564
vary depending on the language, the target system, or anything else.
1565
One can always define separate type numbers---in the following list you
1566
will see for example separate @code{int} and @code{integer*4} types
1567
which are identical except for the name.  But compatibility can be
1568
maintained by not inventing new negative type numbers and instead just
1569
defining a new type with a new name.  For example:
1570
 
1571
@example
1572
.stabs "CARDINAL:t10=-8",128,0,0,0
1573
@end example
1574
 
1575
Here is the list of negative type numbers.  The phrase @dfn{integral
1576
type} is used to mean twos-complement (I strongly suspect that all
1577
machines which use stabs use twos-complement; most machines use
1578
twos-complement these days).
1579
 
1580
@table @code
1581
@item -1
1582
@code{int}, 32 bit signed integral type.
1583
 
1584
@item -2
1585
@code{char}, 8 bit type holding a character.   Both GDB and dbx on AIX
1586
treat this as signed.  GCC uses this type whether @code{char} is signed
1587
or not, which seems like a bad idea.  The AIX compiler (@code{xlc}) seems to
1588
avoid this type; it uses -5 instead for @code{char}.
1589
 
1590
@item -3
1591
@code{short}, 16 bit signed integral type.
1592
 
1593
@item -4
1594
@code{long}, 32 bit signed integral type.
1595
 
1596
@item -5
1597
@code{unsigned char}, 8 bit unsigned integral type.
1598
 
1599
@item -6
1600
@code{signed char}, 8 bit signed integral type.
1601
 
1602
@item -7
1603
@code{unsigned short}, 16 bit unsigned integral type.
1604
 
1605
@item -8
1606
@code{unsigned int}, 32 bit unsigned integral type.
1607
 
1608
@item -9
1609
@code{unsigned}, 32 bit unsigned integral type.
1610
 
1611
@item -10
1612
@code{unsigned long}, 32 bit unsigned integral type.
1613
 
1614
@item -11
1615
@code{void}, type indicating the lack of a value.
1616
 
1617
@item -12
1618
@code{float}, IEEE single precision.
1619
 
1620
@item -13
1621
@code{double}, IEEE double precision.
1622
 
1623
@item -14
1624
@code{long double}, IEEE double precision.  The compiler claims the size
1625
will increase in a future release, and for binary compatibility you have
1626
to avoid using @code{long double}.  I hope when they increase it they
1627
use a new negative type number.
1628
 
1629
@item -15
1630
@code{integer}.  32 bit signed integral type.
1631
 
1632
@item -16
1633
@code{boolean}.  32 bit type.  GDB and GCC assume that zero is false,
1634
one is true, and other values have unspecified meaning.  I hope this
1635
agrees with how the IBM tools use the type.
1636
 
1637
@item -17
1638
@code{short real}.  IEEE single precision.
1639
 
1640
@item -18
1641
@code{real}.  IEEE double precision.
1642
 
1643
@item -19
1644
@code{stringptr}.  @xref{Strings}.
1645
 
1646
@item -20
1647
@code{character}, 8 bit unsigned character type.
1648
 
1649
@item -21
1650
@code{logical*1}, 8 bit type.  This Fortran type has a split
1651
personality in that it is used for boolean variables, but can also be
1652
used for unsigned integers.  0 is false, 1 is true, and other values are
1653
non-boolean.
1654
 
1655
@item -22
1656
@code{logical*2}, 16 bit type.  This Fortran type has a split
1657
personality in that it is used for boolean variables, but can also be
1658
used for unsigned integers.  0 is false, 1 is true, and other values are
1659
non-boolean.
1660
 
1661
@item -23
1662
@code{logical*4}, 32 bit type.  This Fortran type has a split
1663
personality in that it is used for boolean variables, but can also be
1664
used for unsigned integers.  0 is false, 1 is true, and other values are
1665
non-boolean.
1666
 
1667
@item -24
1668
@code{logical}, 32 bit type.  This Fortran type has a split
1669
personality in that it is used for boolean variables, but can also be
1670
used for unsigned integers.  0 is false, 1 is true, and other values are
1671
non-boolean.
1672
 
1673
@item -25
1674
@code{complex}.  A complex type consisting of two IEEE single-precision
1675
floating point values.
1676
 
1677
@item -26
1678
@code{complex}.  A complex type consisting of two IEEE double-precision
1679
floating point values.
1680
 
1681
@item -27
1682
@code{integer*1}, 8 bit signed integral type.
1683
 
1684
@item -28
1685
@code{integer*2}, 16 bit signed integral type.
1686
 
1687
@item -29
1688
@code{integer*4}, 32 bit signed integral type.
1689
 
1690
@item -30
1691
@code{wchar}.  Wide character, 16 bits wide, unsigned (what format?
1692
Unicode?).
1693
 
1694
@item -31
1695
@code{long long}, 64 bit signed integral type.
1696
 
1697
@item -32
1698
@code{unsigned long long}, 64 bit unsigned integral type.
1699
 
1700
@item -33
1701
@code{logical*8}, 64 bit unsigned integral type.
1702
 
1703
@item -34
1704
@code{integer*8}, 64 bit signed integral type.
1705
@end table
1706
 
1707
@node Miscellaneous Types
1708
@section Miscellaneous Types
1709
 
1710
@table @code
1711
@item b @var{type-information} ; @var{bytes}
1712
Pascal space type.  This is documented by IBM; what does it mean?
1713
 
1714
This use of the @samp{b} type descriptor can be distinguished
1715
from its use for builtin integral types (@pxref{Builtin Type
1716
Descriptors}) because the character following the type descriptor is
1717
always a digit, @samp{(}, or @samp{-}.
1718
 
1719
@item B @var{type-information}
1720
A volatile-qualified version of @var{type-information}.  This is
1721
a Sun extension.  References and stores to a variable with a
1722
volatile-qualified type must not be optimized or cached; they
1723
must occur as the user specifies them.
1724
 
1725
@item d @var{type-information}
1726
File of type @var{type-information}.  As far as I know this is only used
1727
by Pascal.
1728
 
1729
@item k @var{type-information}
1730
A const-qualified version of @var{type-information}.  This is a Sun
1731
extension.  A variable with a const-qualified type cannot be modified.
1732
 
1733
@item M @var{type-information} ; @var{length}
1734
Multiple instance type.  The type seems to composed of @var{length}
1735
repetitions of @var{type-information}, for example @code{character*3} is
1736
represented by @samp{M-2;3}, where @samp{-2} is a reference to a
1737
character type (@pxref{Negative Type Numbers}).  I'm not sure how this
1738
differs from an array.  This appears to be a Fortran feature.
1739
@var{length} is a bound, like those in range types; see @ref{Subranges}.
1740
 
1741
@item S @var{type-information}
1742
Pascal set type.  @var{type-information} must be a small type such as an
1743
enumeration or a subrange, and the type is a bitmask whose length is
1744
specified by the number of elements in @var{type-information}.
1745
 
1746
In CHILL, if it is a bitstring instead of a set, also use the @samp{S}
1747
type attribute (@pxref{String Field}).
1748
 
1749
@item * @var{type-information}
1750
Pointer to @var{type-information}.
1751
@end table
1752
 
1753
@node Cross-References
1754
@section Cross-References to Other Types
1755
 
1756
A type can be used before it is defined; one common way to deal with
1757
that situation is just to use a type reference to a type which has not
1758
yet been defined.
1759
 
1760
Another way is with the @samp{x} type descriptor, which is followed by
1761
@samp{s} for a structure tag, @samp{u} for a union tag, or @samp{e} for
1762
a enumerator tag, followed by the name of the tag, followed by @samp{:}.
1763
If the name contains @samp{::} between a @samp{<} and @samp{>} pair (for
1764
C++ templates), such a @samp{::} does not end the name---only a single
1765
@samp{:} ends the name; see @ref{Nested Symbols}.
1766
 
1767
For example, the following C declarations:
1768
 
1769
@example
1770
struct foo;
1771
struct foo *bar;
1772
@end example
1773
 
1774
@noindent
1775
produce:
1776
 
1777
@example
1778
.stabs "bar:G16=*17=xsfoo:",32,0,0,0
1779
@end example
1780
 
1781
Not all debuggers support the @samp{x} type descriptor, so on some
1782
machines GCC does not use it.  I believe that for the above example it
1783
would just emit a reference to type 17 and never define it, but I
1784
haven't verified that.
1785
 
1786
Modula-2 imported types, at least on AIX, use the @samp{i} type
1787
descriptor, which is followed by the name of the module from which the
1788
type is imported, followed by @samp{:}, followed by the name of the
1789
type.  There is then optionally a comma followed by type information for
1790
the type.  This differs from merely naming the type (@pxref{Typedefs}) in
1791
that it identifies the module; I don't understand whether the name of
1792
the type given here is always just the same as the name we are giving
1793
it, or whether this type descriptor is used with a nameless stab
1794
(@pxref{String Field}), or what.  The symbol ends with @samp{;}.
1795
 
1796
@node Subranges
1797
@section Subrange Types
1798
 
1799
The @samp{r} type descriptor defines a type as a subrange of another
1800
type.  It is followed by type information for the type of which it is a
1801
subrange, a semicolon, an integral lower bound, a semicolon, an
1802
integral upper bound, and a semicolon.  The AIX documentation does not
1803
specify the trailing semicolon, in an effort to specify array indexes
1804
more cleanly, but a subrange which is not an array index has always
1805
included a trailing semicolon (@pxref{Arrays}).
1806
 
1807
Instead of an integer, either bound can be one of the following:
1808
 
1809
@table @code
1810
@item A @var{offset}
1811
The bound is passed by reference on the stack at offset @var{offset}
1812
from the argument list.  @xref{Parameters}, for more information on such
1813
offsets.
1814
 
1815
@item T @var{offset}
1816
The bound is passed by value on the stack at offset @var{offset} from
1817
the argument list.
1818
 
1819
@item a @var{register-number}
1820
The bound is pased by reference in register number
1821
@var{register-number}.
1822
 
1823
@item t @var{register-number}
1824
The bound is passed by value in register number @var{register-number}.
1825
 
1826
@item J
1827
There is no bound.
1828
@end table
1829
 
1830
Subranges are also used for builtin types; see @ref{Traditional Builtin Types}.
1831
 
1832
@node Arrays
1833
@section Array Types
1834
 
1835
Arrays use the @samp{a} type descriptor.  Following the type descriptor
1836
is the type of the index and the type of the array elements.  If the
1837
index type is a range type, it ends in a semicolon; otherwise
1838
(for example, if it is a type reference), there does not
1839
appear to be any way to tell where the types are separated.  In an
1840
effort to clean up this mess, IBM documents the two types as being
1841
separated by a semicolon, and a range type as not ending in a semicolon
1842
(but this is not right for range types which are not array indexes,
1843
@pxref{Subranges}).  I think probably the best solution is to specify
1844
that a semicolon ends a range type, and that the index type and element
1845
type of an array are separated by a semicolon, but that if the index
1846
type is a range type, the extra semicolon can be omitted.  GDB (at least
1847
through version 4.9) doesn't support any kind of index type other than a
1848
range anyway; I'm not sure about dbx.
1849
 
1850
It is well established, and widely used, that the type of the index,
1851
unlike most types found in the stabs, is merely a type definition, not
1852
type information (@pxref{String Field}) (that is, it need not start with
1853
@samp{@var{type-number}=} if it is defining a new type).  According to a
1854
comment in GDB, this is also true of the type of the array elements; it
1855
gives @samp{ar1;1;10;ar1;1;10;4} as a legitimate way to express a two
1856
dimensional array.  According to AIX documentation, the element type
1857
must be type information.  GDB accepts either.
1858
 
1859
The type of the index is often a range type, expressed as the type
1860
descriptor @samp{r} and some parameters.  It defines the size of the
1861
array.  In the example below, the range @samp{r1;0;2;} defines an index
1862
type which is a subrange of type 1 (integer), with a lower bound of 0
1863
and an upper bound of 2.  This defines the valid range of subscripts of
1864
a three-element C array.
1865
 
1866
For example, the definition:
1867
 
1868
@example
1869
char char_vec[3] = @{'a','b','c'@};
1870
@end example
1871
 
1872
@noindent
1873
produces the output:
1874
 
1875
@example
1876
.stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
1877
     .global _char_vec
1878
     .align 4
1879
_char_vec:
1880
     .byte 97
1881
     .byte 98
1882
     .byte 99
1883
@end example
1884
 
1885
If an array is @dfn{packed}, the elements are spaced more
1886
closely than normal, saving memory at the expense of speed.  For
1887
example, an array of 3-byte objects might, if unpacked, have each
1888
element aligned on a 4-byte boundary, but if packed, have no padding.
1889
One way to specify that something is packed is with type attributes
1890
(@pxref{String Field}).  In the case of arrays, another is to use the
1891
@samp{P} type descriptor instead of @samp{a}.  Other than specifying a
1892
packed array, @samp{P} is identical to @samp{a}.
1893
 
1894
@c FIXME-what is it?  A pointer?
1895
An open array is represented by the @samp{A} type descriptor followed by
1896
type information specifying the type of the array elements.
1897
 
1898
@c FIXME: what is the format of this type?  A pointer to a vector of pointers?
1899
An N-dimensional dynamic array is represented by
1900
 
1901
@example
1902
D @var{dimensions} ; @var{type-information}
1903
@end example
1904
 
1905
@c Does dimensions really have this meaning?  The AIX documentation
1906
@c doesn't say.
1907
@var{dimensions} is the number of dimensions; @var{type-information}
1908
specifies the type of the array elements.
1909
 
1910
@c FIXME: what is the format of this type?  A pointer to some offsets in
1911
@c another array?
1912
A subarray of an N-dimensional array is represented by
1913
 
1914
@example
1915
E @var{dimensions} ; @var{type-information}
1916
@end example
1917
 
1918
@c Does dimensions really have this meaning?  The AIX documentation
1919
@c doesn't say.
1920
@var{dimensions} is the number of dimensions; @var{type-information}
1921
specifies the type of the array elements.
1922
 
1923
@node Strings
1924
@section Strings
1925
 
1926
Some languages, like C or the original Pascal, do not have string types,
1927
they just have related things like arrays of characters.  But most
1928
Pascals and various other languages have string types, which are
1929
indicated as follows:
1930
 
1931
@table @code
1932
@item n @var{type-information} ; @var{bytes}
1933
@var{bytes} is the maximum length.  I'm not sure what
1934
@var{type-information} is; I suspect that it means that this is a string
1935
of @var{type-information} (thus allowing a string of integers, a string
1936
of wide characters, etc., as well as a string of characters).  Not sure
1937
what the format of this type is.  This is an AIX feature.
1938
 
1939
@item z @var{type-information} ; @var{bytes}
1940
Just like @samp{n} except that this is a gstring, not an ordinary
1941
string.  I don't know the difference.
1942
 
1943
@item N
1944
Pascal Stringptr.  What is this?  This is an AIX feature.
1945
@end table
1946
 
1947
Languages, such as CHILL which have a string type which is basically
1948
just an array of characters use the @samp{S} type attribute
1949
(@pxref{String Field}).
1950
 
1951
@node Enumerations
1952
@section Enumerations
1953
 
1954
Enumerations are defined with the @samp{e} type descriptor.
1955
 
1956
@c FIXME: Where does this information properly go?  Perhaps it is
1957
@c redundant with something we already explain.
1958
The source line below declares an enumeration type at file scope.
1959
The type definition is located after the @code{N_RBRAC} that marks the end of
1960
the previous procedure's block scope, and before the @code{N_FUN} that marks
1961
the beginning of the next procedure's block scope.  Therefore it does not
1962
describe a block local symbol, but a file local one.
1963
 
1964
The source line:
1965
 
1966
@example
1967
enum e_places @{first,second=3,last@};
1968
@end example
1969
 
1970
@noindent
1971
generates the following stab:
1972
 
1973
@example
1974
.stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
1975
@end example
1976
 
1977
The symbol descriptor (@samp{T}) says that the stab describes a
1978
structure, enumeration, or union tag.  The type descriptor @samp{e},
1979
following the @samp{22=} of the type definition narrows it down to an
1980
enumeration type.  Following the @samp{e} is a list of the elements of
1981
the enumeration.  The format is @samp{@var{name}:@var{value},}.  The
1982
list of elements ends with @samp{;}.  The fact that @var{value} is
1983
specified as an integer can cause problems if the value is large.  GCC
1984
2.5.2 tries to output it in octal in that case with a leading zero,
1985
which is probably a good thing, although GDB 4.11 supports octal only in
1986
cases where decimal is perfectly good.  Negative decimal values are
1987
supported by both GDB and dbx.
1988
 
1989
There is no standard way to specify the size of an enumeration type; it
1990
is determined by the architecture (normally all enumerations types are
1991
32 bits).  Type attributes can be used to specify an enumeration type of
1992
another size for debuggers which support them; see @ref{String Field}.
1993
 
1994
Enumeration types are unusual in that they define symbols for the
1995
enumeration values (@code{first}, @code{second}, and @code{third} in the
1996
above example), and even though these symbols are visible in the file as
1997
a whole (rather than being in a more local namespace like structure
1998
member names), they are defined in the type definition for the
1999
enumeration type rather than each having their own symbol.  In order to
2000
be fast, GDB will only get symbols from such types (in its initial scan
2001
of the stabs) if the type is the first thing defined after a @samp{T} or
2002
@samp{t} symbol descriptor (the above example fulfills this
2003
requirement).  If the type does not have a name, the compiler should
2004
emit it in a nameless stab (@pxref{String Field}); GCC does this.
2005
 
2006
@node Structures
2007
@section Structures
2008
 
2009
The encoding of structures in stabs can be shown with an example.
2010
 
2011
The following source code declares a structure tag and defines an
2012
instance of the structure in global scope. Then a @code{typedef} equates the
2013
structure tag with a new type.  Seperate stabs are generated for the
2014
structure tag, the structure @code{typedef}, and the structure instance.  The
2015
stabs for the tag and the @code{typedef} are emited when the definitions are
2016
encountered.  Since the structure elements are not initialized, the
2017
stab and code for the structure variable itself is located at the end
2018
of the program in the bss section.
2019
 
2020
@example
2021
struct s_tag @{
2022
  int   s_int;
2023
  float s_float;
2024
  char  s_char_vec[8];
2025
  struct s_tag* s_next;
2026
@} g_an_s;
2027
 
2028
typedef struct s_tag s_typedef;
2029
@end example
2030
 
2031
The structure tag has an @code{N_LSYM} stab type because, like the
2032
enumeration, the symbol has file scope.  Like the enumeration, the
2033
symbol descriptor is @samp{T}, for enumeration, structure, or tag type.
2034
The type descriptor @samp{s} following the @samp{16=} of the type
2035
definition narrows the symbol type to structure.
2036
 
2037
Following the @samp{s} type descriptor is the number of bytes the
2038
structure occupies, followed by a description of each structure element.
2039
The structure element descriptions are of the form @var{name:type, bit
2040
offset from the start of the struct, number of bits in the element}.
2041
 
2042
@c FIXME: phony line break.  Can probably be fixed by using an example
2043
@c with fewer fields.
2044
@example
2045
# @r{128 is N_LSYM}
2046
.stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;
2047
        s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
2048
@end example
2049
 
2050
In this example, the first two structure elements are previously defined
2051
types.  For these, the type following the @samp{@var{name}:} part of the
2052
element description is a simple type reference.  The other two structure
2053
elements are new types.  In this case there is a type definition
2054
embedded after the @samp{@var{name}:}.  The type definition for the
2055
array element looks just like a type definition for a standalone array.
2056
The @code{s_next} field is a pointer to the same kind of structure that
2057
the field is an element of.  So the definition of structure type 16
2058
contains a type definition for an element which is a pointer to type 16.
2059
 
2060
If a field is a static member (this is a C++ feature in which a single
2061
variable appears to be a field of every structure of a given type) it
2062
still starts out with the field name, a colon, and the type, but then
2063
instead of a comma, bit position, comma, and bit size, there is a colon
2064
followed by the name of the variable which each such field refers to.
2065
 
2066
If the structure has methods (a C++ feature), they follow the non-method
2067
fields; see @ref{Cplusplus}.
2068
 
2069
@node Typedefs
2070
@section Giving a Type a Name
2071
 
2072
@findex N_LSYM, for types
2073
@findex C_DECL, for types
2074
To give a type a name, use the @samp{t} symbol descriptor.  The type
2075
is specified by the type information (@pxref{String Field}) for the stab.
2076
For example,
2077
 
2078
@example
2079
.stabs "s_typedef:t16",128,0,0,0     # @r{128 is N_LSYM}
2080
@end example
2081
 
2082
specifies that @code{s_typedef} refers to type number 16.  Such stabs
2083
have symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF).  (The Sun
2084
documentation mentions using @code{N_GSYM} in some cases).
2085
 
2086
If you are specifying the tag name for a structure, union, or
2087
enumeration, use the @samp{T} symbol descriptor instead.  I believe C is
2088
the only language with this feature.
2089
 
2090
If the type is an opaque type (I believe this is a Modula-2 feature),
2091
AIX provides a type descriptor to specify it.  The type descriptor is
2092
@samp{o} and is followed by a name.  I don't know what the name
2093
means---is it always the same as the name of the type, or is this type
2094
descriptor used with a nameless stab (@pxref{String Field})?  There
2095
optionally follows a comma followed by type information which defines
2096
the type of this type.  If omitted, a semicolon is used in place of the
2097
comma and the type information, and the type is much like a generic
2098
pointer type---it has a known size but little else about it is
2099
specified.
2100
 
2101
@node Unions
2102
@section Unions
2103
 
2104
@example
2105
union u_tag @{
2106
  int  u_int;
2107
  float u_float;
2108
  char* u_char;
2109
@} an_u;
2110
@end example
2111
 
2112
This code generates a stab for a union tag and a stab for a union
2113
variable.  Both use the @code{N_LSYM} stab type.  If a union variable is
2114
scoped locally to the procedure in which it is defined, its stab is
2115
located immediately preceding the @code{N_LBRAC} for the procedure's block
2116
start.
2117
 
2118
The stab for the union tag, however, is located preceding the code for
2119
the procedure in which it is defined.  The stab type is @code{N_LSYM}.  This
2120
would seem to imply that the union type is file scope, like the struct
2121
type @code{s_tag}.  This is not true.  The contents and position of the stab
2122
for @code{u_type} do not convey any infomation about its procedure local
2123
scope.
2124
 
2125
@c FIXME: phony line break.  Can probably be fixed by using an example
2126
@c with fewer fields.
2127
@smallexample
2128
# @r{128 is N_LSYM}
2129
.stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
2130
       128,0,0,0
2131
@end smallexample
2132
 
2133
The symbol descriptor @samp{T}, following the @samp{name:} means that
2134
the stab describes an enumeration, structure, or union tag.  The type
2135
descriptor @samp{u}, following the @samp{23=} of the type definition,
2136
narrows it down to a union type definition.  Following the @samp{u} is
2137
the number of bytes in the union.  After that is a list of union element
2138
descriptions.  Their format is @var{name:type, bit offset into the
2139
union, number of bytes for the element;}.
2140
 
2141
The stab for the union variable is:
2142
 
2143
@example
2144
.stabs "an_u:23",128,0,0,-20     # @r{128 is N_LSYM}
2145
@end example
2146
 
2147
@samp{-20} specifies where the variable is stored (@pxref{Stack
2148
Variables}).
2149
 
2150
@node Function Types
2151
@section Function Types
2152
 
2153
Various types can be defined for function variables.  These types are
2154
not used in defining functions (@pxref{Procedures}); they are used for
2155
things like pointers to functions.
2156
 
2157
The simple, traditional, type is type descriptor @samp{f} is followed by
2158
type information for the return type of the function, followed by a
2159
semicolon.
2160
 
2161
This does not deal with functions for which the number and types of the
2162
parameters are part of the type, as in Modula-2 or ANSI C.  AIX provides
2163
extensions to specify these, using the @samp{f}, @samp{F}, @samp{p}, and
2164
@samp{R} type descriptors.
2165
 
2166
First comes the type descriptor.  If it is @samp{f} or @samp{F}, this
2167
type involves a function rather than a procedure, and the type
2168
information for the return type of the function follows, followed by a
2169
comma.  Then comes the number of parameters to the function and a
2170
semicolon.  Then, for each parameter, there is the name of the parameter
2171
followed by a colon (this is only present for type descriptors @samp{R}
2172
and @samp{F} which represent Pascal function or procedure parameters),
2173
type information for the parameter, a comma, 0 if passed by reference or
2174
1 if passed by value, and a semicolon.  The type definition ends with a
2175
semicolon.
2176
 
2177
For example, this variable definition:
2178
 
2179
@example
2180
int (*g_pf)();
2181
@end example
2182
 
2183
@noindent
2184
generates the following code:
2185
 
2186
@example
2187
.stabs "g_pf:G24=*25=f1",32,0,0,0
2188
    .common _g_pf,4,"bss"
2189
@end example
2190
 
2191
The variable defines a new type, 24, which is a pointer to another new
2192
type, 25, which is a function returning @code{int}.
2193
 
2194
@node Symbol Tables
2195
@chapter Symbol Information in Symbol Tables
2196
 
2197
This chapter describes the format of symbol table entries
2198
and how stab assembler directives map to them.  It also describes the
2199
transformations that the assembler and linker make on data from stabs.
2200
 
2201
@menu
2202
* Symbol Table Format::
2203
* Transformations On Symbol Tables::
2204
@end menu
2205
 
2206
@node Symbol Table Format
2207
@section Symbol Table Format
2208
 
2209
Each time the assembler encounters a stab directive, it puts
2210
each field of the stab into a corresponding field in a symbol table
2211
entry of its output file.  If the stab contains a string field, the
2212
symbol table entry for that stab points to a string table entry
2213
containing the string data from the stab.  Assembler labels become
2214
relocatable addresses.  Symbol table entries in a.out have the format:
2215
 
2216
@c FIXME: should refer to external, not internal.
2217
@example
2218
struct internal_nlist @{
2219
  unsigned long n_strx;         /* index into string table of name */
2220
  unsigned char n_type;         /* type of symbol */
2221
  unsigned char n_other;        /* misc info (usually empty) */
2222
  unsigned short n_desc;        /* description field */
2223
  bfd_vma n_value;              /* value of symbol */
2224
@};
2225
@end example
2226
 
2227
If the stab has a string, the @code{n_strx} field holds the offset in
2228
bytes of the string within the string table.  The string is terminated
2229
by a NUL character.  If the stab lacks a string (for example, it was
2230
produced by a @code{.stabn} or @code{.stabd} directive), the
2231
@code{n_strx} field is zero.
2232
 
2233
Symbol table entries with @code{n_type} field values greater than 0x1f
2234
originated as stabs generated by the compiler (with one random
2235
exception).  The other entries were placed in the symbol table of the
2236
executable by the assembler or the linker.
2237
 
2238
@node Transformations On Symbol Tables
2239
@section Transformations on Symbol Tables
2240
 
2241
The linker concatenates object files and does fixups of externally
2242
defined symbols.
2243
 
2244
You can see the transformations made on stab data by the assembler and
2245
linker by examining the symbol table after each pass of the build.  To
2246
do this, use @samp{nm -ap}, which dumps the symbol table, including
2247
debugging information, unsorted.  For stab entries the columns are:
2248
@var{value}, @var{other}, @var{desc}, @var{type}, @var{string}.  For
2249
assembler and linker symbols, the columns are: @var{value}, @var{type},
2250
@var{string}.
2251
 
2252
The low 5 bits of the stab type tell the linker how to relocate the
2253
value of the stab.  Thus for stab types like @code{N_RSYM} and
2254
@code{N_LSYM}, where the value is an offset or a register number, the
2255
low 5 bits are @code{N_ABS}, which tells the linker not to relocate the
2256
value.
2257
 
2258
Where the value of a stab contains an assembly language label,
2259
it is transformed by each build step.  The assembler turns it into a
2260
relocatable address and the linker turns it into an absolute address.
2261
 
2262
@menu
2263
* Transformations On Static Variables::
2264
* Transformations On Global Variables::
2265
* Stab Section Transformations::           For some object file formats,
2266
                                           things are a bit different.
2267
@end menu
2268
 
2269
@node Transformations On Static Variables
2270
@subsection Transformations on Static Variables
2271
 
2272
This source line defines a static variable at file scope:
2273
 
2274
@example
2275
static int s_g_repeat
2276
@end example
2277
 
2278
@noindent
2279
The following stab describes the symbol:
2280
 
2281
@example
2282
.stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
2283
@end example
2284
 
2285
@noindent
2286
The assembler transforms the stab into this symbol table entry in the
2287
@file{.o} file.  The location is expressed as a data segment offset.
2288
 
2289
@example
2290
00000084 - 00 0000 STSYM s_g_repeat:S1
2291
@end example
2292
 
2293
@noindent
2294
In the symbol table entry from the executable, the linker has made the
2295
relocatable address absolute.
2296
 
2297
@example
2298
0000e00c - 00 0000 STSYM s_g_repeat:S1
2299
@end example
2300
 
2301
@node Transformations On Global Variables
2302
@subsection Transformations on Global Variables
2303
 
2304
Stabs for global variables do not contain location information. In
2305
this case, the debugger finds location information in the assembler or
2306
linker symbol table entry describing the variable.  The source line:
2307
 
2308
@example
2309
char g_foo = 'c';
2310
@end example
2311
 
2312
@noindent
2313
generates the stab:
2314
 
2315
@example
2316
.stabs "g_foo:G2",32,0,0,0
2317
@end example
2318
 
2319
The variable is represented by two symbol table entries in the object
2320
file (see below).  The first one originated as a stab.  The second one
2321
is an external symbol.  The upper case @samp{D} signifies that the
2322
@code{n_type} field of the symbol table contains 7, @code{N_DATA} with
2323
local linkage.  The stab's value is zero since the value is not used for
2324
@code{N_GSYM} stabs.  The value of the linker symbol is the relocatable
2325
address corresponding to the variable.
2326
 
2327
@example
2328
00000000 - 00 0000  GSYM g_foo:G2
2329
00000080 D _g_foo
2330
@end example
2331
 
2332
@noindent
2333
These entries as transformed by the linker.  The linker symbol table
2334
entry now holds an absolute address:
2335
 
2336
@example
2337
00000000 - 00 0000  GSYM g_foo:G2
2338
@dots{}
2339
0000e008 D _g_foo
2340
@end example
2341
 
2342
@node Stab Section Transformations
2343
@subsection Transformations of Stabs in separate sections
2344
 
2345
For object file formats using stabs in separate sections (@pxref{Stab
2346
Sections}), use @code{objdump --stabs} instead of @code{nm} to show the
2347
stabs in an object or executable file.  @code{objdump} is a GNU utility;
2348
Sun does not provide any equivalent.
2349
 
2350
The following example is for a stab whose value is an address is
2351
relative to the compilation unit (@pxref{ELF Linker Relocation}).  For
2352
example, if the source line
2353
 
2354
@example
2355
static int ld = 5;
2356
@end example
2357
 
2358
appears within a function, then the assembly language output from the
2359
compiler contains:
2360
 
2361
@example
2362
.Ddata.data:
2363
@dots{}
2364
        .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data    # @r{0x26 is N_STSYM}
2365
@dots{}
2366
.L18:
2367
        .align 4
2368
        .word 0x5
2369
@end example
2370
 
2371
Because the value is formed by subtracting one symbol from another, the
2372
value is absolute, not relocatable, and so the object file contains
2373
 
2374
@example
2375
Symnum n_type n_othr n_desc n_value  n_strx String
2376
31     STSYM  0      4      00000004 680    ld:V(0,3)
2377
@end example
2378
 
2379
without any relocations, and the executable file also contains
2380
 
2381
@example
2382
Symnum n_type n_othr n_desc n_value  n_strx String
2383
31     STSYM  0      4      00000004 680    ld:V(0,3)
2384
@end example
2385
 
2386
@node Cplusplus
2387
@chapter GNU C++ Stabs
2388
 
2389
@menu
2390
* Class Names::                 C++ class names are both tags and typedefs.
2391
* Nested Symbols::              C++ symbol names can be within other types.
2392
* Basic Cplusplus Types::
2393
* Simple Classes::
2394
* Class Instance::
2395
* Methods::                     Method definition
2396
* Method Type Descriptor::      The @samp{#} type descriptor
2397
* Member Type Descriptor::      The @samp{@@} type descriptor
2398
* Protections::
2399
* Method Modifiers::
2400
* Virtual Methods::
2401
* Inheritence::
2402
* Virtual Base Classes::
2403
* Static Members::
2404
@end menu
2405
 
2406
@node Class Names
2407
@section C++ Class Names
2408
 
2409
In C++, a class name which is declared with @code{class}, @code{struct},
2410
or @code{union}, is not only a tag, as in C, but also a type name.  Thus
2411
there should be stabs with both @samp{t} and @samp{T} symbol descriptors
2412
(@pxref{Typedefs}).
2413
 
2414
To save space, there is a special abbreviation for this case.  If the
2415
@samp{T} symbol descriptor is followed by @samp{t}, then the stab
2416
defines both a type name and a tag.
2417
 
2418
For example, the C++ code
2419
 
2420
@example
2421
struct foo @{int x;@};
2422
@end example
2423
 
2424
can be represented as either
2425
 
2426
@example
2427
.stabs "foo:T19=s4x:1,0,32;;",128,0,0,0       # @r{128 is N_LSYM}
2428
.stabs "foo:t19",128,0,0,0
2429
@end example
2430
 
2431
or
2432
 
2433
@example
2434
.stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0
2435
@end example
2436
 
2437
@node Nested Symbols
2438
@section Defining a Symbol Within Another Type
2439
 
2440
In C++, a symbol (such as a type name) can be defined within another type.
2441
@c FIXME: Needs example.
2442
 
2443
In stabs, this is sometimes represented by making the name of a symbol
2444
which contains @samp{::}.  Such a pair of colons does not end the name
2445
of the symbol, the way a single colon would (@pxref{String Field}).  I'm
2446
not sure how consistently used or well thought out this mechanism is.
2447
So that a pair of colons in this position always has this meaning,
2448
@samp{:} cannot be used as a symbol descriptor.
2449
 
2450
For example, if the string for a stab is @samp{foo::bar::baz:t5=*6},
2451
then @code{foo::bar::baz} is the name of the symbol, @samp{t} is the
2452
symbol descriptor, and @samp{5=*6} is the type information.
2453
 
2454
@node Basic Cplusplus Types
2455
@section Basic Types For C++
2456
 
2457
<< the examples that follow are based on a01.C >>
2458
 
2459
 
2460
C++ adds two more builtin types to the set defined for C.  These are
2461
the unknown type and the vtable record type.  The unknown type, type
2462
16, is defined in terms of itself like the void type.
2463
 
2464
The vtable record type, type 17, is defined as a structure type and
2465
then as a structure tag.  The structure has four fields: delta, index,
2466
pfn, and delta2.  pfn is the function pointer.
2467
 
2468
<< In boilerplate $vtbl_ptr_type, what are the fields delta,
2469
index, and delta2 used for? >>
2470
 
2471
This basic type is present in all C++ programs even if there are no
2472
virtual methods defined.
2473
 
2474
@display
2475
.stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8)
2476
        elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16);
2477
        elem_name(index):type_ref(short int),bit_offset(16),field_bits(16);
2478
        elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void),
2479
                                    bit_offset(32),field_bits(32);
2480
        elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;"
2481
        N_LSYM, NIL, NIL
2482
@end display
2483
 
2484
@smallexample
2485
.stabs "$vtbl_ptr_type:t17=s8
2486
        delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;"
2487
        ,128,0,0,0
2488
@end smallexample
2489
 
2490
@display
2491
.stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL
2492
@end display
2493
 
2494
@example
2495
.stabs "$vtbl_ptr_type:T17",128,0,0,0
2496
@end example
2497
 
2498
@node Simple Classes
2499
@section Simple Class Definition
2500
 
2501
The stabs describing C++ language features are an extension of the
2502
stabs describing C.  Stabs representing C++ class types elaborate
2503
extensively on the stab format used to describe structure types in C.
2504
Stabs representing class type variables look just like stabs
2505
representing C language variables.
2506
 
2507
Consider the following very simple class definition.
2508
 
2509
@example
2510
class baseA @{
2511
public:
2512
        int Adat;
2513
        int Ameth(int in, char other);
2514
@};
2515
@end example
2516
 
2517
The class @code{baseA} is represented by two stabs.  The first stab describes
2518
the class as a structure type.  The second stab describes a structure
2519
tag of the class type.  Both stabs are of stab type @code{N_LSYM}.  Since the
2520
stab is not located between an @code{N_FUN} and an @code{N_LBRAC} stab this indicates
2521
that the class is defined at file scope.  If it were, then the @code{N_LSYM}
2522
would signify a local variable.
2523
 
2524
A stab describing a C++ class type is similar in format to a stab
2525
describing a C struct, with each class member shown as a field in the
2526
structure.  The part of the struct format describing fields is
2527
expanded to include extra information relevent to C++ class members.
2528
In addition, if the class has multiple base classes or virtual
2529
functions the struct format outside of the field parts is also
2530
augmented.
2531
 
2532
In this simple example the field part of the C++ class stab
2533
representing member data looks just like the field part of a C struct
2534
stab.  The section on protections describes how its format is
2535
sometimes extended for member data.
2536
 
2537
The field part of a C++ class stab representing a member function
2538
differs substantially from the field part of a C struct stab.  It
2539
still begins with @samp{name:} but then goes on to define a new type number
2540
for the member function, describe its return type, its argument types,
2541
its protection level, any qualifiers applied to the method definition,
2542
and whether the method is virtual or not.  If the method is virtual
2543
then the method description goes on to give the vtable index of the
2544
method, and the type number of the first base class defining the
2545
method.
2546
 
2547
When the field name is a method name it is followed by two colons rather
2548
than one.  This is followed by a new type definition for the method.
2549
This is a number followed by an equal sign and the type of the method.
2550
Normally this will be a type declared using the @samp{#} type
2551
descriptor; see @ref{Method Type Descriptor}; static member functions
2552
are declared using the @samp{f} type descriptor instead; see
2553
@ref{Function Types}.
2554
 
2555
The format of an overloaded operator method name differs from that of
2556
other methods.  It is @samp{op$::@var{operator-name}.} where
2557
@var{operator-name} is the operator name such as @samp{+} or @samp{+=}.
2558
The name ends with a period, and any characters except the period can
2559
occur in the @var{operator-name} string.
2560
 
2561
The next part of the method description represents the arguments to the
2562
method, preceeded by a colon and ending with a semi-colon.  The types of
2563
the arguments are expressed in the same way argument types are expressed
2564
in C++ name mangling.  In this example an @code{int} and a @code{char}
2565
map to @samp{ic}.
2566
 
2567
This is followed by a number, a letter, and an asterisk or period,
2568
followed by another semicolon.  The number indicates the protections
2569
that apply to the member function.  Here the 2 means public.  The
2570
letter encodes any qualifier applied to the method definition.  In
2571
this case, @samp{A} means that it is a normal function definition.  The dot
2572
shows that the method is not virtual.  The sections that follow
2573
elaborate further on these fields and describe the additional
2574
information present for virtual methods.
2575
 
2576
 
2577
@display
2578
.stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4)
2579
        field_name(Adat):type(int),bit_offset(0),field_bits(32);
2580
 
2581
        method_name(Ameth)::type_def(21)=type_desc(method)return_type(int);
2582
        :arg_types(int char);
2583
        protection(public)qualifier(normal)virtual(no);;"
2584
        N_LSYM,NIL,NIL,NIL
2585
@end display
2586
 
2587
@smallexample
2588
.stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0
2589
 
2590
.stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL
2591
 
2592
.stabs "baseA:T20",128,0,0,0
2593
@end smallexample
2594
 
2595
@node Class Instance
2596
@section Class Instance
2597
 
2598
As shown above, describing even a simple C++ class definition is
2599
accomplished by massively extending the stab format used in C to
2600
describe structure types.  However, once the class is defined, C stabs
2601
with no modifications can be used to describe class instances.  The
2602
following source:
2603
 
2604
@example
2605
main () @{
2606
        baseA AbaseA;
2607
@}
2608
@end example
2609
 
2610
@noindent
2611
yields the following stab describing the class instance.  It looks no
2612
different from a standard C stab describing a local variable.
2613
 
2614
@display
2615
.stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset
2616
@end display
2617
 
2618
@example
2619
.stabs "AbaseA:20",128,0,0,-20
2620
@end example
2621
 
2622
@node Methods
2623
@section Method Definition
2624
 
2625
The class definition shown above declares Ameth.  The C++ source below
2626
defines Ameth:
2627
 
2628
@example
2629
int
2630
baseA::Ameth(int in, char other)
2631
@{
2632
        return in;
2633
@};
2634
@end example
2635
 
2636
 
2637
This method definition yields three stabs following the code of the
2638
method.  One stab describes the method itself and following two describe
2639
its parameters.  Although there is only one formal argument all methods
2640
have an implicit argument which is the @code{this} pointer.  The @code{this}
2641
pointer is a pointer to the object on which the method was called.  Note
2642
that the method name is mangled to encode the class name and argument
2643
types.  Name mangling is described in the @sc{arm} (@cite{The Annotated
2644
C++ Reference Manual}, by Ellis and Stroustrup, @sc{isbn}
2645
0-201-51459-1); @file{gpcompare.texi} in Cygnus GCC distributions
2646
describes the differences between GNU mangling and @sc{arm}
2647
mangling.
2648
@c FIXME: Use @xref, especially if this is generally installed in the
2649
@c info tree.
2650
@c FIXME: This information should be in a net release, either of GCC or
2651
@c GDB.  But gpcompare.texi doesn't seem to be in the FSF GCC.
2652
 
2653
@example
2654
.stabs "name:symbol_desriptor(global function)return_type(int)",
2655
        N_FUN, NIL, NIL, code_addr_of_method_start
2656
 
2657
.stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic
2658
@end example
2659
 
2660
Here is the stab for the @code{this} pointer implicit argument.  The
2661
name of the @code{this} pointer is always @code{this}.  Type 19, the
2662
@code{this} pointer is defined as a pointer to type 20, @code{baseA},
2663
but a stab defining @code{baseA} has not yet been emited.  Since the
2664
compiler knows it will be emited shortly, here it just outputs a cross
2665
reference to the undefined symbol, by prefixing the symbol name with
2666
@samp{xs}.
2667
 
2668
@example
2669
.stabs "name:sym_desc(register param)type_def(19)=
2670
        type_desc(ptr to)type_ref(baseA)=
2671
        type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number
2672
 
2673
.stabs "this:P19=*20=xsbaseA:",64,0,0,8
2674
@end example
2675
 
2676
The stab for the explicit integer argument looks just like a parameter
2677
to a C function.  The last field of the stab is the offset from the
2678
argument pointer, which in most systems is the same as the frame
2679
pointer.
2680
 
2681
@example
2682
.stabs "name:sym_desc(value parameter)type_ref(int)",
2683
        N_PSYM,NIL,NIL,offset_from_arg_ptr
2684
 
2685
.stabs "in:p1",160,0,0,72
2686
@end example
2687
 
2688
<< The examples that follow are based on A1.C >>
2689
 
2690
@node Method Type Descriptor
2691
@section The @samp{#} Type Descriptor
2692
 
2693
This is used to describe a class method.  This is a function which takes
2694
an extra argument as its first argument, for the @code{this} pointer.
2695
 
2696
If the @samp{#} is immediately followed by another @samp{#}, the second
2697
one will be followed by the return type and a semicolon.  The class and
2698
argument types are not specified, and must be determined by demangling
2699
the name of the method if it is available.
2700
 
2701
Otherwise, the single @samp{#} is followed by the class type, a comma,
2702
the return type, a comma, and zero or more parameter types separated by
2703
commas.  The list of arguments is terminated by a semicolon.  In the
2704
debugging output generated by gcc, a final argument type of @code{void}
2705
indicates a method which does not take a variable number of arguments.
2706
If the final argument type of @code{void} does not appear, the method
2707
was declared with an ellipsis.
2708
 
2709
Note that although such a type will normally be used to describe fields
2710
in structures, unions, or classes, for at least some versions of the
2711
compiler it can also be used in other contexts.
2712
 
2713
@node Member Type Descriptor
2714
@section The @samp{@@} Type Descriptor
2715
 
2716
The @samp{@@} type descriptor is for a member (class and variable) type.
2717
It is followed by type information for the offset basetype, a comma, and
2718
type information for the type of the field being pointed to.  (FIXME:
2719
this is acknowledged to be gibberish.  Can anyone say what really goes
2720
here?).
2721
 
2722
Note that there is a conflict between this and type attributes
2723
(@pxref{String Field}); both use type descriptor @samp{@@}.
2724
Fortunately, the @samp{@@} type descriptor used in this C++ sense always
2725
will be followed by a digit, @samp{(}, or @samp{-}, and type attributes
2726
never start with those things.
2727
 
2728
@node Protections
2729
@section Protections
2730
 
2731
In the simple class definition shown above all member data and
2732
functions were publicly accessable.  The example that follows
2733
contrasts public, protected and privately accessable fields and shows
2734
how these protections are encoded in C++ stabs.
2735
 
2736
If the character following the @samp{@var{field-name}:} part of the
2737
string is @samp{/}, then the next character is the visibility.  @samp{0}
2738
means private, @samp{1} means protected, and @samp{2} means public.
2739
Debuggers should ignore visibility characters they do not recognize, and
2740
assume a reasonable default (such as public) (GDB 4.11 does not, but
2741
this should be fixed in the next GDB release).  If no visibility is
2742
specified the field is public.  The visibility @samp{9} means that the
2743
field has been optimized out and is public (there is no way to specify
2744
an optimized out field with a private or protected visibility).
2745
Visibility @samp{9} is not supported by GDB 4.11; this should be fixed
2746
in the next GDB release.
2747
 
2748
The following C++ source:
2749
 
2750
@example
2751
class vis @{
2752
private:
2753
        int   priv;
2754
protected:
2755
        char  prot;
2756
public:
2757
        float pub;
2758
@};
2759
@end example
2760
 
2761
@noindent
2762
generates the following stab:
2763
 
2764
@example
2765
# @r{128 is N_LSYM}
2766
.stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0
2767
@end example
2768
 
2769
@samp{vis:T19=s12} indicates that type number 19 is a 12 byte structure
2770
named @code{vis} The @code{priv} field has public visibility
2771
(@samp{/0}), type int (@samp{1}), and offset and size @samp{,0,32;}.
2772
The @code{prot} field has protected visibility (@samp{/1}), type char
2773
(@samp{2}) and offset and size @samp{,32,8;}.  The @code{pub} field has
2774
type float (@samp{12}), and offset and size @samp{,64,32;}.
2775
 
2776
Protections for member functions are signified by one digit embeded in
2777
the field part of the stab describing the method.  The digit is 0 if
2778
private, 1 if protected and 2 if public.  Consider the C++ class
2779
definition below:
2780
 
2781
@example
2782
class all_methods @{
2783
private:
2784
        int   priv_meth(int in)@{return in;@};
2785
protected:
2786
        char  protMeth(char in)@{return in;@};
2787
public:
2788
        float pubMeth(float in)@{return in;@};
2789
@};
2790
@end example
2791
 
2792
It generates the following stab.  The digit in question is to the left
2793
of an @samp{A} in each case.  Notice also that in this case two symbol
2794
descriptors apply to the class name struct tag and struct type.
2795
 
2796
@display
2797
.stabs "class_name:sym_desc(struct tag&type)type_def(21)=
2798
        sym_desc(struct)struct_bytes(1)
2799
        meth_name::type_def(22)=sym_desc(method)returning(int);
2800
        :args(int);protection(private)modifier(normal)virtual(no);
2801
        meth_name::type_def(23)=sym_desc(method)returning(char);
2802
        :args(char);protection(protected)modifier(normal)virual(no);
2803
        meth_name::type_def(24)=sym_desc(method)returning(float);
2804
        :args(float);protection(public)modifier(normal)virtual(no);;",
2805
        N_LSYM,NIL,NIL,NIL
2806
@end display
2807
 
2808
@smallexample
2809
.stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.;
2810
        pubMeth::24=##12;:f;2A.;;",128,0,0,0
2811
@end smallexample
2812
 
2813
@node Method Modifiers
2814
@section Method Modifiers (@code{const}, @code{volatile}, @code{const volatile})
2815
 
2816
<< based on a6.C >>
2817
 
2818
In the class example described above all the methods have the normal
2819
modifier.  This method modifier information is located just after the
2820
protection information for the method.  This field has four possible
2821
character values.  Normal methods use @samp{A}, const methods use
2822
@samp{B}, volatile methods use @samp{C}, and const volatile methods use
2823
@samp{D}.  Consider the class definition below:
2824
 
2825
@example
2826
class A @{
2827
public:
2828
        int ConstMeth (int arg) const @{ return arg; @};
2829
        char VolatileMeth (char arg) volatile @{ return arg; @};
2830
        float ConstVolMeth (float arg) const volatile @{return arg; @};
2831
@};
2832
@end example
2833
 
2834
This class is described by the following stab:
2835
 
2836
@display
2837
.stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1)
2838
        meth_name(ConstMeth)::type_def(21)sym_desc(method)
2839
        returning(int);:arg(int);protection(public)modifier(const)virtual(no);
2840
        meth_name(VolatileMeth)::type_def(22)=sym_desc(method)
2841
        returning(char);:arg(char);protection(public)modifier(volatile)virt(no)
2842
        meth_name(ConstVolMeth)::type_def(23)=sym_desc(method)
2843
        returning(float);:arg(float);protection(public)modifer(const volatile)
2844
        virtual(no);;", @dots{}
2845
@end display
2846
 
2847
@example
2848
.stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.;
2849
             ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0
2850
@end example
2851
 
2852
@node Virtual Methods
2853
@section Virtual Methods
2854
 
2855
<< The following examples are based on a4.C >>
2856
 
2857
The presence of virtual methods in a class definition adds additional
2858
data to the class description.  The extra data is appended to the
2859
description of the virtual method and to the end of the class
2860
description.  Consider the class definition below:
2861
 
2862
@example
2863
class A @{
2864
public:
2865
        int Adat;
2866
        virtual int A_virt (int arg) @{ return arg; @};
2867
@};
2868
@end example
2869
 
2870
This results in the stab below describing class A.  It defines a new
2871
type (20) which is an 8 byte structure.  The first field of the class
2872
struct is @samp{Adat}, an integer, starting at structure offset 0 and
2873
occupying 32 bits.
2874
 
2875
The second field in the class struct is not explicitly defined by the
2876
C++ class definition but is implied by the fact that the class
2877
contains a virtual method.  This field is the vtable pointer.  The
2878
name of the vtable pointer field starts with @samp{$vf} and continues with a
2879
type reference to the class it is part of.  In this example the type
2880
reference for class A is 20 so the name of its vtable pointer field is
2881
@samp{$vf20}, followed by the usual colon.
2882
 
2883
Next there is a type definition for the vtable pointer type (21).
2884
This is in turn defined as a pointer to another new type (22).
2885
 
2886
Type 22 is the vtable itself, which is defined as an array, indexed by
2887
a range of integers between 0 and 1, and whose elements are of type
2888
17.  Type 17 was the vtable record type defined by the boilerplate C++
2889
type definitions, as shown earlier.
2890
 
2891
The bit offset of the vtable pointer field is 32.  The number of bits
2892
in the field are not specified when the field is a vtable pointer.
2893
 
2894
Next is the method definition for the virtual member function @code{A_virt}.
2895
Its description starts out using the same format as the non-virtual
2896
member functions described above, except instead of a dot after the
2897
@samp{A} there is an asterisk, indicating that the function is virtual.
2898
Since is is virtual some addition information is appended to the end
2899
of the method description.
2900
 
2901
The first number represents the vtable index of the method.  This is a
2902
32 bit unsigned number with the high bit set, followed by a
2903
semi-colon.
2904
 
2905
The second number is a type reference to the first base class in the
2906
inheritence hierarchy defining the virtual member function.  In this
2907
case the class stab describes a base class so the virtual function is
2908
not overriding any other definition of the method.  Therefore the
2909
reference is to the type number of the class that the stab is
2910
describing (20).
2911
 
2912
This is followed by three semi-colons.  One marks the end of the
2913
current sub-section, one marks the end of the method field, and the
2914
third marks the end of the struct definition.
2915
 
2916
For classes containing virtual functions the very last section of the
2917
string part of the stab holds a type reference to the first base
2918
class.  This is preceeded by @samp{~%} and followed by a final semi-colon.
2919
 
2920
@display
2921
.stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8)
2922
        field_name(Adat):type_ref(int),bit_offset(0),field_bits(32);
2923
        field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)=
2924
        sym_desc(array)index_type_ref(range of int from 0 to 1);
2925
        elem_type_ref(vtbl elem type),
2926
        bit_offset(32);
2927
        meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int);
2928
        :arg_type(int),protection(public)normal(yes)virtual(yes)
2929
        vtable_index(1);class_first_defining(A);;;~%first_base(A);",
2930
        N_LSYM,NIL,NIL,NIL
2931
@end display
2932
 
2933
@c FIXME: bogus line break.
2934
@example
2935
.stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
2936
        A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
2937
@end example
2938
 
2939
@node Inheritence
2940
@section Inheritence
2941
 
2942
Stabs describing C++ derived classes include additional sections that
2943
describe the inheritence hierarchy of the class.  A derived class stab
2944
also encodes the number of base classes.  For each base class it tells
2945
if the base class is virtual or not, and if the inheritence is private
2946
or public.  It also gives the offset into the object of the portion of
2947
the object corresponding to each base class.
2948
 
2949
This additional information is embeded in the class stab following the
2950
number of bytes in the struct.  First the number of base classes
2951
appears bracketed by an exclamation point and a comma.
2952
 
2953
Then for each base type there repeats a series: a virtual character, a
2954
visibilty character, a number, a comma, another number, and a
2955
semi-colon.
2956
 
2957
The virtual character is @samp{1} if the base class is virtual and
2958
@samp{0} if not.  The visibility character is @samp{2} if the derivation
2959
is public, @samp{1} if it is protected, and @samp{0} if it is private.
2960
Debuggers should ignore virtual or visibility characters they do not
2961
recognize, and assume a reasonable default (such as public and
2962
non-virtual) (GDB 4.11 does not, but this should be fixed in the next
2963
GDB release).
2964
 
2965
The number following the virtual and visibility characters is the offset
2966
from the start of the object to the part of the object pertaining to the
2967
base class.
2968
 
2969
After the comma, the second number is a type_descriptor for the base
2970
type.  Finally a semi-colon ends the series, which repeats for each
2971
base class.
2972
 
2973
The source below defines three base classes @code{A}, @code{B}, and
2974
@code{C} and the derived class @code{D}.
2975
 
2976
 
2977
@example
2978
class A @{
2979
public:
2980
        int Adat;
2981
        virtual int A_virt (int arg) @{ return arg; @};
2982
@};
2983
 
2984
class B @{
2985
public:
2986
        int B_dat;
2987
        virtual int B_virt (int arg) @{return arg; @};
2988
@};
2989
 
2990
class C @{
2991
public:
2992
        int Cdat;
2993
        virtual int C_virt (int arg) @{return arg; @};
2994
@};
2995
 
2996
class D : A, virtual B, public C @{
2997
public:
2998
        int Ddat;
2999
        virtual int A_virt (int arg ) @{ return arg+1; @};
3000
        virtual int B_virt (int arg)  @{ return arg+2; @};
3001
        virtual int C_virt (int arg)  @{ return arg+3; @};
3002
        virtual int D_virt (int arg)  @{ return arg; @};
3003
@};
3004
@end example
3005
 
3006
Class stabs similar to the ones described earlier are generated for
3007
each base class.
3008
 
3009
@c FIXME!!! the linebreaks in the following example probably make the
3010
@c examples literally unusable, but I don't know any other way to get
3011
@c them on the page.
3012
@c One solution would be to put some of the type definitions into
3013
@c separate stabs, even if that's not exactly what the compiler actually
3014
@c emits.
3015
@smallexample
3016
.stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
3017
        A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
3018
 
3019
.stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1;
3020
        :i;2A*-2147483647;25;;;~%25;",128,0,0,0
3021
 
3022
.stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1;
3023
        :i;2A*-2147483647;28;;;~%28;",128,0,0,0
3024
@end smallexample
3025
 
3026
In the stab describing derived class @code{D} below, the information about
3027
the derivation of this class is encoded as follows.
3028
 
3029
@display
3030
.stabs "derived_class_name:symbol_descriptors(struct tag&type)=
3031
        type_descriptor(struct)struct_bytes(32)!num_bases(3),
3032
        base_virtual(no)inheritence_public(no)base_offset(0),
3033
        base_class_type_ref(A);
3034
        base_virtual(yes)inheritence_public(no)base_offset(NIL),
3035
        base_class_type_ref(B);
3036
        base_virtual(no)inheritence_public(yes)base_offset(64),
3037
        base_class_type_ref(C); @dots{}
3038
@end display
3039
 
3040
@c FIXME! fake linebreaks.
3041
@smallexample
3042
.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:
3043
        1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt:
3044
        :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;
3045
        28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
3046
@end smallexample
3047
 
3048
@node Virtual Base Classes
3049
@section Virtual Base Classes
3050
 
3051
A derived class object consists of a concatenation in memory of the data
3052
areas defined by each base class, starting with the leftmost and ending
3053
with the rightmost in the list of base classes.  The exception to this
3054
rule is for virtual inheritence.  In the example above, class @code{D}
3055
inherits virtually from base class @code{B}.  This means that an
3056
instance of a @code{D} object will not contain its own @code{B} part but
3057
merely a pointer to a @code{B} part, known as a virtual base pointer.
3058
 
3059
In a derived class stab, the base offset part of the derivation
3060
information, described above, shows how the base class parts are
3061
ordered.  The base offset for a virtual base class is always given as 0.
3062
Notice that the base offset for @code{B} is given as 0 even though
3063
@code{B} is not the first base class.  The first base class @code{A}
3064
starts at offset 0.
3065
 
3066
The field information part of the stab for class @code{D} describes the field
3067
which is the pointer to the virtual base class @code{B}. The vbase pointer
3068
name is @samp{$vb} followed by a type reference to the virtual base class.
3069
Since the type id for @code{B} in this example is 25, the vbase pointer name
3070
is @samp{$vb25}.
3071
 
3072
@c FIXME!! fake linebreaks below
3073
@smallexample
3074
.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1,
3075
       160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i;
3076
       2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt:
3077
       :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
3078
@end smallexample
3079
 
3080
Following the name and a semicolon is a type reference describing the
3081
type of the virtual base class pointer, in this case 24.  Type 24 was
3082
defined earlier as the type of the @code{B} class @code{this} pointer.  The
3083
@code{this} pointer for a class is a pointer to the class type.
3084
 
3085
@example
3086
.stabs "this:P24=*25=xsB:",64,0,0,8
3087
@end example
3088
 
3089
Finally the field offset part of the vbase pointer field description
3090
shows that the vbase pointer is the first field in the @code{D} object,
3091
before any data fields defined by the class.  The layout of a @code{D}
3092
class object is a follows, @code{Adat} at 0, the vtable pointer for
3093
@code{A} at 32, @code{Cdat} at 64, the vtable pointer for C at 96, the
3094
virtual base pointer for @code{B} at 128, and @code{Ddat} at 160.
3095
 
3096
 
3097
@node Static Members
3098
@section Static Members
3099
 
3100
The data area for a class is a concatenation of the space used by the
3101
data members of the class.  If the class has virtual methods, a vtable
3102
pointer follows the class data.  The field offset part of each field
3103
description in the class stab shows this ordering.
3104
 
3105
<< How is this reflected in stabs?  See Cygnus bug #677 for some info.  >>
3106
 
3107
@node Stab Types
3108
@appendix Table of Stab Types
3109
 
3110
The following are all the possible values for the stab type field, for
3111
a.out files, in numeric order.  This does not apply to XCOFF, but
3112
it does apply to stabs in sections (@pxref{Stab Sections}).  Stabs in
3113
ECOFF use these values but add 0x8f300 to distinguish them from non-stab
3114
symbols.
3115
 
3116
The symbolic names are defined in the file @file{include/aout/stabs.def}.
3117
 
3118
@menu
3119
* Non-Stab Symbol Types::       Types from 0 to 0x1f
3120
* Stab Symbol Types::           Types from 0x20 to 0xff
3121
@end menu
3122
 
3123
@node Non-Stab Symbol Types
3124
@appendixsec Non-Stab Symbol Types
3125
 
3126
The following types are used by the linker and assembler, not by stab
3127
directives.  Since this document does not attempt to describe aspects of
3128
object file format other than the debugging format, no details are
3129
given.
3130
 
3131
@c Try to get most of these to fit on a single line.
3132
@iftex
3133
@tableindent=1.5in
3134
@end iftex
3135
 
3136
@table @code
3137
@item 0x0     N_UNDF
3138
Undefined symbol
3139
 
3140
@item 0x2     N_ABS
3141
File scope absolute symbol
3142
 
3143
@item 0x3     N_ABS | N_EXT
3144
External absolute symbol
3145
 
3146
@item 0x4     N_TEXT
3147
File scope text symbol
3148
 
3149
@item 0x5     N_TEXT | N_EXT
3150
External text symbol
3151
 
3152
@item 0x6     N_DATA
3153
File scope data symbol
3154
 
3155
@item 0x7     N_DATA | N_EXT
3156
External data symbol
3157
 
3158
@item 0x8     N_BSS
3159
File scope BSS symbol
3160
 
3161
@item 0x9     N_BSS | N_EXT
3162
External BSS symbol
3163
 
3164
@item 0x0c    N_FN_SEQ
3165
Same as @code{N_FN}, for Sequent compilers
3166
 
3167
@item 0x0a    N_INDR
3168
Symbol is indirected to another symbol
3169
 
3170
@item 0x12    N_COMM
3171
Common---visible after shared library dynamic link
3172
 
3173
@item 0x14 N_SETA
3174
@itemx 0x15 N_SETA | N_EXT
3175
Absolute set element
3176
 
3177
@item 0x16 N_SETT
3178
@itemx 0x17 N_SETT | N_EXT
3179
Text segment set element
3180
 
3181
@item 0x18 N_SETD
3182
@itemx 0x19 N_SETD | N_EXT
3183
Data segment set element
3184
 
3185
@item 0x1a N_SETB
3186
@itemx 0x1b N_SETB | N_EXT
3187
BSS segment set element
3188
 
3189
@item 0x1c N_SETV
3190
@itemx 0x1d N_SETV | N_EXT
3191
Pointer to set vector
3192
 
3193
@item 0x1e N_WARNING
3194
Print a warning message during linking
3195
 
3196
@item 0x1f    N_FN
3197
File name of a @file{.o} file
3198
@end table
3199
 
3200
@node Stab Symbol Types
3201
@appendixsec Stab Symbol Types
3202
 
3203
The following symbol types indicate that this is a stab.  This is the
3204
full list of stab numbers, including stab types that are used in
3205
languages other than C.
3206
 
3207
@table @code
3208
@item 0x20     N_GSYM
3209
Global symbol; see @ref{Global Variables}.
3210
 
3211
@item 0x22     N_FNAME
3212
Function name (for BSD Fortran); see @ref{Procedures}.
3213
 
3214
@item 0x24     N_FUN
3215
Function name (@pxref{Procedures}) or text segment variable
3216
(@pxref{Statics}).
3217
 
3218
@item 0x26 N_STSYM
3219
Data segment file-scope variable; see @ref{Statics}.
3220
 
3221
@item 0x28 N_LCSYM
3222
BSS segment file-scope variable; see @ref{Statics}.
3223
 
3224
@item 0x2a N_MAIN
3225
Name of main routine; see @ref{Main Program}.
3226
 
3227
@item 0x2c N_ROSYM
3228
Variable in @code{.rodata} section; see @ref{Statics}.
3229
 
3230
@item 0x30     N_PC
3231
Global symbol (for Pascal); see @ref{N_PC}.
3232
 
3233
@item 0x32     N_NSYMS
3234
Number of symbols (according to Ultrix V4.0); see @ref{N_NSYMS}.
3235
 
3236
@item 0x34     N_NOMAP
3237
No DST map; see @ref{N_NOMAP}.
3238
 
3239
@c FIXME: describe this solaris feature in the body of the text (see
3240
@c comments in include/aout/stab.def).
3241
@item 0x38 N_OBJ
3242
Object file (Solaris2).
3243
 
3244
@c See include/aout/stab.def for (a little) more info.
3245
@item 0x3c N_OPT
3246
Debugger options (Solaris2).
3247
 
3248
@item 0x40     N_RSYM
3249
Register variable; see @ref{Register Variables}.
3250
 
3251
@item 0x42     N_M2C
3252
Modula-2 compilation unit; see @ref{N_M2C}.
3253
 
3254
@item 0x44     N_SLINE
3255
Line number in text segment; see @ref{Line Numbers}.
3256
 
3257
@item 0x46     N_DSLINE
3258
Line number in data segment; see @ref{Line Numbers}.
3259
 
3260
@item 0x48     N_BSLINE
3261
Line number in bss segment; see @ref{Line Numbers}.
3262
 
3263
@item 0x48     N_BROWS
3264
Sun source code browser, path to @file{.cb} file; see @ref{N_BROWS}.
3265
 
3266
@item 0x4a     N_DEFD
3267
GNU Modula2 definition module dependency; see @ref{N_DEFD}.
3268
 
3269
@item 0x4c N_FLINE
3270
Function start/body/end line numbers (Solaris2).
3271
 
3272
@item 0x50     N_EHDECL
3273
GNU C++ exception variable; see @ref{N_EHDECL}.
3274
 
3275
@item 0x50     N_MOD2
3276
Modula2 info "for imc" (according to Ultrix V4.0); see @ref{N_MOD2}.
3277
 
3278
@item 0x54     N_CATCH
3279
GNU C++ @code{catch} clause; see @ref{N_CATCH}.
3280
 
3281
@item 0x60     N_SSYM
3282
Structure of union element; see @ref{N_SSYM}.
3283
 
3284
@item 0x62 N_ENDM
3285
Last stab for module (Solaris2).
3286
 
3287
@item 0x64     N_SO
3288
Path and name of source file; see @ref{Source Files}.
3289
 
3290
@item 0x80 N_LSYM
3291
Stack variable (@pxref{Stack Variables}) or type (@pxref{Typedefs}).
3292
 
3293
@item 0x82     N_BINCL
3294
Beginning of an include file (Sun only); see @ref{Include Files}.
3295
 
3296
@item 0x84     N_SOL
3297
Name of include file; see @ref{Include Files}.
3298
 
3299
@item 0xa0     N_PSYM
3300
Parameter variable; see @ref{Parameters}.
3301
 
3302
@item 0xa2     N_EINCL
3303
End of an include file; see @ref{Include Files}.
3304
 
3305
@item 0xa4     N_ENTRY
3306
Alternate entry point; see @ref{Alternate Entry Points}.
3307
 
3308
@item 0xc0     N_LBRAC
3309
Beginning of a lexical block; see @ref{Block Structure}.
3310
 
3311
@item 0xc2     N_EXCL
3312
Place holder for a deleted include file; see @ref{Include Files}.
3313
 
3314
@item 0xc4     N_SCOPE
3315
Modula2 scope information (Sun linker); see @ref{N_SCOPE}.
3316
 
3317
@item 0xe0     N_RBRAC
3318
End of a lexical block; see @ref{Block Structure}.
3319
 
3320
@item 0xe2     N_BCOMM
3321
Begin named common block; see @ref{Common Blocks}.
3322
 
3323
@item 0xe4     N_ECOMM
3324
End named common block; see @ref{Common Blocks}.
3325
 
3326
@item 0xe8     N_ECOML
3327
Member of a common block; see @ref{Common Blocks}.
3328
 
3329
@c FIXME: How does this really work?  Move it to main body of document.
3330
@item 0xea N_WITH
3331
Pascal @code{with} statement: type,,0,0,offset (Solaris2).
3332
 
3333
@item 0xf0     N_NBTEXT
3334
Gould non-base registers; see @ref{Gould}.
3335
 
3336
@item 0xf2     N_NBDATA
3337
Gould non-base registers; see @ref{Gould}.
3338
 
3339
@item 0xf4     N_NBBSS
3340
Gould non-base registers; see @ref{Gould}.
3341
 
3342
@item 0xf6     N_NBSTS
3343
Gould non-base registers; see @ref{Gould}.
3344
 
3345
@item 0xf8     N_NBLCS
3346
Gould non-base registers; see @ref{Gould}.
3347
@end table
3348
 
3349
@c Restore the default table indent
3350
@iftex
3351
@tableindent=.8in
3352
@end iftex
3353
 
3354
@node Symbol Descriptors
3355
@appendix Table of Symbol Descriptors
3356
 
3357
The symbol descriptor is the character which follows the colon in many
3358
stabs, and which tells what kind of stab it is.  @xref{String Field},
3359
for more information about their use.
3360
 
3361
@c Please keep this alphabetical
3362
@table @code
3363
@c In TeX, this looks great, digit is in italics.  But makeinfo insists
3364
@c on putting it in `', not realizing that @var should override @code.
3365
@c I don't know of any way to make makeinfo do the right thing.  Seems
3366
@c like a makeinfo bug to me.
3367
@item @var{digit}
3368
@itemx (
3369
@itemx -
3370
Variable on the stack; see @ref{Stack Variables}.
3371
 
3372
@item :
3373
C++ nested symbol; see @xref{Nested Symbols}.
3374
 
3375
@item a
3376
Parameter passed by reference in register; see @ref{Reference Parameters}.
3377
 
3378
@item b
3379
Based variable; see @ref{Based Variables}.
3380
 
3381
@item c
3382
Constant; see @ref{Constants}.
3383
 
3384
@item C
3385
Conformant array bound (Pascal, maybe other languages); @ref{Conformant
3386
Arrays}.  Name of a caught exception (GNU C++).  These can be
3387
distinguished because the latter uses @code{N_CATCH} and the former uses
3388
another symbol type.
3389
 
3390
@item d
3391
Floating point register variable; see @ref{Register Variables}.
3392
 
3393
@item D
3394
Parameter in floating point register; see @ref{Register Parameters}.
3395
 
3396
@item f
3397
File scope function; see @ref{Procedures}.
3398
 
3399
@item F
3400
Global function; see @ref{Procedures}.
3401
 
3402
@item G
3403
Global variable; see @ref{Global Variables}.
3404
 
3405
@item i
3406
@xref{Register Parameters}.
3407
 
3408
@item I
3409
Internal (nested) procedure; see @ref{Nested Procedures}.
3410
 
3411
@item J
3412
Internal (nested) function; see @ref{Nested Procedures}.
3413
 
3414
@item L
3415
Label name (documented by AIX, no further information known).
3416
 
3417
@item m
3418
Module; see @ref{Procedures}.
3419
 
3420
@item p
3421
Argument list parameter; see @ref{Parameters}.
3422
 
3423
@item pP
3424
@xref{Parameters}.
3425
 
3426
@item pF
3427
Fortran Function parameter; see @ref{Parameters}.
3428
 
3429
@item P
3430
Unfortunately, three separate meanings have been independently invented
3431
for this symbol descriptor.  At least the GNU and Sun uses can be
3432
distinguished by the symbol type.  Global Procedure (AIX) (symbol type
3433
used unknown); see @ref{Procedures}.  Register parameter (GNU) (symbol
3434
type @code{N_PSYM}); see @ref{Parameters}.  Prototype of function
3435
referenced by this file (Sun @code{acc}) (symbol type @code{N_FUN}).
3436
 
3437
@item Q
3438
Static Procedure; see @ref{Procedures}.
3439
 
3440
@item R
3441
Register parameter; see @ref{Register Parameters}.
3442
 
3443
@item r
3444
Register variable; see @ref{Register Variables}.
3445
 
3446
@item S
3447
File scope variable; see @ref{Statics}.
3448
 
3449
@item s
3450
Local variable (OS9000).
3451
 
3452
@item t
3453
Type name; see @ref{Typedefs}.
3454
 
3455
@item T
3456
Enumeration, structure, or union tag; see @ref{Typedefs}.
3457
 
3458
@item v
3459
Parameter passed by reference; see @ref{Reference Parameters}.
3460
 
3461
@item V
3462
Procedure scope static variable; see @ref{Statics}.
3463
 
3464
@item x
3465
Conformant array; see @ref{Conformant Arrays}.
3466
 
3467
@item X
3468
Function return variable; see @ref{Parameters}.
3469
@end table
3470
 
3471
@node Type Descriptors
3472
@appendix Table of Type Descriptors
3473
 
3474
The type descriptor is the character which follows the type number and
3475
an equals sign.  It specifies what kind of type is being defined.
3476
@xref{String Field}, for more information about their use.
3477
 
3478
@table @code
3479
@item @var{digit}
3480
@itemx (
3481
Type reference; see @ref{String Field}.
3482
 
3483
@item -
3484
Reference to builtin type; see @ref{Negative Type Numbers}.
3485
 
3486
@item #
3487
Method (C++); see @ref{Method Type Descriptor}.
3488
 
3489
@item *
3490
Pointer; see @ref{Miscellaneous Types}.
3491
 
3492
@item &
3493
Reference (C++).
3494
 
3495
@item @@
3496
Type Attributes (AIX); see @ref{String Field}.  Member (class and variable)
3497
type (GNU C++); see @ref{Member Type Descriptor}.
3498
 
3499
@item a
3500
Array; see @ref{Arrays}.
3501
 
3502
@item A
3503
Open array; see @ref{Arrays}.
3504
 
3505
@item b
3506
Pascal space type (AIX); see @ref{Miscellaneous Types}.  Builtin integer
3507
type (Sun); see @ref{Builtin Type Descriptors}.  Const and volatile
3508
qualfied type (OS9000).
3509
 
3510
@item B
3511
Volatile-qualified type; see @ref{Miscellaneous Types}.
3512
 
3513
@item c
3514
Complex builtin type (AIX); see @ref{Builtin Type Descriptors}.
3515
Const-qualified type (OS9000).
3516
 
3517
@item C
3518
COBOL Picture type.  See AIX documentation for details.
3519
 
3520
@item d
3521
File type; see @ref{Miscellaneous Types}.
3522
 
3523
@item D
3524
N-dimensional dynamic array; see @ref{Arrays}.
3525
 
3526
@item e
3527
Enumeration type; see @ref{Enumerations}.
3528
 
3529
@item E
3530
N-dimensional subarray; see @ref{Arrays}.
3531
 
3532
@item f
3533
Function type; see @ref{Function Types}.
3534
 
3535
@item F
3536
Pascal function parameter; see @ref{Function Types}
3537
 
3538
@item g
3539
Builtin floating point type; see @ref{Builtin Type Descriptors}.
3540
 
3541
@item G
3542
COBOL Group.  See AIX documentation for details.
3543
 
3544
@item i
3545
Imported type (AIX); see @ref{Cross-References}.  Volatile-qualified
3546
type (OS9000).
3547
 
3548
@item k
3549
Const-qualified type; see @ref{Miscellaneous Types}.
3550
 
3551
@item K
3552
COBOL File Descriptor.  See AIX documentation for details.
3553
 
3554
@item M
3555
Multiple instance type; see @ref{Miscellaneous Types}.
3556
 
3557
@item n
3558
String type; see @ref{Strings}.
3559
 
3560
@item N
3561
Stringptr; see @ref{Strings}.
3562
 
3563
@item o
3564
Opaque type; see @ref{Typedefs}.
3565
 
3566
@item p
3567
Procedure; see @ref{Function Types}.
3568
 
3569
@item P
3570
Packed array; see @ref{Arrays}.
3571
 
3572
@item r
3573
Range type; see @ref{Subranges}.
3574
 
3575
@item R
3576
Builtin floating type; see @ref{Builtin Type Descriptors} (Sun).  Pascal
3577
subroutine parameter; see @ref{Function Types} (AIX).  Detecting this
3578
conflict is possible with careful parsing (hint: a Pascal subroutine
3579
parameter type will always contain a comma, and a builtin type
3580
descriptor never will).
3581
 
3582
@item s
3583
Structure type; see @ref{Structures}.
3584
 
3585
@item S
3586
Set type; see @ref{Miscellaneous Types}.
3587
 
3588
@item u
3589
Union; see @ref{Unions}.
3590
 
3591
@item v
3592
Variant record.  This is a Pascal and Modula-2 feature which is like a
3593
union within a struct in C.  See AIX documentation for details.
3594
 
3595
@item w
3596
Wide character; see @ref{Builtin Type Descriptors}.
3597
 
3598
@item x
3599
Cross-reference; see @ref{Cross-References}.
3600
 
3601
@item Y
3602
Used by IBM's xlC C++ compiler (for structures, I think).
3603
 
3604
@item z
3605
gstring; see @ref{Strings}.
3606
@end table
3607
 
3608
@node Expanded Reference
3609
@appendix Expanded Reference by Stab Type
3610
 
3611
@c FIXME: This appendix should go away; see N_PSYM or N_SO for an example.
3612
 
3613
For a full list of stab types, and cross-references to where they are
3614
described, see @ref{Stab Types}.  This appendix just covers certain
3615
stabs which are not yet described in the main body of this document;
3616
eventually the information will all be in one place.
3617
 
3618
Format of an entry:
3619
 
3620
The first line is the symbol type (see @file{include/aout/stab.def}).
3621
 
3622
The second line describes the language constructs the symbol type
3623
represents.
3624
 
3625
The third line is the stab format with the significant stab fields
3626
named and the rest NIL.
3627
 
3628
Subsequent lines expand upon the meaning and possible values for each
3629
significant stab field.
3630
 
3631
Finally, any further information.
3632
 
3633
@menu
3634
* N_PC::                        Pascal global symbol
3635
* N_NSYMS::                     Number of symbols
3636
* N_NOMAP::                     No DST map
3637
* N_M2C::                       Modula-2 compilation unit
3638
* N_BROWS::                     Path to .cb file for Sun source code browser
3639
* N_DEFD::                      GNU Modula2 definition module dependency
3640
* N_EHDECL::                    GNU C++ exception variable
3641
* N_MOD2::                      Modula2 information "for imc"
3642
* N_CATCH::                     GNU C++ "catch" clause
3643
* N_SSYM::                      Structure or union element
3644
* N_SCOPE::                     Modula2 scope information (Sun only)
3645
* Gould::                       non-base register symbols used on Gould systems
3646
* N_LENG::                      Length of preceding entry
3647
@end menu
3648
 
3649
@node N_PC
3650
@section N_PC
3651
 
3652
@deffn @code{.stabs} N_PC
3653
@findex N_PC
3654
Global symbol (for Pascal).
3655
 
3656
@example
3657
"name" -> "symbol_name"  <<?>>
3658
value  -> supposedly the line number (stab.def is skeptical)
3659
@end example
3660
 
3661
@display
3662
@file{stabdump.c} says:
3663
 
3664
global pascal symbol: name,,0,subtype,line
3665
<< subtype? >>
3666
@end display
3667
@end deffn
3668
 
3669
@node N_NSYMS
3670
@section N_NSYMS
3671
 
3672
@deffn @code{.stabn} N_NSYMS
3673
@findex N_NSYMS
3674
Number of symbols (according to Ultrix V4.0).
3675
 
3676
@display
3677
        0, files,,funcs,lines (stab.def)
3678
@end display
3679
@end deffn
3680
 
3681
@node N_NOMAP
3682
@section N_NOMAP
3683
 
3684
@deffn @code{.stabs} N_NOMAP
3685
@findex N_NOMAP
3686
No DST map for symbol (according to Ultrix V4.0).  I think this means a
3687
variable has been optimized out.
3688
 
3689
@display
3690
        name, ,0,type,ignored (stab.def)
3691
@end display
3692
@end deffn
3693
 
3694
@node N_M2C
3695
@section N_M2C
3696
 
3697
@deffn @code{.stabs} N_M2C
3698
@findex N_M2C
3699
Modula-2 compilation unit.
3700
 
3701
@example
3702
"string" -> "unit_name,unit_time_stamp[,code_time_stamp]"
3703
desc   -> unit_number
3704
value  -> 0 (main unit)
3705
          1 (any other unit)
3706
@end example
3707
 
3708
See @cite{Dbx and Dbxtool Interfaces}, 2nd edition, by Sun, 1988, for
3709
more information.
3710
 
3711
@end deffn
3712
 
3713
@node N_BROWS
3714
@section N_BROWS
3715
 
3716
@deffn @code{.stabs} N_BROWS
3717
@findex N_BROWS
3718
Sun source code browser, path to @file{.cb} file
3719
 
3720
<<?>>
3721
"path to associated @file{.cb} file"
3722
 
3723
Note: N_BROWS has the same value as N_BSLINE.
3724
@end deffn
3725
 
3726
@node N_DEFD
3727
@section N_DEFD
3728
 
3729
@deffn @code{.stabn} N_DEFD
3730
@findex N_DEFD
3731
GNU Modula2 definition module dependency.
3732
 
3733
GNU Modula-2 definition module dependency.  The value is the
3734
modification time of the definition file.  The other field is non-zero
3735
if it is imported with the GNU M2 keyword @code{%INITIALIZE}.  Perhaps
3736
@code{N_M2C} can be used if there are enough empty fields?
3737
@end deffn
3738
 
3739
@node N_EHDECL
3740
@section N_EHDECL
3741
 
3742
@deffn @code{.stabs} N_EHDECL
3743
@findex N_EHDECL
3744
GNU C++ exception variable <<?>>.
3745
 
3746
"@var{string} is variable name"
3747
 
3748
Note: conflicts with @code{N_MOD2}.
3749
@end deffn
3750
 
3751
@node N_MOD2
3752
@section N_MOD2
3753
 
3754
@deffn @code{.stab?} N_MOD2
3755
@findex N_MOD2
3756
Modula2 info "for imc" (according to Ultrix V4.0)
3757
 
3758
Note: conflicts with @code{N_EHDECL}  <<?>>
3759
@end deffn
3760
 
3761
@node N_CATCH
3762
@section N_CATCH
3763
 
3764
@deffn @code{.stabn} N_CATCH
3765
@findex N_CATCH
3766
GNU C++ @code{catch} clause
3767
 
3768
GNU C++ @code{catch} clause.  The value is its address.  The desc field
3769
is nonzero if this entry is immediately followed by a @code{CAUGHT} stab
3770
saying what exception was caught.  Multiple @code{CAUGHT} stabs means
3771
that multiple exceptions can be caught here.  If desc is 0, it means all
3772
exceptions are caught here.
3773
@end deffn
3774
 
3775
@node N_SSYM
3776
@section N_SSYM
3777
 
3778
@deffn @code{.stabn} N_SSYM
3779
@findex N_SSYM
3780
Structure or union element.
3781
 
3782
The value is the offset in the structure.
3783
 
3784
<<?looking at structs and unions in C I didn't see these>>
3785
@end deffn
3786
 
3787
@node N_SCOPE
3788
@section N_SCOPE
3789
 
3790
@deffn @code{.stab?} N_SCOPE
3791
@findex N_SCOPE
3792
Modula2 scope information (Sun linker)
3793
<<?>>
3794
@end deffn
3795
 
3796
@node Gould
3797
@section Non-base registers on Gould systems
3798
 
3799
@deffn @code{.stab?} N_NBTEXT
3800
@deffnx @code{.stab?} N_NBDATA
3801
@deffnx @code{.stab?} N_NBBSS
3802
@deffnx @code{.stab?} N_NBSTS
3803
@deffnx @code{.stab?} N_NBLCS
3804
@findex N_NBTEXT
3805
@findex N_NBDATA
3806
@findex N_NBBSS
3807
@findex N_NBSTS
3808
@findex N_NBLCS
3809
These are used on Gould systems for non-base registers syms.
3810
 
3811
However, the following values are not the values used by Gould; they are
3812
the values which GNU has been documenting for these values for a long
3813
time, without actually checking what Gould uses.  I include these values
3814
only because perhaps some someone actually did something with the GNU
3815
information (I hope not, why GNU knowingly assigned wrong values to
3816
these in the header file is a complete mystery to me).
3817
 
3818
@example
3819
240    0xf0     N_NBTEXT  ??
3820
242    0xf2     N_NBDATA  ??
3821
244    0xf4     N_NBBSS   ??
3822
246    0xf6     N_NBSTS   ??
3823
248    0xf8     N_NBLCS   ??
3824
@end example
3825
@end deffn
3826
 
3827
@node N_LENG
3828
@section N_LENG
3829
 
3830
@deffn @code{.stabn} N_LENG
3831
@findex N_LENG
3832
Second symbol entry containing a length-value for the preceding entry.
3833
The value is the length.
3834
@end deffn
3835
 
3836
@node Questions
3837
@appendix Questions and Anomalies
3838
 
3839
@itemize @bullet
3840
@item
3841
@c I think this is changed in GCC 2.4.5 to put the line number there.
3842
For GNU C stabs defining local and global variables (@code{N_LSYM} and
3843
@code{N_GSYM}), the desc field is supposed to contain the source
3844
line number on which the variable is defined.  In reality the desc
3845
field is always 0.  (This behavior is defined in @file{dbxout.c} and
3846
putting a line number in desc is controlled by @samp{#ifdef
3847
WINNING_GDB}, which defaults to false). GDB supposedly uses this
3848
information if you say @samp{list @var{var}}.  In reality, @var{var} can
3849
be a variable defined in the program and GDB says @samp{function
3850
@var{var} not defined}.
3851
 
3852
@item
3853
In GNU C stabs, there seems to be no way to differentiate tag types:
3854
structures, unions, and enums (symbol descriptor @samp{T}) and typedefs
3855
(symbol descriptor @samp{t}) defined at file scope from types defined locally
3856
to a procedure or other more local scope.  They all use the @code{N_LSYM}
3857
stab type.  Types defined at procedure scope are emited after the
3858
@code{N_RBRAC} of the preceding function and before the code of the
3859
procedure in which they are defined.  This is exactly the same as
3860
types defined in the source file between the two procedure bodies.
3861
GDB overcompensates by placing all types in block #1, the block for
3862
symbols of file scope.  This is true for default, @samp{-ansi} and
3863
@samp{-traditional} compiler options. (Bugs gcc/1063, gdb/1066.)
3864
 
3865
@item
3866
What ends the procedure scope?  Is it the proc block's @code{N_RBRAC} or the
3867
next @code{N_FUN}?  (I believe its the first.)
3868
@end itemize
3869
 
3870
@node Stab Sections
3871
@appendix Using Stabs in Their Own Sections
3872
 
3873
Many object file formats allow tools to create object files with custom
3874
sections containing any arbitrary data.  For any such object file
3875
format, stabs can be embedded in special sections.  This is how stabs
3876
are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs
3877
are used with COFF.
3878
 
3879
@menu
3880
* Stab Section Basics::    How to embed stabs in sections
3881
* ELF Linker Relocation::  Sun ELF hacks
3882
@end menu
3883
 
3884
@node Stab Section Basics
3885
@appendixsec How to Embed Stabs in Sections
3886
 
3887
The assembler creates two custom sections, a section named @code{.stab}
3888
which contains an array of fixed length structures, one struct per stab,
3889
and a section named @code{.stabstr} containing all the variable length
3890
strings that are referenced by stabs in the @code{.stab} section.  The
3891
byte order of the stabs binary data depends on the object file format.
3892
For ELF, it matches the byte order of the ELF file itself, as determined
3893
from the @code{EI_DATA} field in the @code{e_ident} member of the ELF
3894
header.  For SOM, it is always big-endian (is this true??? FIXME).  For
3895
COFF, it matches the byte order of the COFF headers.  The meaning of the
3896
fields is the same as for a.out (@pxref{Symbol Table Format}), except
3897
that the @code{n_strx} field is relative to the strings for the current
3898
compilation unit (which can be found using the synthetic N_UNDF stab
3899
described below), rather than the entire string table.
3900
 
3901
The first stab in the @code{.stab} section for each compilation unit is
3902
synthetic, generated entirely by the assembler, with no corresponding
3903
@code{.stab} directive as input to the assembler.  This stab contains
3904
the following fields:
3905
 
3906
@table @code
3907
@item n_strx
3908
Offset in the @code{.stabstr} section to the source filename.
3909
 
3910
@item n_type
3911
@code{N_UNDF}.
3912
 
3913
@item n_other
3914
Unused field, always zero.
3915
This may eventually be used to hold overflows from the count in
3916
the @code{n_desc} field.
3917
 
3918
@item n_desc
3919
Count of upcoming symbols, i.e., the number of remaining stabs for this
3920
source file.
3921
 
3922
@item n_value
3923
Size of the string table fragment associated with this source file, in
3924
bytes.
3925
@end table
3926
 
3927
The @code{.stabstr} section always starts with a null byte (so that string
3928
offsets of zero reference a null string), followed by random length strings,
3929
each of which is null byte terminated.
3930
 
3931
The ELF section header for the @code{.stab} section has its
3932
@code{sh_link} member set to the section number of the @code{.stabstr}
3933
section, and the @code{.stabstr} section has its ELF section
3934
header @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a
3935
string table.  SOM and COFF have no way of linking the sections together
3936
or marking them as string tables.
3937
 
3938
For COFF, the @code{.stab} and @code{.stabstr} sections may be simply
3939
concatenated by the linker.  GDB then uses the @code{n_desc} fields to
3940
figure out the extent of the original sections.  Similarly, the
3941
@code{n_value} fields of the header symbols are added together in order
3942
to get the actual position of the strings in a desired @code{.stabstr}
3943
section.  Although this design obviates any need for the linker to
3944
relocate or otherwise manipulate @code{.stab} and @code{.stabstr}
3945
sections, it also requires some care to ensure that the offsets are
3946
calculated correctly.  For instance, if the linker were to pad in
3947
between the @code{.stabstr} sections before concatenating, then the
3948
offsets to strings in the middle of the executable's @code{.stabstr}
3949
section would be wrong.
3950
 
3951
The GNU linker is able to optimize stabs information by merging
3952
duplicate strings and removing duplicate header file information
3953
(@pxref{Include Files}).  When some versions of the GNU linker optimize
3954
stabs in sections, they remove the leading @code{N_UNDF} symbol and
3955
arranges for all the @code{n_strx} fields to be relative to the start of
3956
the @code{.stabstr} section.
3957
 
3958
@node ELF Linker Relocation
3959
@appendixsec Having the Linker Relocate Stabs in ELF
3960
 
3961
This section describes some Sun hacks for Stabs in ELF; it does not
3962
apply to COFF or SOM.
3963
 
3964
To keep linking fast, you don't want the linker to have to relocate very
3965
many stabs.  Making sure this is done for @code{N_SLINE},
3966
@code{N_RBRAC}, and @code{N_LBRAC} stabs is the most important thing
3967
(see the descriptions of those stabs for more information).  But Sun's
3968
stabs in ELF has taken this further, to make all addresses in the
3969
@code{n_value} field (functions and static variables) relative to the
3970
source file.  For the @code{N_SO} symbol itself, Sun simply omits the
3971
address.  To find the address of each section corresponding to a given
3972
source file, the compiler puts out symbols giving the address of each
3973
section for a given source file.  Since these are ELF (not stab)
3974
symbols, the linker relocates them correctly without having to touch the
3975
stabs section.  They are named @code{Bbss.bss} for the bss section,
3976
@code{Ddata.data} for the data section, and @code{Drodata.rodata} for
3977
the rodata section.  For the text section, there is no such symbol (but
3978
there should be, see below).  For an example of how these symbols work,
3979
@xref{Stab Section Transformations}.  GCC does not provide these symbols;
3980
it instead relies on the stabs getting relocated.  Thus addresses which
3981
would normally be relative to @code{Bbss.bss}, etc., are already
3982
relocated.  The Sun linker provided with Solaris 2.2 and earlier
3983
relocates stabs using normal ELF relocation information, as it would do
3984
for any section.  Sun has been threatening to kludge their linker to not
3985
do this (to speed up linking), even though the correct way to avoid
3986
having the linker do these relocations is to have the compiler no longer
3987
output relocatable values.  Last I heard they had been talked out of the
3988
linker kludge.  See Sun point patch 101052-01 and Sun bug 1142109.  With
3989
the Sun compiler this affects @samp{S} symbol descriptor stabs
3990
(@pxref{Statics}) and functions (@pxref{Procedures}).  In the latter
3991
case, to adopt the clean solution (making the value of the stab relative
3992
to the start of the compilation unit), it would be necessary to invent a
3993
@code{Ttext.text} symbol, analogous to the @code{Bbss.bss}, etc.,
3994
symbols.  I recommend this rather than using a zero value and getting
3995
the address from the ELF symbols.
3996
 
3997
Finding the correct @code{Bbss.bss}, etc., symbol is difficult, because
3998
the linker simply concatenates the @code{.stab} sections from each
3999
@file{.o} file without including any information about which part of a
4000
@code{.stab} section comes from which @file{.o} file.  The way GDB does
4001
this is to look for an ELF @code{STT_FILE} symbol which has the same
4002
name as the last component of the file name from the @code{N_SO} symbol
4003
in the stabs (for example, if the file name is @file{../../gdb/main.c},
4004
it looks for an ELF @code{STT_FILE} symbol named @code{main.c}).  This
4005
loses if different files have the same name (they could be in different
4006
directories, a library could have been copied from one system to
4007
another, etc.).  It would be much cleaner to have the @code{Bbss.bss}
4008
symbols in the stabs themselves.  Having the linker relocate them there
4009
is no more work than having the linker relocate ELF symbols, and it
4010
solves the problem of having to associate the ELF and stab symbols.
4011
However, no one has yet designed or implemented such a scheme.
4012
 
4013
@node Symbol Types Index
4014
@unnumbered Symbol Types Index
4015
 
4016
@printindex fn
4017
 
4018
@contents
4019
@bye

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.