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

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [gdb-6.8/] [gdb/] [doc/] [stabs.texinfo] - Blame information for rev 247

Go to most recent revision | Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

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