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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-old/] [gdb-6.8/] [gdb/] [doc/] [stabs.info] - Blame information for rev 840

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 24 jeremybenn
This is stabs.info, produced by makeinfo version 4.8 from
2
../.././gdb/doc/stabs.texinfo.
3
 
4
INFO-DIR-SECTION Software development
5
START-INFO-DIR-ENTRY
6
* Stabs: (stabs).                 The "stabs" debugging information format.
7
END-INFO-DIR-ENTRY
8
 
9
   This document describes the stabs debugging symbol tables.
10
 
11
   Copyright (C) 1992,1993,1994,1995,1997,1998,2000,2001    Free
12
Software Foundation, Inc.  Contributed by Cygnus Support.  Written by
13
Julia Menapace, Jim Kingdon, and David MacKenzie.
14
 
15
   Permission is granted to copy, distribute and/or modify this document
16
under the terms of the GNU Free Documentation License, Version 1.1 or
17
any later version published by the Free Software Foundation; with no
18
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
19
Texts.  A copy of the license is included in the section entitled "GNU
20
Free Documentation License".
21
 
22

23
File: stabs.info,  Node: Top,  Next: Overview,  Up: (dir)
24
 
25
The "stabs" representation of debugging information
26
***************************************************
27
 
28
This document describes the stabs debugging format.
29
 
30
* Menu:
31
 
32
* Overview::                    Overview of stabs
33
* Program Structure::           Encoding of the structure of the program
34
* Constants::                   Constants
35
* Variables::
36
* Types::                       Type definitions
37
* Macro define and undefine::   Representation of #define and #undef
38
* Symbol Tables::               Symbol information in symbol tables
39
* Cplusplus::                   Stabs specific to C++
40
* Stab Types::                  Symbol types in a.out files
41
* Symbol Descriptors::          Table of symbol descriptors
42
* Type Descriptors::            Table of type descriptors
43
* Expanded Reference::          Reference information by stab type
44
* Questions::                   Questions and anomalies
45
* Stab Sections::               In some object file formats, stabs are
46
                                in sections.
47
* Symbol Types Index::          Index of symbolic stab symbol type names.
48
* GNU Free Documentation License::  The license for this documentation
49
 
50

51
File: stabs.info,  Node: Overview,  Next: Program Structure,  Prev: Top,  Up: Top
52
 
53
1 Overview of Stabs
54
*******************
55
 
56
"Stabs" refers to a format for information that describes a program to
57
a debugger.  This format was apparently invented by Peter Kessler at
58
the University of California at Berkeley, for the `pdx' Pascal
59
debugger; the format has spread widely since then.
60
 
61
   This document is one of the few published sources of documentation on
62
stabs.  It is believed to be comprehensive for stabs used by C.  The
63
lists of symbol descriptors (*note Symbol Descriptors::) and type
64
descriptors (*note Type Descriptors::) are believed to be completely
65
comprehensive.  Stabs for COBOL-specific features and for variant
66
records (used by Pascal and Modula-2) are poorly documented here.
67
 
68
   Other sources of information on stabs are `Dbx and Dbxtool
69
Interfaces', 2nd edition, by Sun, 1988, and `AIX Version 3.2 Files
70
Reference', Fourth Edition, September 1992, "dbx Stabstring Grammar" in
71
the a.out section, page 2-31.  This document is believed to incorporate
72
the information from those two sources except where it explicitly
73
directs you to them for more information.
74
 
75
* Menu:
76
 
77
* Flow::                        Overview of debugging information flow
78
* Stabs Format::                Overview of stab format
79
* String Field::                The string field
80
* C Example::                   A simple example in C source
81
* Assembly Code::               The simple example at the assembly level
82
 
83

84
File: stabs.info,  Node: Flow,  Next: Stabs Format,  Up: Overview
85
 
86
1.1 Overview of Debugging Information Flow
87
==========================================
88
 
89
The GNU C compiler compiles C source in a `.c' file into assembly
90
language in a `.s' file, which the assembler translates into a `.o'
91
file, which the linker combines with other `.o' files and libraries to
92
produce an executable file.
93
 
94
   With the `-g' option, GCC puts in the `.s' file additional debugging
95
information, which is slightly transformed by the assembler and linker,
96
and carried through into the final executable.  This debugging
97
information describes features of the source file like line numbers,
98
the types and scopes of variables, and function names, parameters, and
99
scopes.
100
 
101
   For some object file formats, the debugging information is
102
encapsulated in assembler directives known collectively as "stab"
103
(symbol table) directives, which are interspersed with the generated
104
code.  Stabs are the native format for debugging information in the
105
a.out and XCOFF object file formats.  The GNU tools can also emit stabs
106
in the COFF and ECOFF object file formats.
107
 
108
   The assembler adds the information from stabs to the symbol
109
information it places by default in the symbol table and the string
110
table of the `.o' file it is building.  The linker consolidates the `.o'
111
files into one executable file, with one symbol table and one string
112
table.  Debuggers use the symbol and string tables in the executable as
113
a source of debugging information about the program.
114
 
115

116
File: stabs.info,  Node: Stabs Format,  Next: String Field,  Prev: Flow,  Up: Overview
117
 
118
1.2 Overview of Stab Format
119
===========================
120
 
121
There are three overall formats for stab assembler directives,
122
differentiated by the first word of the stab.  The name of the directive
123
describes which combination of four possible data fields follows.  It is
124
either `.stabs' (string), `.stabn' (number), or `.stabd' (dot).  IBM's
125
XCOFF assembler uses `.stabx' (and some other directives such as
126
`.file' and `.bi') instead of `.stabs', `.stabn' or `.stabd'.
127
 
128
   The overall format of each class of stab is:
129
 
130
     .stabs "STRING",TYPE,OTHER,DESC,VALUE
131
     .stabn TYPE,OTHER,DESC,VALUE
132
     .stabd TYPE,OTHER,DESC
133
     .stabx "STRING",VALUE,TYPE,SDB-TYPE
134
 
135
   For `.stabn' and `.stabd', there is no STRING (the `n_strx' field is
136
zero; see *Note Symbol Tables::).  For `.stabd', the VALUE field is
137
implicit and has the value of the current file location.  For `.stabx',
138
the SDB-TYPE field is unused for stabs and can always be set to zero.
139
The OTHER field is almost always unused and can be set to zero.
140
 
141
   The number in the TYPE field gives some basic information about
142
which type of stab this is (or whether it _is_ a stab, as opposed to an
143
ordinary symbol).  Each valid type number defines a different stab
144
type; further, the stab type defines the exact interpretation of, and
145
possible values for, any remaining STRING, DESC, or VALUE fields
146
present in the stab.  *Note Stab Types::, for a list in numeric order
147
of the valid TYPE field values for stab directives.
148
 
149

150
File: stabs.info,  Node: String Field,  Next: C Example,  Prev: Stabs Format,  Up: Overview
151
 
152
1.3 The String Field
153
====================
154
 
155
For most stabs the string field holds the meat of the debugging
156
information.  The flexible nature of this field is what makes stabs
157
extensible.  For some stab types the string field contains only a name.
158
For other stab types the contents can be a great deal more complex.
159
 
160
   The overall format of the string field for most stab types is:
161
 
162
     "NAME:SYMBOL-DESCRIPTOR TYPE-INFORMATION"
163
 
164
   NAME is the name of the symbol represented by the stab; it can
165
contain a pair of colons (*note Nested Symbols::).  NAME can be
166
omitted, which means the stab represents an unnamed object.  For
167
example, `:t10=*2' defines type 10 as a pointer to type 2, but does not
168
give the type a name.  Omitting the NAME field is supported by AIX dbx
169
and GDB after about version 4.8, but not other debuggers.  GCC
170
sometimes uses a single space as the name instead of omitting the name
171
altogether; apparently that is supported by most debuggers.
172
 
173
   The SYMBOL-DESCRIPTOR following the `:' is an alphabetic character
174
that tells more specifically what kind of symbol the stab represents.
175
If the SYMBOL-DESCRIPTOR is omitted, but type information follows, then
176
the stab represents a local variable.  For a list of symbol
177
descriptors, see *Note Symbol Descriptors::.  The `c' symbol descriptor
178
is an exception in that it is not followed by type information.  *Note
179
Constants::.
180
 
181
   TYPE-INFORMATION is either a TYPE-NUMBER, or `TYPE-NUMBER='.  A
182
TYPE-NUMBER alone is a type reference, referring directly to a type
183
that has already been defined.
184
 
185
   The `TYPE-NUMBER=' form is a type definition, where the number
186
represents a new type which is about to be defined.  The type
187
definition may refer to other types by number, and those type numbers
188
may be followed by `=' and nested definitions.  Also, the Lucid
189
compiler will repeat `TYPE-NUMBER=' more than once if it wants to
190
define several type numbers at once.
191
 
192
   In a type definition, if the character that follows the equals sign
193
is non-numeric then it is a TYPE-DESCRIPTOR, and tells what kind of
194
type is about to be defined.  Any other values following the
195
TYPE-DESCRIPTOR vary, depending on the TYPE-DESCRIPTOR.  *Note Type
196
Descriptors::, for a list of TYPE-DESCRIPTOR values.  If a number
197
follows the `=' then the number is a TYPE-REFERENCE.  For a full
198
description of types, *Note Types::.
199
 
200
   A TYPE-NUMBER is often a single number.  The GNU and Sun tools
201
additionally permit a TYPE-NUMBER to be a pair
202
(FILE-NUMBER,FILETYPE-NUMBER) (the parentheses appear in the string,
203
and serve to distinguish the two cases).  The FILE-NUMBER is 0 for the
204
base source file, 1 for the first included file, 2 for the next, and so
205
on.  The FILETYPE-NUMBER is a number starting with 1 which is
206
incremented for each new type defined in the file.  (Separating the
207
file number and the type number permits the `N_BINCL' optimization to
208
succeed more often; see *Note Include Files::).
209
 
210
   There is an AIX extension for type attributes.  Following the `='
211
are any number of type attributes.  Each one starts with `@' and ends
212
with `;'.  Debuggers, including AIX's dbx and GDB 4.10, skip any type
213
attributes they do not recognize.  GDB 4.9 and other versions of dbx
214
may not do this.  Because of a conflict with C++ (*note Cplusplus::),
215
new attributes should not be defined which begin with a digit, `(', or
216
`-'; GDB may be unable to distinguish those from the C++ type
217
descriptor `@'.  The attributes are:
218
 
219
`aBOUNDARY'
220
     BOUNDARY is an integer specifying the alignment.  I assume it
221
     applies to all variables of this type.
222
 
223
`pINTEGER'
224
     Pointer class (for checking).  Not sure what this means, or how
225
     INTEGER is interpreted.
226
 
227
`P'
228
     Indicate this is a packed type, meaning that structure fields or
229
     array elements are placed more closely in memory, to save memory
230
     at the expense of speed.
231
 
232
`sSIZE'
233
     Size in bits of a variable of this type.  This is fully supported
234
     by GDB 4.11 and later.
235
 
236
`S'
237
     Indicate that this type is a string instead of an array of
238
     characters, or a bitstring instead of a set.  It doesn't change
239
     the layout of the data being represented, but does enable the
240
     debugger to know which type it is.
241
 
242
`V'
243
     Indicate that this type is a vector instead of an array.  The only
244
     major difference between vectors and arrays is that vectors are
245
     passed by value instead of by reference (vector coprocessor
246
     extension).
247
 
248
 
249
   All of this can make the string field quite long.  All versions of
250
GDB, and some versions of dbx, can handle arbitrarily long strings.
251
But many versions of dbx (or assemblers or linkers, I'm not sure which)
252
cretinously limit the strings to about 80 characters, so compilers which
253
must work with such systems need to split the `.stabs' directive into
254
several `.stabs' directives.  Each stab duplicates every field except
255
the string field.  The string field of every stab except the last is
256
marked as continued with a backslash at the end (in the assembly code
257
this may be written as a double backslash, depending on the assembler).
258
Removing the backslashes and concatenating the string fields of each
259
stab produces the original, long string.  Just to be incompatible (or so
260
they don't have to worry about what the assembler does with
261
backslashes), AIX can use `?' instead of backslash.
262
 
263

264
File: stabs.info,  Node: C Example,  Next: Assembly Code,  Prev: String Field,  Up: Overview
265
 
266
1.4 A Simple Example in C Source
267
================================
268
 
269
To get the flavor of how stabs describe source information for a C
270
program, let's look at the simple program:
271
 
272
     main()
273
     {
274
             printf("Hello world");
275
     }
276
 
277
   When compiled with `-g', the program above yields the following `.s'
278
file.  Line numbers have been added to make it easier to refer to parts
279
of the `.s' file in the description of the stabs that follows.
280
 
281

282
File: stabs.info,  Node: Assembly Code,  Prev: C Example,  Up: Overview
283
 
284
1.5 The Simple Example at the Assembly Level
285
============================================
286
 
287
This simple "hello world" example demonstrates several of the stab
288
types used to describe C language source files.
289
 
290
     1  gcc2_compiled.:
291
     2  .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
292
     3  .stabs "hello.c",100,0,0,Ltext0
293
     4  .text
294
     5  Ltext0:
295
     6  .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
296
     7  .stabs "char:t2=r2;0;127;",128,0,0,0
297
     8  .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
298
     9  .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
299
     10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
300
     11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
301
     12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
302
     13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
303
     14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
304
     15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
305
     16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
306
     17 .stabs "float:t12=r1;4;0;",128,0,0,0
307
     18 .stabs "double:t13=r1;8;0;",128,0,0,0
308
     19 .stabs "long double:t14=r1;8;0;",128,0,0,0
309
     20 .stabs "void:t15=15",128,0,0,0
310
     21      .align 4
311
     22 LC0:
312
     23      .ascii "Hello, world!\12\0"
313
     24      .align 4
314
     25      .global _main
315
     26      .proc 1
316
     27 _main:
317
     28 .stabn 68,0,4,LM1
318
     29 LM1:
319
     30      !#PROLOGUE# 0
320
     31      save %sp,-136,%sp
321
     32      !#PROLOGUE# 1
322
     33      call ___main,0
323
     34      nop
324
     35 .stabn 68,0,5,LM2
325
     36 LM2:
326
     37 LBB2:
327
     38      sethi %hi(LC0),%o1
328
     39      or %o1,%lo(LC0),%o0
329
     40      call _printf,0
330
     41      nop
331
     42 .stabn 68,0,6,LM3
332
     43 LM3:
333
     44 LBE2:
334
     45 .stabn 68,0,6,LM4
335
     46 LM4:
336
     47 L1:
337
     48      ret
338
     49      restore
339
     50 .stabs "main:F1",36,0,0,_main
340
     51 .stabn 192,0,0,LBB2
341
     52 .stabn 224,0,0,LBE2
342
 
343

344
File: stabs.info,  Node: Program Structure,  Next: Constants,  Prev: Overview,  Up: Top
345
 
346
2 Encoding the Structure of the Program
347
***************************************
348
 
349
The elements of the program structure that stabs encode include the name
350
of the main function, the names of the source and include files, the
351
line numbers, procedure names and types, and the beginnings and ends of
352
blocks of code.
353
 
354
* Menu:
355
 
356
* Main Program::                Indicate what the main program is
357
* Source Files::                The path and name of the source file
358
* Include Files::               Names of include files
359
* Line Numbers::
360
* Procedures::
361
* Nested Procedures::
362
* Block Structure::
363
* Alternate Entry Points::      Entering procedures except at the beginning.
364
 
365

366
File: stabs.info,  Node: Main Program,  Next: Source Files,  Up: Program Structure
367
 
368
2.1 Main Program
369
================
370
 
371
Most languages allow the main program to have any name.  The `N_MAIN'
372
stab type tells the debugger the name that is used in this program.
373
Only the string field is significant; it is the name of a function
374
which is the main program.  Most C compilers do not use this stab (they
375
expect the debugger to assume that the name is `main'), but some C
376
compilers emit an `N_MAIN' stab for the `main' function.  I'm not sure
377
how XCOFF handles this.
378
 
379

380
File: stabs.info,  Node: Source Files,  Next: Include Files,  Prev: Main Program,  Up: Program Structure
381
 
382
2.2 Paths and Names of the Source Files
383
=======================================
384
 
385
Before any other stabs occur, there must be a stab specifying the source
386
file.  This information is contained in a symbol of stab type `N_SO';
387
the string field contains the name of the file.  The value of the
388
symbol is the start address of the portion of the text section
389
corresponding to that file.
390
 
391
   Some compilers use the desc field to indicate the language of the
392
source file.  Sun's compilers started this usage, and the first
393
constants are derived from their documentation.  Languages added by
394
gcc/gdb start at 0x32 to avoid conflict with languages Sun may add in
395
the future.  A desc field with a value 0 indicates that no language has
396
been specified via this mechanism.
397
 
398
`N_SO_AS' (0x1)
399
     Assembly language
400
 
401
`N_SO_C'  (0x2)
402
     K&R traditional C
403
 
404
`N_SO_ANSI_C' (0x3)
405
     ANSI C
406
 
407
`N_SO_CC'  (0x4)
408
     C++
409
 
410
`N_SO_FORTRAN' (0x5)
411
     Fortran
412
 
413
`N_SO_PASCAL' (0x6)
414
     Pascal
415
 
416
`N_SO_FORTRAN90' (0x7)
417
     Fortran90
418
 
419
`N_SO_OBJC' (0x32)
420
     Objective-C
421
 
422
`N_SO_OBJCPLUS' (0x33)
423
     Objective-C++
424
 
425
   Some compilers (for example, GCC2 and SunOS4 `/bin/cc') also include
426
the directory in which the source was compiled, in a second `N_SO'
427
symbol preceding the one containing the file name.  This symbol can be
428
distinguished by the fact that it ends in a slash.  Code from the
429
`cfront' C++ compiler can have additional `N_SO' symbols for
430
nonexistent source files after the `N_SO' for the real source file;
431
these are believed to contain no useful information.
432
 
433
   For example:
434
 
435
     .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0     # 100 is N_SO
436
     .stabs "hello.c",100,0,0,Ltext0
437
             .text
438
     Ltext0:
439
 
440
   Instead of `N_SO' symbols, XCOFF uses a `.file' assembler directive
441
which assembles to a `C_FILE' symbol; explaining this in detail is
442
outside the scope of this document.
443
 
444
   If it is useful to indicate the end of a source file, this is done
445
with an `N_SO' symbol with an empty string for the name.  The value is
446
the address of the end of the text section for the file.  For some
447
systems, there is no indication of the end of a source file, and you
448
just need to figure it ended when you see an `N_SO' for a different
449
source file, or a symbol ending in `.o' (which at least some linkers
450
insert to mark the start of a new `.o' file).
451
 
452

453
File: stabs.info,  Node: Include Files,  Next: Line Numbers,  Prev: Source Files,  Up: Program Structure
454
 
455
2.3 Names of Include Files
456
==========================
457
 
458
There are several schemes for dealing with include files: the
459
traditional `N_SOL' approach, Sun's `N_BINCL' approach, and the XCOFF
460
`C_BINCL' approach (which despite the similar name has little in common
461
with `N_BINCL').
462
 
463
   An `N_SOL' symbol specifies which include file subsequent symbols
464
refer to.  The string field is the name of the file and the value is the
465
text address corresponding to the end of the previous include file and
466
the start of this one.  To specify the main source file again, use an
467
`N_SOL' symbol with the name of the main source file.
468
 
469
   The `N_BINCL' approach works as follows.  An `N_BINCL' symbol
470
specifies the start of an include file.  In an object file, only the
471
string is significant; the linker puts data into some of the other
472
fields.  The end of the include file is marked by an `N_EINCL' symbol
473
(which has no string field).  In an object file, there is no
474
significant data in the `N_EINCL' symbol.  `N_BINCL' and `N_EINCL' can
475
be nested.
476
 
477
   If the linker detects that two source files have identical stabs
478
between an `N_BINCL' and `N_EINCL' pair (as will generally be the case
479
for a header file), then it only puts out the stabs once.  Each
480
additional occurrence is replaced by an `N_EXCL' symbol.  I believe the
481
GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
482
ones which supports this feature.
483
 
484
   A linker which supports this feature will set the value of a
485
`N_BINCL' symbol to the total of all the characters in the stabs
486
strings included in the header file, omitting any file numbers.  The
487
value of an `N_EXCL' symbol is the same as the value of the `N_BINCL'
488
symbol it replaces.  This information can be used to match up `N_EXCL'
489
and `N_BINCL' symbols which have the same filename.  The `N_EINCL'
490
value, and the values of the other and description fields for all
491
three, appear to always be zero.
492
 
493
   For the start of an include file in XCOFF, use the `.bi' assembler
494
directive, which generates a `C_BINCL' symbol.  A `.ei' directive,
495
which generates a `C_EINCL' symbol, denotes the end of the include
496
file.  Both directives are followed by the name of the source file in
497
quotes, which becomes the string for the symbol.  The value of each
498
symbol, produced automatically by the assembler and linker, is the
499
offset into the executable of the beginning (inclusive, as you'd
500
expect) or end (inclusive, as you would not expect) of the portion of
501
the COFF line table that corresponds to this include file.  `C_BINCL'
502
and `C_EINCL' do not nest.
503
 
504

505
File: stabs.info,  Node: Line Numbers,  Next: Procedures,  Prev: Include Files,  Up: Program Structure
506
 
507
2.4 Line Numbers
508
================
509
 
510
An `N_SLINE' symbol represents the start of a source line.  The desc
511
field contains the line number and the value contains the code address
512
for the start of that source line.  On most machines the address is
513
absolute; for stabs in sections (*note Stab Sections::), it is relative
514
to the function in which the `N_SLINE' symbol occurs.
515
 
516
   GNU documents `N_DSLINE' and `N_BSLINE' symbols for line numbers in
517
the data or bss segments, respectively.  They are identical to
518
`N_SLINE' but are relocated differently by the linker.  They were
519
intended to be used to describe the source location of a variable
520
declaration, but I believe that GCC2 actually puts the line number in
521
the desc field of the stab for the variable itself.  GDB has been
522
ignoring these symbols (unless they contain a string field) since at
523
least GDB 3.5.
524
 
525
   For single source lines that generate discontiguous code, such as
526
flow of control statements, there may be more than one line number
527
entry for the same source line.  In this case there is a line number
528
entry at the start of each code range, each with the same line number.
529
 
530
   XCOFF does not use stabs for line numbers.  Instead, it uses COFF
531
line numbers (which are outside the scope of this document).  Standard
532
COFF line numbers cannot deal with include files, but in XCOFF this is
533
fixed with the `C_BINCL' method of marking include files (*note Include
534
Files::).
535
 
536

537
File: stabs.info,  Node: Procedures,  Next: Nested Procedures,  Prev: Line Numbers,  Up: Program Structure
538
 
539
2.5 Procedures
540
==============
541
 
542
All of the following stabs normally use the `N_FUN' symbol type.
543
However, Sun's `acc' compiler on SunOS4 uses `N_GSYM' and `N_STSYM',
544
which means that the value of the stab for the function is useless and
545
the debugger must get the address of the function from the non-stab
546
symbols instead.  On systems where non-stab symbols have leading
547
underscores, the stabs will lack underscores and the debugger needs to
548
know about the leading underscore to match up the stab and the non-stab
549
symbol.  BSD Fortran is said to use `N_FNAME' with the same
550
restriction; the value of the symbol is not useful (I'm not sure it
551
really does use this, because GDB doesn't handle this and no one has
552
complained).
553
 
554
   A function is represented by an `F' symbol descriptor for a global
555
(extern) function, and `f' for a static (local) function.  For a.out,
556
the value of the symbol is the address of the start of the function; it
557
is already relocated.  For stabs in ELF, the SunPRO compiler version
558
2.0.1 and GCC put out an address which gets relocated by the linker.
559
In a future release SunPRO is planning to put out zero, in which case
560
the address can be found from the ELF (non-stab) symbol.  Because
561
looking things up in the ELF symbols would probably be slow, I'm not
562
sure how to find which symbol of that name is the right one, and this
563
doesn't provide any way to deal with nested functions, it would
564
probably be better to make the value of the stab an address relative to
565
the start of the file, or just absolute.  See *Note ELF Linker
566
Relocation:: for more information on linker relocation of stabs in ELF
567
files.  For XCOFF, the stab uses the `C_FUN' storage class and the
568
value of the stab is meaningless; the address of the function can be
569
found from the csect symbol (XTY_LD/XMC_PR).
570
 
571
   The type information of the stab represents the return type of the
572
function; thus `foo:f5' means that foo is a function returning type 5.
573
There is no need to try to get the line number of the start of the
574
function from the stab for the function; it is in the next `N_SLINE'
575
symbol.
576
 
577
   Some compilers (such as Sun's Solaris compiler) support an extension
578
for specifying the types of the arguments.  I suspect this extension is
579
not used for old (non-prototyped) function definitions in C.  If the
580
extension is in use, the type information of the stab for the function
581
is followed by type information for each argument, with each argument
582
preceded by `;'.  An argument type of 0 means that additional arguments
583
are being passed, whose types and number may vary (`...' in ANSI C).
584
GDB has tolerated this extension (parsed the syntax, if not necessarily
585
used the information) since at least version 4.8; I don't know whether
586
all versions of dbx tolerate it.  The argument types given here are not
587
redundant with the symbols for the formal parameters (*note
588
Parameters::); they are the types of the arguments as they are passed,
589
before any conversions might take place.  For example, if a C function
590
which is declared without a prototype takes a `float' argument, the
591
value is passed as a `double' but then converted to a `float'.
592
Debuggers need to use the types given in the arguments when printing
593
values, but when calling the function they need to use the types given
594
in the symbol defining the function.
595
 
596
   If the return type and types of arguments of a function which is
597
defined in another source file are specified (i.e., a function
598
prototype in ANSI C), traditionally compilers emit no stab; the only
599
way for the debugger to find the information is if the source file
600
where the function is defined was also compiled with debugging symbols.
601
As an extension the Solaris compiler uses symbol descriptor `P'
602
followed by the return type of the function, followed by the arguments,
603
each preceded by `;', as in a stab with symbol descriptor `f' or `F'.
604
This use of symbol descriptor `P' can be distinguished from its use for
605
register parameters (*note Register Parameters::) by the fact that it
606
has symbol type `N_FUN'.
607
 
608
   The AIX documentation also defines symbol descriptor `J' as an
609
internal function.  I assume this means a function nested within another
610
function.  It also says symbol descriptor `m' is a module in Modula-2
611
or extended Pascal.
612
 
613
   Procedures (functions which do not return values) are represented as
614
functions returning the `void' type in C.  I don't see why this couldn't
615
be used for all languages (inventing a `void' type for this purpose if
616
necessary), but the AIX documentation defines `I', `P', and `Q' for
617
internal, global, and static procedures, respectively.  These symbol
618
descriptors are unusual in that they are not followed by type
619
information.
620
 
621
   The following example shows a stab for a function `main' which
622
returns type number `1'.  The `_main' specified for the value is a
623
reference to an assembler label which is used to fill in the start
624
address of the function.
625
 
626
     .stabs "main:F1",36,0,0,_main      # 36 is N_FUN
627
 
628
   The stab representing a procedure is located immediately following
629
the code of the procedure.  This stab is in turn directly followed by a
630
group of other stabs describing elements of the procedure.  These other
631
stabs describe the procedure's parameters, its block local variables,
632
and its block structure.
633
 
634
   If functions can appear in different sections, then the debugger may
635
not be able to find the end of a function.  Recent versions of GCC will
636
mark the end of a function with an `N_FUN' symbol with an empty string
637
for the name.  The value is the address of the end of the current
638
function.  Without such a symbol, there is no indication of the address
639
of the end of a function, and you must assume that it ended at the
640
starting address of the next function or at the end of the text section
641
for the program.
642
 
643

644
File: stabs.info,  Node: Nested Procedures,  Next: Block Structure,  Prev: Procedures,  Up: Program Structure
645
 
646
2.6 Nested Procedures
647
=====================
648
 
649
For any of the symbol descriptors representing procedures, after the
650
symbol descriptor and the type information is optionally a scope
651
specifier.  This consists of a comma, the name of the procedure, another
652
comma, and the name of the enclosing procedure.  The first name is local
653
to the scope specified, and seems to be redundant with the name of the
654
symbol (before the `:').  This feature is used by GCC, and presumably
655
Pascal, Modula-2, etc., compilers, for nested functions.
656
 
657
   If procedures are nested more than one level deep, only the
658
immediately containing scope is specified.  For example, this code:
659
 
660
     int
661
     foo (int x)
662
     {
663
       int bar (int y)
664
         {
665
           int baz (int z)
666
             {
667
               return x + y + z;
668
             }
669
           return baz (x + 2 * y);
670
         }
671
       return x + bar (3 * x);
672
     }
673
 
674
produces the stabs:
675
 
676
     .stabs "baz:f1,baz,bar",36,0,0,_baz.15         # 36 is N_FUN
677
     .stabs "bar:f1,bar,foo",36,0,0,_bar.12
678
     .stabs "foo:F1",36,0,0,_foo
679
 
680

681
File: stabs.info,  Node: Block Structure,  Next: Alternate Entry Points,  Prev: Nested Procedures,  Up: Program Structure
682
 
683
2.7 Block Structure
684
===================
685
 
686
The program's block structure is represented by the `N_LBRAC' (left
687
brace) and the `N_RBRAC' (right brace) stab types.  The variables
688
defined inside a block precede the `N_LBRAC' symbol for most compilers,
689
including GCC.  Other compilers, such as the Convex, Acorn RISC
690
machine, and Sun `acc' compilers, put the variables after the `N_LBRAC'
691
symbol.  The values of the `N_LBRAC' and `N_RBRAC' symbols are the
692
start and end addresses of the code of the block, respectively.  For
693
most machines, they are relative to the starting address of this source
694
file.  For the Gould NP1, they are absolute.  For stabs in sections
695
(*note Stab Sections::), they are relative to the function in which
696
they occur.
697
 
698
   The `N_LBRAC' and `N_RBRAC' stabs that describe the block scope of a
699
procedure are located after the `N_FUN' stab that represents the
700
procedure itself.
701
 
702
   Sun documents the desc field of `N_LBRAC' and `N_RBRAC' symbols as
703
containing the nesting level of the block.  However, dbx seems to not
704
care, and GCC always sets desc to zero.
705
 
706
   For XCOFF, block scope is indicated with `C_BLOCK' symbols.  If the
707
name of the symbol is `.bb', then it is the beginning of the block; if
708
the name of the symbol is `.be'; it is the end of the block.
709
 
710

711
File: stabs.info,  Node: Alternate Entry Points,  Prev: Block Structure,  Up: Program Structure
712
 
713
2.8 Alternate Entry Points
714
==========================
715
 
716
Some languages, like Fortran, have the ability to enter procedures at
717
some place other than the beginning.  One can declare an alternate entry
718
point.  The `N_ENTRY' stab is for this; however, the Sun FORTRAN
719
compiler doesn't use it.  According to AIX documentation, only the name
720
of a `C_ENTRY' stab is significant; the address of the alternate entry
721
point comes from the corresponding external symbol.  A previous
722
revision of this document said that the value of an `N_ENTRY' stab was
723
the address of the alternate entry point, but I don't know the source
724
for that information.
725
 
726

727
File: stabs.info,  Node: Constants,  Next: Variables,  Prev: Program Structure,  Up: Top
728
 
729
3 Constants
730
***********
731
 
732
The `c' symbol descriptor indicates that this stab represents a
733
constant.  This symbol descriptor is an exception to the general rule
734
that symbol descriptors are followed by type information.  Instead, it
735
is followed by `=' and one of the following:
736
 
737
`b VALUE'
738
     Boolean constant.  VALUE is a numeric value; I assume it is 0 for
739
     false or 1 for true.
740
 
741
`c VALUE'
742
     Character constant.  VALUE is the numeric value of the constant.
743
 
744
`e TYPE-INFORMATION , VALUE'
745
     Constant whose value can be represented as integral.
746
     TYPE-INFORMATION is the type of the constant, as it would appear
747
     after a symbol descriptor (*note String Field::).  VALUE is the
748
     numeric value of the constant.  GDB 4.9 does not actually get the
749
     right value if VALUE does not fit in a host `int', but it does not
750
     do anything violent, and future debuggers could be extended to
751
     accept integers of any size (whether unsigned or not).  This
752
     constant type is usually documented as being only for enumeration
753
     constants, but GDB has never imposed that restriction; I don't
754
     know about other debuggers.
755
 
756
`i VALUE'
757
     Integer constant.  VALUE is the numeric value.  The type is some
758
     sort of generic integer type (for GDB, a host `int'); to specify
759
     the type explicitly, use `e' instead.
760
 
761
`r VALUE'
762
     Real constant.  VALUE is the real value, which can be `INF'
763
     (optionally preceded by a sign) for infinity, `QNAN' for a quiet
764
     NaN (not-a-number), or `SNAN' for a signalling NaN.  If it is a
765
     normal number the format is that accepted by the C library function
766
     `atof'.
767
 
768
`s STRING'
769
     String constant.  STRING is a string enclosed in either `'' (in
770
     which case `'' characters within the string are represented as
771
     `\'' or `"' (in which case `"' characters within the string are
772
     represented as `\"').
773
 
774
`S TYPE-INFORMATION , ELEMENTS , BITS , PATTERN'
775
     Set constant.  TYPE-INFORMATION is the type of the constant, as it
776
     would appear after a symbol descriptor (*note String Field::).
777
     ELEMENTS is the number of elements in the set (does this means how
778
     many bits of PATTERN are actually used, which would be redundant
779
     with the type, or perhaps the number of bits set in PATTERN?  I
780
     don't get it), BITS is the number of bits in the constant (meaning
781
     it specifies the length of PATTERN, I think), and PATTERN is a
782
     hexadecimal representation of the set.  AIX documentation refers
783
     to a limit of 32 bytes, but I see no reason why this limit should
784
     exist.  This form could probably be used for arbitrary constants,
785
     not just sets; the only catch is that PATTERN should be understood
786
     to be target, not host, byte order and format.
787
 
788
   The boolean, character, string, and set constants are not supported
789
by GDB 4.9, but it ignores them.  GDB 4.8 and earlier gave an error
790
message and refused to read symbols from the file containing the
791
constants.
792
 
793
   The above information is followed by `;'.
794
 
795

796
File: stabs.info,  Node: Variables,  Next: Types,  Prev: Constants,  Up: Top
797
 
798
4 Variables
799
***********
800
 
801
Different types of stabs describe the various ways that variables can be
802
allocated: on the stack, globally, in registers, in common blocks,
803
statically, or as arguments to a function.
804
 
805
* Menu:
806
 
807
* Stack Variables::             Variables allocated on the stack.
808
* Global Variables::            Variables used by more than one source file.
809
* Register Variables::          Variables in registers.
810
* Common Blocks::               Variables statically allocated together.
811
* Statics::                     Variables local to one source file.
812
* Based Variables::             Fortran pointer based variables.
813
* Parameters::                  Variables for arguments to functions.
814
 
815

816
File: stabs.info,  Node: Stack Variables,  Next: Global Variables,  Up: Variables
817
 
818
4.1 Automatic Variables Allocated on the Stack
819
==============================================
820
 
821
If a variable's scope is local to a function and its lifetime is only as
822
long as that function executes (C calls such variables "automatic"), it
823
can be allocated in a register (*note Register Variables::) or on the
824
stack.
825
 
826
   Each variable allocated on the stack has a stab with the symbol
827
descriptor omitted.  Since type information should begin with a digit,
828
`-', or `(', only those characters precluded from being used for symbol
829
descriptors.  However, the Acorn RISC machine (ARM) is said to get this
830
wrong: it puts out a mere type definition here, without the preceding
831
`TYPE-NUMBER='.  This is a bad idea; there is no guarantee that type
832
descriptors are distinct from symbol descriptors.  Stabs for stack
833
variables use the `N_LSYM' stab type, or `C_LSYM' for XCOFF.
834
 
835
   The value of the stab is the offset of the variable within the local
836
variables.  On most machines this is an offset from the frame pointer
837
and is negative.  The location of the stab specifies which block it is
838
defined in; see *Note Block Structure::.
839
 
840
   For example, the following C code:
841
 
842
     int
843
     main ()
844
     {
845
       int x;
846
     }
847
 
848
   produces the following stabs:
849
 
850
     .stabs "main:F1",36,0,0,_main   # 36 is N_FUN
851
     .stabs "x:1",128,0,0,-12        # 128 is N_LSYM
852
     .stabn 192,0,0,LBB2             # 192 is N_LBRAC
853
     .stabn 224,0,0,LBE2             # 224 is N_RBRAC
854
 
855
   See *Note Procedures:: for more information on the `N_FUN' stab, and
856
*Note Block Structure:: for more information on the `N_LBRAC' and
857
`N_RBRAC' stabs.
858
 
859

860
File: stabs.info,  Node: Global Variables,  Next: Register Variables,  Prev: Stack Variables,  Up: Variables
861
 
862
4.2 Global Variables
863
====================
864
 
865
A variable whose scope is not specific to just one source file is
866
represented by the `G' symbol descriptor.  These stabs use the `N_GSYM'
867
stab type (C_GSYM for XCOFF).  The type information for the stab (*note
868
String Field::) gives the type of the variable.
869
 
870
   For example, the following source code:
871
 
872
     char g_foo = 'c';
873
 
874
yields the following assembly code:
875
 
876
     .stabs "g_foo:G2",32,0,0,0     # 32 is N_GSYM
877
          .global _g_foo
878
          .data
879
     _g_foo:
880
          .byte 99
881
 
882
   The address of the variable represented by the `N_GSYM' is not
883
contained in the `N_GSYM' stab.  The debugger gets this information
884
from the external symbol for the global variable.  In the example above,
885
the `.global _g_foo' and `_g_foo:' lines tell the assembler to produce
886
an external symbol.
887
 
888
   Some compilers, like GCC, output `N_GSYM' stabs only once, where the
889
variable is defined.  Other compilers, like SunOS4 /bin/cc, output a
890
`N_GSYM' stab for each compilation unit which references the variable.
891
 
892

893
File: stabs.info,  Node: Register Variables,  Next: Common Blocks,  Prev: Global Variables,  Up: Variables
894
 
895
4.3 Register Variables
896
======================
897
 
898
Register variables have their own stab type, `N_RSYM' (`C_RSYM' for
899
XCOFF), and their own symbol descriptor, `r'.  The stab's value is the
900
number of the register where the variable data will be stored.
901
 
902
   AIX defines a separate symbol descriptor `d' for floating point
903
registers.  This seems unnecessary; why not just just give floating
904
point registers different register numbers?  I have not verified whether
905
the compiler actually uses `d'.
906
 
907
   If the register is explicitly allocated to a global variable, but not
908
initialized, as in:
909
 
910
     register int g_bar asm ("%g5");
911
 
912
then the stab may be emitted at the end of the object file, with the
913
other bss symbols.
914
 
915

916
File: stabs.info,  Node: Common Blocks,  Next: Statics,  Prev: Register Variables,  Up: Variables
917
 
918
4.4 Common Blocks
919
=================
920
 
921
A common block is a statically allocated section of memory which can be
922
referred to by several source files.  It may contain several variables.
923
I believe Fortran is the only language with this feature.
924
 
925
   A `N_BCOMM' stab begins a common block and an `N_ECOMM' stab ends
926
it.  The only field that is significant in these two stabs is the
927
string, which names a normal (non-debugging) symbol that gives the
928
address of the common block.  According to IBM documentation, only the
929
`N_BCOMM' has the name of the common block (even though their compiler
930
actually puts it both places).
931
 
932
   The stabs for the members of the common block are between the
933
`N_BCOMM' and the `N_ECOMM'; the value of each stab is the offset
934
within the common block of that variable.  IBM uses the `C_ECOML' stab
935
type, and there is a corresponding `N_ECOML' stab type, but Sun's
936
Fortran compiler uses `N_GSYM' instead.  The variables within a common
937
block use the `V' symbol descriptor (I believe this is true of all
938
Fortran variables).  Other stabs (at least type declarations using
939
`C_DECL') can also be between the `N_BCOMM' and the `N_ECOMM'.
940
 
941

942
File: stabs.info,  Node: Statics,  Next: Based Variables,  Prev: Common Blocks,  Up: Variables
943
 
944
4.5 Static Variables
945
====================
946
 
947
Initialized static variables are represented by the `S' and `V' symbol
948
descriptors.  `S' means file scope static, and `V' means procedure
949
scope static.  One exception: in XCOFF, IBM's xlc compiler always uses
950
`V', and whether it is file scope or not is distinguished by whether
951
the stab is located within a function.
952
 
953
   In a.out files, `N_STSYM' means the data section, `N_FUN' means the
954
text section, and `N_LCSYM' means the bss section.  For those systems
955
with a read-only data section separate from the text section (Solaris),
956
`N_ROSYM' means the read-only data section.
957
 
958
   For example, the source lines:
959
 
960
     static const int var_const = 5;
961
     static int var_init = 2;
962
     static int var_noinit;
963
 
964
yield the following stabs:
965
 
966
     .stabs "var_const:S1",36,0,0,_var_const      # 36 is N_FUN
967
     ...
968
     .stabs "var_init:S1",38,0,0,_var_init        # 38 is N_STSYM
969
     ...
970
     .stabs "var_noinit:S1",40,0,0,_var_noinit    # 40 is N_LCSYM
971
 
972
   In XCOFF files, the stab type need not indicate the section;
973
`C_STSYM' can be used for all statics.  Also, each static variable is
974
enclosed in a static block.  A `C_BSTAT' (emitted with a `.bs'
975
assembler directive) symbol begins the static block; its value is the
976
symbol number of the csect symbol whose value is the address of the
977
static block, its section is the section of the variables in that
978
static block, and its name is `.bs'.  A `C_ESTAT' (emitted with a `.es'
979
assembler directive) symbol ends the static block; its name is `.es'
980
and its value and section are ignored.
981
 
982
   In ECOFF files, the storage class is used to specify the section, so
983
the stab type need not indicate the section.
984
 
985
   In ELF files, for the SunPRO compiler version 2.0.1, symbol
986
descriptor `S' means that the address is absolute (the linker relocates
987
it) and symbol descriptor `V' means that the address is relative to the
988
start of the relevant section for that compilation unit.  SunPRO has
989
plans to have the linker stop relocating stabs; I suspect that their the
990
debugger gets the address from the corresponding ELF (not stab) symbol.
991
I'm not sure how to find which symbol of that name is the right one.
992
The clean way to do all this would be to have the value of a symbol
993
descriptor `S' symbol be an offset relative to the start of the file,
994
just like everything else, but that introduces obvious compatibility
995
problems.  For more information on linker stab relocation, *Note ELF
996
Linker Relocation::.
997
 
998

999
File: stabs.info,  Node: Based Variables,  Next: Parameters,  Prev: Statics,  Up: Variables
1000
 
1001
4.6 Fortran Based Variables
1002
===========================
1003
 
1004
Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature
1005
which allows allocating arrays with `malloc', but which avoids blurring
1006
the line between arrays and pointers the way that C does.  In stabs
1007
such a variable uses the `b' symbol descriptor.
1008
 
1009
   For example, the Fortran declarations
1010
 
1011
     real foo, foo10(10), foo10_5(10,5)
1012
     pointer (foop, foo)
1013
     pointer (foo10p, foo10)
1014
     pointer (foo105p, foo10_5)
1015
 
1016
   produce the stabs
1017
 
1018
     foo:b6
1019
     foo10:bar3;1;10;6
1020
     foo10_5:bar3;1;5;ar3;1;10;6
1021
 
1022
   In this example, `real' is type 6 and type 3 is an integral type
1023
which is the type of the subscripts of the array (probably `integer').
1024
 
1025
   The `b' symbol descriptor is like `V' in that it denotes a
1026
statically allocated symbol whose scope is local to a function; see
1027
*Note Statics::.  The value of the symbol, instead of being the address
1028
of the variable itself, is the address of a pointer to that variable.
1029
So in the above example, the value of the `foo' stab is the address of
1030
a pointer to a real, the value of the `foo10' stab is the address of a
1031
pointer to a 10-element array of reals, and the value of the `foo10_5'
1032
stab is the address of a pointer to a 5-element array of 10-element
1033
arrays of reals.
1034
 
1035

1036
File: stabs.info,  Node: Parameters,  Prev: Based Variables,  Up: Variables
1037
 
1038
4.7 Parameters
1039
==============
1040
 
1041
Formal parameters to a function are represented by a stab (or sometimes
1042
two; see below) for each parameter.  The stabs are in the order in which
1043
the debugger should print the parameters (i.e., the order in which the
1044
parameters are declared in the source file).  The exact form of the stab
1045
depends on how the parameter is being passed.
1046
 
1047
   Parameters passed on the stack use the symbol descriptor `p' and the
1048
`N_PSYM' symbol type (or `C_PSYM' for XCOFF).  The value of the symbol
1049
is an offset used to locate the parameter on the stack; its exact
1050
meaning is machine-dependent, but on most machines it is an offset from
1051
the frame pointer.
1052
 
1053
   As a simple example, the code:
1054
 
1055
     main (argc, argv)
1056
          int argc;
1057
          char **argv;
1058
 
1059
   produces the stabs:
1060
 
1061
     .stabs "main:F1",36,0,0,_main                 # 36 is N_FUN
1062
     .stabs "argc:p1",160,0,0,68                   # 160 is N_PSYM
1063
     .stabs "argv:p20=*21=*2",160,0,0,72
1064
 
1065
   The type definition of `argv' is interesting because it contains
1066
several type definitions.  Type 21 is pointer to type 2 (char) and
1067
`argv' (type 20) is pointer to type 21.
1068
 
1069
   The following symbol descriptors are also said to go with `N_PSYM'.
1070
The value of the symbol is said to be an offset from the argument
1071
pointer (I'm not sure whether this is true or not).
1072
 
1073
     pP (<>)
1074
     pF Fortran function parameter
1075
     X  (function result variable)
1076
 
1077
* Menu:
1078
 
1079
* Register Parameters::
1080
* Local Variable Parameters::
1081
* Reference Parameters::
1082
* Conformant Arrays::
1083
 
1084

1085
File: stabs.info,  Node: Register Parameters,  Next: Local Variable Parameters,  Up: Parameters
1086
 
1087
4.7.1 Passing Parameters in Registers
1088
-------------------------------------
1089
 
1090
If the parameter is passed in a register, then traditionally there are
1091
two symbols for each argument:
1092
 
1093
     .stabs "arg:p1" . . .       ; N_PSYM
1094
     .stabs "arg:r1" . . .       ; N_RSYM
1095
 
1096
   Debuggers use the second one to find the value, and the first one to
1097
know that it is an argument.
1098
 
1099
   Because that approach is kind of ugly, some compilers use symbol
1100
descriptor `P' or `R' to indicate an argument which is in a register.
1101
Symbol type `C_RPSYM' is used in XCOFF and `N_RSYM' is used otherwise.
1102
The symbol's value is the register number.  `P' and `R' mean the same
1103
thing; the difference is that `P' is a GNU invention and `R' is an IBM
1104
(XCOFF) invention.  As of version 4.9, GDB should handle either one.
1105
 
1106
   There is at least one case where GCC uses a `p' and `r' pair rather
1107
than `P'; this is where the argument is passed in the argument list and
1108
then loaded into a register.
1109
 
1110
   According to the AIX documentation, symbol descriptor `D' is for a
1111
parameter passed in a floating point register.  This seems
1112
unnecessary--why not just use `R' with a register number which
1113
indicates that it's a floating point register?  I haven't verified
1114
whether the system actually does what the documentation indicates.
1115
 
1116
   On the sparc and hppa, for a `P' symbol whose type is a structure or
1117
union, the register contains the address of the structure.  On the
1118
sparc, this is also true of a `p' and `r' pair (using Sun `cc') or a
1119
`p' symbol.  However, if a (small) structure is really in a register,
1120
`r' is used.  And, to top it all off, on the hppa it might be a
1121
structure which was passed on the stack and loaded into a register and
1122
for which there is a `p' and `r' pair!  I believe that symbol
1123
descriptor `i' is supposed to deal with this case (it is said to mean
1124
"value parameter by reference, indirect access"; I don't know the
1125
source for this information), but I don't know details or what
1126
compilers or debuggers use it, if any (not GDB or GCC).  It is not
1127
clear to me whether this case needs to be dealt with differently than
1128
parameters passed by reference (*note Reference Parameters::).
1129
 
1130

1131
File: stabs.info,  Node: Local Variable Parameters,  Next: Reference Parameters,  Prev: Register Parameters,  Up: Parameters
1132
 
1133
4.7.2 Storing Parameters as Local Variables
1134
-------------------------------------------
1135
 
1136
There is a case similar to an argument in a register, which is an
1137
argument that is actually stored as a local variable.  Sometimes this
1138
happens when the argument was passed in a register and then the compiler
1139
stores it as a local variable.  If possible, the compiler should claim
1140
that it's in a register, but this isn't always done.
1141
 
1142
   If a parameter is passed as one type and converted to a smaller type
1143
by the prologue (for example, the parameter is declared as a `float',
1144
but the calling conventions specify that it is passed as a `double'),
1145
then GCC2 (sometimes) uses a pair of symbols.  The first symbol uses
1146
symbol descriptor `p' and the type which is passed.  The second symbol
1147
has the type and location which the parameter actually has after the
1148
prologue.  For example, suppose the following C code appears with no
1149
prototypes involved:
1150
 
1151
     void
1152
     subr (f)
1153
          float f;
1154
     {
1155
 
1156
   if `f' is passed as a double at stack offset 8, and the prologue
1157
converts it to a float in register number 0, then the stabs look like:
1158
 
1159
     .stabs "f:p13",160,0,3,8   # 160 is `N_PSYM', here 13 is `double'
1160
     .stabs "f:r12",64,0,3,0    # 64 is `N_RSYM', here 12 is `float'
1161
 
1162
   In both stabs 3 is the line number where `f' is declared (*note Line
1163
Numbers::).
1164
 
1165
   GCC, at least on the 960, has another solution to the same problem.
1166
It uses a single `p' symbol descriptor for an argument which is stored
1167
as a local variable but uses `N_LSYM' instead of `N_PSYM'.  In this
1168
case, the value of the symbol is an offset relative to the local
1169
variables for that function, not relative to the arguments; on some
1170
machines those are the same thing, but not on all.
1171
 
1172
   On the VAX or on other machines in which the calling convention
1173
includes the number of words of arguments actually passed, the debugger
1174
(GDB at least) uses the parameter symbols to keep track of whether it
1175
needs to print nameless arguments in addition to the formal parameters
1176
which it has printed because each one has a stab.  For example, in
1177
 
1178
     extern int fprintf (FILE *stream, char *format, ...);
1179
     ...
1180
     fprintf (stdout, "%d\n", x);
1181
 
1182
   there are stabs for `stream' and `format'.  On most machines, the
1183
debugger can only print those two arguments (because it has no way of
1184
knowing that additional arguments were passed), but on the VAX or other
1185
machines with a calling convention which indicates the number of words
1186
of arguments, the debugger can print all three arguments.  To do so,
1187
the parameter symbol (symbol descriptor `p') (not necessarily `r' or
1188
symbol descriptor omitted symbols) needs to contain the actual type as
1189
passed (for example, `double' not `float' if it is passed as a double
1190
and converted to a float).
1191
 
1192

1193
File: stabs.info,  Node: Reference Parameters,  Next: Conformant Arrays,  Prev: Local Variable Parameters,  Up: Parameters
1194
 
1195
4.7.3 Passing Parameters by Reference
1196
-------------------------------------
1197
 
1198
If the parameter is passed by reference (e.g., Pascal `VAR'
1199
parameters), then the symbol descriptor is `v' if it is in the argument
1200
list, or `a' if it in a register.  Other than the fact that these
1201
contain the address of the parameter rather than the parameter itself,
1202
they are identical to `p' and `R', respectively.  I believe `a' is an
1203
AIX invention; `v' is supported by all stabs-using systems as far as I
1204
know.
1205
 
1206

1207
File: stabs.info,  Node: Conformant Arrays,  Prev: Reference Parameters,  Up: Parameters
1208
 
1209
4.7.4 Passing Conformant Array Parameters
1210
-----------------------------------------
1211
 
1212
Conformant arrays are a feature of Modula-2, and perhaps other
1213
languages, in which the size of an array parameter is not known to the
1214
called function until run-time.  Such parameters have two stabs: a `x'
1215
for the array itself, and a `C', which represents the size of the
1216
array.  The value of the `x' stab is the offset in the argument list
1217
where the address of the array is stored (it this right?  it is a
1218
guess); the value of the `C' stab is the offset in the argument list
1219
where the size of the array (in elements? in bytes?) is stored.
1220
 
1221

1222
File: stabs.info,  Node: Types,  Next: Macro define and undefine,  Prev: Variables,  Up: Top
1223
 
1224
5 Defining Types
1225
****************
1226
 
1227
The examples so far have described types as references to previously
1228
defined types, or defined in terms of subranges of or pointers to
1229
previously defined types.  This chapter describes the other type
1230
descriptors that may follow the `=' in a type definition.
1231
 
1232
* Menu:
1233
 
1234
* Builtin Types::               Integers, floating point, void, etc.
1235
* Miscellaneous Types::         Pointers, sets, files, etc.
1236
* Cross-References::            Referring to a type not yet defined.
1237
* Subranges::                   A type with a specific range.
1238
* Arrays::                      An aggregate type of same-typed elements.
1239
* Strings::                     Like an array but also has a length.
1240
* Enumerations::                Like an integer but the values have names.
1241
* Structures::                  An aggregate type of different-typed elements.
1242
* Typedefs::                    Giving a type a name.
1243
* Unions::                      Different types sharing storage.
1244
* Function Types::
1245
 
1246

1247
File: stabs.info,  Node: Builtin Types,  Next: Miscellaneous Types,  Up: Types
1248
 
1249
5.1 Builtin Types
1250
=================
1251
 
1252
Certain types are built in (`int', `short', `void', `float', etc.); the
1253
debugger recognizes these types and knows how to handle them.  Thus,
1254
don't be surprised if some of the following ways of specifying builtin
1255
types do not specify everything that a debugger would need to know
1256
about the type--in some cases they merely specify enough information to
1257
distinguish the type from other types.
1258
 
1259
   The traditional way to define builtin types is convoluted, so new
1260
ways have been invented to describe them.  Sun's `acc' uses special
1261
builtin type descriptors (`b' and `R'), and IBM uses negative type
1262
numbers.  GDB accepts all three ways, as of version 4.8; dbx just
1263
accepts the traditional builtin types and perhaps one of the other two
1264
formats.  The following sections describe each of these formats.
1265
 
1266
* Menu:
1267
 
1268
* Traditional Builtin Types::   Put on your seat belts and prepare for kludgery
1269
* Builtin Type Descriptors::    Builtin types with special type descriptors
1270
* Negative Type Numbers::       Builtin types using negative type numbers
1271
 
1272

1273
File: stabs.info,  Node: Traditional Builtin Types,  Next: Builtin Type Descriptors,  Up: Builtin Types
1274
 
1275
5.1.1 Traditional Builtin Types
1276
-------------------------------
1277
 
1278
This is the traditional, convoluted method for defining builtin types.
1279
There are several classes of such type definitions: integer, floating
1280
point, and `void'.
1281
 
1282
* Menu:
1283
 
1284
* Traditional Integer Types::
1285
* Traditional Other Types::
1286
 
1287

1288
File: stabs.info,  Node: Traditional Integer Types,  Next: Traditional Other Types,  Up: Traditional Builtin Types
1289
 
1290
5.1.1.1 Traditional Integer Types
1291
.................................
1292
 
1293
Often types are defined as subranges of themselves.  If the bounding
1294
values fit within an `int', then they are given normally.  For example:
1295
 
1296
     .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0    # 128 is N_LSYM
1297
     .stabs "char:t2=r2;0;127;",128,0,0,0
1298
 
1299
   Builtin types can also be described as subranges of `int':
1300
 
1301
     .stabs "unsigned short:t6=r1;0;65535;",128,0,0,0
1302
 
1303
   If the lower bound of a subrange is 0 and the upper bound is -1, the
1304
type is an unsigned integral type whose bounds are too big to describe
1305
in an `int'.  Traditionally this is only used for `unsigned int' and
1306
`unsigned long':
1307
 
1308
     .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
1309
 
1310
   For larger types, GCC 2.4.5 puts out bounds in octal, with one or
1311
more leading zeroes.  In this case a negative bound consists of a number
1312
which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in
1313
the number (except the sign bit), and a positive bound is one which is a
1314
1 bit for each bit in the number (except possibly the sign bit).  All
1315
known versions of dbx and GDB version 4 accept this (at least in the
1316
sense of not refusing to process the file), but GDB 3.5 refuses to read
1317
the whole file containing such symbols.  So GCC 2.3.3 did not output the
1318
proper size for these types.  As an example of octal bounds, the string
1319
fields of the stabs for 64 bit integer types look like:
1320
 
1321
     long int:t3=r1;001000000000000000000000;000777777777777777777777;
1322
     long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777;
1323
 
1324
   If the lower bound of a subrange is 0 and the upper bound is
1325
negative, the type is an unsigned integral type whose size in bytes is
1326
the absolute value of the upper bound.  I believe this is a Convex
1327
convention for `unsigned long long'.
1328
 
1329
   If the lower bound of a subrange is negative and the upper bound is
1330
0, the type is a signed integral type whose size in bytes is the
1331
absolute value of the lower bound.  I believe this is a Convex
1332
convention for `long long'.  To distinguish this from a legitimate
1333
subrange, the type should be a subrange of itself.  I'm not sure whether
1334
this is the case for Convex.
1335
 
1336

1337
File: stabs.info,  Node: Traditional Other Types,  Prev: Traditional Integer Types,  Up: Traditional Builtin Types
1338
 
1339
5.1.1.2 Traditional Other Types
1340
...............................
1341
 
1342
If the upper bound of a subrange is 0 and the lower bound is positive,
1343
the type is a floating point type, and the lower bound of the subrange
1344
indicates the number of bytes in the type:
1345
 
1346
     .stabs "float:t12=r1;4;0;",128,0,0,0
1347
     .stabs "double:t13=r1;8;0;",128,0,0,0
1348
 
1349
   However, GCC writes `long double' the same way it writes `double',
1350
so there is no way to distinguish.
1351
 
1352
     .stabs "long double:t14=r1;8;0;",128,0,0,0
1353
 
1354
   Complex types are defined the same way as floating-point types;
1355
there is no way to distinguish a single-precision complex from a
1356
double-precision floating-point type.
1357
 
1358
   The C `void' type is defined as itself:
1359
 
1360
     .stabs "void:t15=15",128,0,0,0
1361
 
1362
   I'm not sure how a boolean type is represented.
1363
 
1364

1365
File: stabs.info,  Node: Builtin Type Descriptors,  Next: Negative Type Numbers,  Prev: Traditional Builtin Types,  Up: Builtin Types
1366
 
1367
5.1.2 Defining Builtin Types Using Builtin Type Descriptors
1368
-----------------------------------------------------------
1369
 
1370
This is the method used by Sun's `acc' for defining builtin types.
1371
These are the type descriptors to define builtin types:
1372
 
1373
`b SIGNED CHAR-FLAG WIDTH ; OFFSET ; NBITS ;'
1374
     Define an integral type.  SIGNED is `u' for unsigned or `s' for
1375
     signed.  CHAR-FLAG is `c' which indicates this is a character
1376
     type, or is omitted.  I assume this is to distinguish an integral
1377
     type from a character type of the same size, for example it might
1378
     make sense to set it for the C type `wchar_t' so the debugger can
1379
     print such variables differently (Solaris does not do this).  Sun
1380
     sets it on the C types `signed char' and `unsigned char' which
1381
     arguably is wrong.  WIDTH and OFFSET appear to be for small
1382
     objects stored in larger ones, for example a `short' in an `int'
1383
     register.  WIDTH is normally the number of bytes in the type.
1384
     OFFSET seems to always be zero.  NBITS is the number of bits in
1385
     the type.
1386
 
1387
     Note that type descriptor `b' used for builtin types conflicts with
1388
     its use for Pascal space types (*note Miscellaneous Types::); they
1389
     can be distinguished because the character following the type
1390
     descriptor will be a digit, `(', or `-' for a Pascal space type, or
1391
     `u' or `s' for a builtin type.
1392
 
1393
`w'
1394
     Documented by AIX to define a wide character type, but their
1395
     compiler actually uses negative type numbers (*note Negative Type
1396
     Numbers::).
1397
 
1398
`R FP-TYPE ; BYTES ;'
1399
     Define a floating point type.  FP-TYPE has one of the following
1400
     values:
1401
 
1402
    `1 (NF_SINGLE)'
1403
          IEEE 32-bit (single precision) floating point format.
1404
 
1405
    `2 (NF_DOUBLE)'
1406
          IEEE 64-bit (double precision) floating point format.
1407
 
1408
    `3 (NF_COMPLEX)'
1409
 
1410
    `4 (NF_COMPLEX16)'
1411
 
1412
    `5 (NF_COMPLEX32)'
1413
          These are for complex numbers.  A comment in the GDB source
1414
          describes them as Fortran `complex', `double complex', and
1415
          `complex*16', respectively, but what does that mean?  (i.e.,
1416
          Single precision?  Double precision?).
1417
 
1418
    `6 (NF_LDOUBLE)'
1419
          Long double.  This should probably only be used for Sun format
1420
          `long double', and new codes should be used for other floating
1421
          point formats (`NF_DOUBLE' can be used if a `long double' is
1422
          really just an IEEE double, of course).
1423
 
1424
     BYTES is the number of bytes occupied by the type.  This allows a
1425
     debugger to perform some operations with the type even if it
1426
     doesn't understand FP-TYPE.
1427
 
1428
`g TYPE-INFORMATION ; NBITS'
1429
     Documented by AIX to define a floating type, but their compiler
1430
     actually uses negative type numbers (*note Negative Type
1431
     Numbers::).
1432
 
1433
`c TYPE-INFORMATION ; NBITS'
1434
     Documented by AIX to define a complex type, but their compiler
1435
     actually uses negative type numbers (*note Negative Type
1436
     Numbers::).
1437
 
1438
   The C `void' type is defined as a signed integral type 0 bits long:
1439
     .stabs "void:t19=bs0;0;0",128,0,0,0
1440
   The Solaris compiler seems to omit the trailing semicolon in this
1441
case.  Getting sloppy in this way is not a swift move because if a type
1442
is embedded in a more complex expression it is necessary to be able to
1443
tell where it ends.
1444
 
1445
   I'm not sure how a boolean type is represented.
1446
 
1447

1448
File: stabs.info,  Node: Negative Type Numbers,  Prev: Builtin Type Descriptors,  Up: Builtin Types
1449
 
1450
5.1.3 Negative Type Numbers
1451
---------------------------
1452
 
1453
This is the method used in XCOFF for defining builtin types.  Since the
1454
debugger knows about the builtin types anyway, the idea of negative
1455
type numbers is simply to give a special type number which indicates
1456
the builtin type.  There is no stab defining these types.
1457
 
1458
   There are several subtle issues with negative type numbers.
1459
 
1460
   One is the size of the type.  A builtin type (for example the C types
1461
`int' or `long') might have different sizes depending on compiler
1462
options, the target architecture, the ABI, etc.  This issue doesn't
1463
come up for IBM tools since (so far) they just target the RS/6000; the
1464
sizes indicated below for each size are what the IBM RS/6000 tools use.
1465
To deal with differing sizes, either define separate negative type
1466
numbers for each size (which works but requires changing the debugger,
1467
and, unless you get both AIX dbx and GDB to accept the change,
1468
introduces an incompatibility), or use a type attribute (*note String
1469
Field::) to define a new type with the appropriate size (which merely
1470
requires a debugger which understands type attributes, like AIX dbx or
1471
GDB).  For example,
1472
 
1473
     .stabs "boolean:t10=@s8;-16",128,0,0,0
1474
 
1475
   defines an 8-bit boolean type, and
1476
 
1477
     .stabs "boolean:t10=@s64;-16",128,0,0,0
1478
 
1479
   defines a 64-bit boolean type.
1480
 
1481
   A similar issue is the format of the type.  This comes up most often
1482
for floating-point types, which could have various formats (particularly
1483
extended doubles, which vary quite a bit even among IEEE systems).
1484
Again, it is best to define a new negative type number for each
1485
different format; changing the format based on the target system has
1486
various problems.  One such problem is that the Alpha has both VAX and
1487
IEEE floating types.  One can easily imagine one library using the VAX
1488
types and another library in the same executable using the IEEE types.
1489
Another example is that the interpretation of whether a boolean is true
1490
or false can be based on the least significant bit, most significant
1491
bit, whether it is zero, etc., and different compilers (or different
1492
options to the same compiler) might provide different kinds of boolean.
1493
 
1494
   The last major issue is the names of the types.  The name of a given
1495
type depends _only_ on the negative type number given; these do not
1496
vary depending on the language, the target system, or anything else.
1497
One can always define separate type numbers--in the following list you
1498
will see for example separate `int' and `integer*4' types which are
1499
identical except for the name.  But compatibility can be maintained by
1500
not inventing new negative type numbers and instead just defining a new
1501
type with a new name.  For example:
1502
 
1503
     .stabs "CARDINAL:t10=-8",128,0,0,0
1504
 
1505
   Here is the list of negative type numbers.  The phrase "integral
1506
type" is used to mean twos-complement (I strongly suspect that all
1507
machines which use stabs use twos-complement; most machines use
1508
twos-complement these days).
1509
 
1510
`-1'
1511
     `int', 32 bit signed integral type.
1512
 
1513
`-2'
1514
     `char', 8 bit type holding a character.   Both GDB and dbx on AIX
1515
     treat this as signed.  GCC uses this type whether `char' is signed
1516
     or not, which seems like a bad idea.  The AIX compiler (`xlc')
1517
     seems to avoid this type; it uses -5 instead for `char'.
1518
 
1519
`-3'
1520
     `short', 16 bit signed integral type.
1521
 
1522
`-4'
1523
     `long', 32 bit signed integral type.
1524
 
1525
`-5'
1526
     `unsigned char', 8 bit unsigned integral type.
1527
 
1528
`-6'
1529
     `signed char', 8 bit signed integral type.
1530
 
1531
`-7'
1532
     `unsigned short', 16 bit unsigned integral type.
1533
 
1534
`-8'
1535
     `unsigned int', 32 bit unsigned integral type.
1536
 
1537
`-9'
1538
     `unsigned', 32 bit unsigned integral type.
1539
 
1540
`-10'
1541
     `unsigned long', 32 bit unsigned integral type.
1542
 
1543
`-11'
1544
     `void', type indicating the lack of a value.
1545
 
1546
`-12'
1547
     `float', IEEE single precision.
1548
 
1549
`-13'
1550
     `double', IEEE double precision.
1551
 
1552
`-14'
1553
     `long double', IEEE double precision.  The compiler claims the size
1554
     will increase in a future release, and for binary compatibility
1555
     you have to avoid using `long double'.  I hope when they increase
1556
     it they use a new negative type number.
1557
 
1558
`-15'
1559
     `integer'.  32 bit signed integral type.
1560
 
1561
`-16'
1562
     `boolean'.  32 bit type.  GDB and GCC assume that zero is false,
1563
     one is true, and other values have unspecified meaning.  I hope
1564
     this agrees with how the IBM tools use the type.
1565
 
1566
`-17'
1567
     `short real'.  IEEE single precision.
1568
 
1569
`-18'
1570
     `real'.  IEEE double precision.
1571
 
1572
`-19'
1573
     `stringptr'.  *Note Strings::.
1574
 
1575
`-20'
1576
     `character', 8 bit unsigned character type.
1577
 
1578
`-21'
1579
     `logical*1', 8 bit type.  This Fortran type has a split
1580
     personality in that it is used for boolean variables, but can also
1581
     be used for unsigned integers.  0 is false, 1 is true, and other
1582
     values are non-boolean.
1583
 
1584
`-22'
1585
     `logical*2', 16 bit type.  This Fortran type has a split
1586
     personality in that it is used for boolean variables, but can also
1587
     be used for unsigned integers.  0 is false, 1 is true, and other
1588
     values are non-boolean.
1589
 
1590
`-23'
1591
     `logical*4', 32 bit type.  This Fortran type has a split
1592
     personality in that it is used for boolean variables, but can also
1593
     be used for unsigned integers.  0 is false, 1 is true, and other
1594
     values are non-boolean.
1595
 
1596
`-24'
1597
     `logical', 32 bit type.  This Fortran type has a split personality
1598
     in that it is used for boolean variables, but can also be used for
1599
     unsigned integers.  0 is false, 1 is true, and other values are
1600
     non-boolean.
1601
 
1602
`-25'
1603
     `complex'.  A complex type consisting of two IEEE single-precision
1604
     floating point values.
1605
 
1606
`-26'
1607
     `complex'.  A complex type consisting of two IEEE double-precision
1608
     floating point values.
1609
 
1610
`-27'
1611
     `integer*1', 8 bit signed integral type.
1612
 
1613
`-28'
1614
     `integer*2', 16 bit signed integral type.
1615
 
1616
`-29'
1617
     `integer*4', 32 bit signed integral type.
1618
 
1619
`-30'
1620
     `wchar'.  Wide character, 16 bits wide, unsigned (what format?
1621
     Unicode?).
1622
 
1623
`-31'
1624
     `long long', 64 bit signed integral type.
1625
 
1626
`-32'
1627
     `unsigned long long', 64 bit unsigned integral type.
1628
 
1629
`-33'
1630
     `logical*8', 64 bit unsigned integral type.
1631
 
1632
`-34'
1633
     `integer*8', 64 bit signed integral type.
1634
 
1635

1636
File: stabs.info,  Node: Miscellaneous Types,  Next: Cross-References,  Prev: Builtin Types,  Up: Types
1637
 
1638
5.2 Miscellaneous Types
1639
=======================
1640
 
1641
`b TYPE-INFORMATION ; BYTES'
1642
     Pascal space type.  This is documented by IBM; what does it mean?
1643
 
1644
     This use of the `b' type descriptor can be distinguished from its
1645
     use for builtin integral types (*note Builtin Type Descriptors::)
1646
     because the character following the type descriptor is always a
1647
     digit, `(', or `-'.
1648
 
1649
`B TYPE-INFORMATION'
1650
     A volatile-qualified version of TYPE-INFORMATION.  This is a Sun
1651
     extension.  References and stores to a variable with a
1652
     volatile-qualified type must not be optimized or cached; they must
1653
     occur as the user specifies them.
1654
 
1655
`d TYPE-INFORMATION'
1656
     File of type TYPE-INFORMATION.  As far as I know this is only used
1657
     by Pascal.
1658
 
1659
`k TYPE-INFORMATION'
1660
     A const-qualified version of TYPE-INFORMATION.  This is a Sun
1661
     extension.  A variable with a const-qualified type cannot be
1662
     modified.
1663
 
1664
`M TYPE-INFORMATION ; LENGTH'
1665
     Multiple instance type.  The type seems to composed of LENGTH
1666
     repetitions of TYPE-INFORMATION, for example `character*3' is
1667
     represented by `M-2;3', where `-2' is a reference to a character
1668
     type (*note Negative Type Numbers::).  I'm not sure how this
1669
     differs from an array.  This appears to be a Fortran feature.
1670
     LENGTH is a bound, like those in range types; see *Note
1671
     Subranges::.
1672
 
1673
`S TYPE-INFORMATION'
1674
     Pascal set type.  TYPE-INFORMATION must be a small type such as an
1675
     enumeration or a subrange, and the type is a bitmask whose length
1676
     is specified by the number of elements in TYPE-INFORMATION.
1677
 
1678
     In CHILL, if it is a bitstring instead of a set, also use the `S'
1679
     type attribute (*note String Field::).
1680
 
1681
`* TYPE-INFORMATION'
1682
     Pointer to TYPE-INFORMATION.
1683
 
1684

1685
File: stabs.info,  Node: Cross-References,  Next: Subranges,  Prev: Miscellaneous Types,  Up: Types
1686
 
1687
5.3 Cross-References to Other Types
1688
===================================
1689
 
1690
A type can be used before it is defined; one common way to deal with
1691
that situation is just to use a type reference to a type which has not
1692
yet been defined.
1693
 
1694
   Another way is with the `x' type descriptor, which is followed by
1695
`s' for a structure tag, `u' for a union tag, or `e' for a enumerator
1696
tag, followed by the name of the tag, followed by `:'.  If the name
1697
contains `::' between a `<' and `>' pair (for C++ templates), such a
1698
`::' does not end the name--only a single `:' ends the name; see *Note
1699
Nested Symbols::.
1700
 
1701
   For example, the following C declarations:
1702
 
1703
     struct foo;
1704
     struct foo *bar;
1705
 
1706
produce:
1707
 
1708
     .stabs "bar:G16=*17=xsfoo:",32,0,0,0
1709
 
1710
   Not all debuggers support the `x' type descriptor, so on some
1711
machines GCC does not use it.  I believe that for the above example it
1712
would just emit a reference to type 17 and never define it, but I
1713
haven't verified that.
1714
 
1715
   Modula-2 imported types, at least on AIX, use the `i' type
1716
descriptor, which is followed by the name of the module from which the
1717
type is imported, followed by `:', followed by the name of the type.
1718
There is then optionally a comma followed by type information for the
1719
type.  This differs from merely naming the type (*note Typedefs::) in
1720
that it identifies the module; I don't understand whether the name of
1721
the type given here is always just the same as the name we are giving
1722
it, or whether this type descriptor is used with a nameless stab (*note
1723
String Field::), or what.  The symbol ends with `;'.
1724
 
1725

1726
File: stabs.info,  Node: Subranges,  Next: Arrays,  Prev: Cross-References,  Up: Types
1727
 
1728
5.4 Subrange Types
1729
==================
1730
 
1731
The `r' type descriptor defines a type as a subrange of another type.
1732
It is followed by type information for the type of which it is a
1733
subrange, a semicolon, an integral lower bound, a semicolon, an
1734
integral upper bound, and a semicolon.  The AIX documentation does not
1735
specify the trailing semicolon, in an effort to specify array indexes
1736
more cleanly, but a subrange which is not an array index has always
1737
included a trailing semicolon (*note Arrays::).
1738
 
1739
   Instead of an integer, either bound can be one of the following:
1740
 
1741
`A OFFSET'
1742
     The bound is passed by reference on the stack at offset OFFSET
1743
     from the argument list.  *Note Parameters::, for more information
1744
     on such offsets.
1745
 
1746
`T OFFSET'
1747
     The bound is passed by value on the stack at offset OFFSET from
1748
     the argument list.
1749
 
1750
`a REGISTER-NUMBER'
1751
     The bound is passed by reference in register number
1752
     REGISTER-NUMBER.
1753
 
1754
`t REGISTER-NUMBER'
1755
     The bound is passed by value in register number REGISTER-NUMBER.
1756
 
1757
`J'
1758
     There is no bound.
1759
 
1760
   Subranges are also used for builtin types; see *Note Traditional
1761
Builtin Types::.
1762
 
1763

1764
File: stabs.info,  Node: Arrays,  Next: Strings,  Prev: Subranges,  Up: Types
1765
 
1766
5.5 Array Types
1767
===============
1768
 
1769
Arrays use the `a' type descriptor.  Following the type descriptor is
1770
the type of the index and the type of the array elements.  If the index
1771
type is a range type, it ends in a semicolon; otherwise (for example,
1772
if it is a type reference), there does not appear to be any way to tell
1773
where the types are separated.  In an effort to clean up this mess, IBM
1774
documents the two types as being separated by a semicolon, and a range
1775
type as not ending in a semicolon (but this is not right for range
1776
types which are not array indexes, *note Subranges::).  I think
1777
probably the best solution is to specify that a semicolon ends a range
1778
type, and that the index type and element type of an array are
1779
separated by a semicolon, but that if the index type is a range type,
1780
the extra semicolon can be omitted.  GDB (at least through version 4.9)
1781
doesn't support any kind of index type other than a range anyway; I'm
1782
not sure about dbx.
1783
 
1784
   It is well established, and widely used, that the type of the index,
1785
unlike most types found in the stabs, is merely a type definition, not
1786
type information (*note String Field::) (that is, it need not start with
1787
`TYPE-NUMBER=' if it is defining a new type).  According to a comment
1788
in GDB, this is also true of the type of the array elements; it gives
1789
`ar1;1;10;ar1;1;10;4' as a legitimate way to express a two dimensional
1790
array.  According to AIX documentation, the element type must be type
1791
information.  GDB accepts either.
1792
 
1793
   The type of the index is often a range type, expressed as the type
1794
descriptor `r' and some parameters.  It defines the size of the array.
1795
In the example below, the range `r1;0;2;' defines an index type which
1796
is a subrange of type 1 (integer), with a lower bound of 0 and an upper
1797
bound of 2.  This defines the valid range of subscripts of a
1798
three-element C array.
1799
 
1800
   For example, the definition:
1801
 
1802
     char char_vec[3] = {'a','b','c'};
1803
 
1804
produces the output:
1805
 
1806
     .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
1807
          .global _char_vec
1808
          .align 4
1809
     _char_vec:
1810
          .byte 97
1811
          .byte 98
1812
          .byte 99
1813
 
1814
   If an array is "packed", the elements are spaced more closely than
1815
normal, saving memory at the expense of speed.  For example, an array
1816
of 3-byte objects might, if unpacked, have each element aligned on a
1817
4-byte boundary, but if packed, have no padding.  One way to specify
1818
that something is packed is with type attributes (*note String
1819
Field::).  In the case of arrays, another is to use the `P' type
1820
descriptor instead of `a'.  Other than specifying a packed array, `P'
1821
is identical to `a'.
1822
 
1823
   An open array is represented by the `A' type descriptor followed by
1824
type information specifying the type of the array elements.
1825
 
1826
   An N-dimensional dynamic array is represented by
1827
 
1828
     D DIMENSIONS ; TYPE-INFORMATION
1829
 
1830
   DIMENSIONS is the number of dimensions; TYPE-INFORMATION specifies
1831
the type of the array elements.
1832
 
1833
   A subarray of an N-dimensional array is represented by
1834
 
1835
     E DIMENSIONS ; TYPE-INFORMATION
1836
 
1837
   DIMENSIONS is the number of dimensions; TYPE-INFORMATION specifies
1838
the type of the array elements.
1839
 
1840

1841
File: stabs.info,  Node: Strings,  Next: Enumerations,  Prev: Arrays,  Up: Types
1842
 
1843
5.6 Strings
1844
===========
1845
 
1846
Some languages, like C or the original Pascal, do not have string types,
1847
they just have related things like arrays of characters.  But most
1848
Pascals and various other languages have string types, which are
1849
indicated as follows:
1850
 
1851
`n TYPE-INFORMATION ; BYTES'
1852
     BYTES is the maximum length.  I'm not sure what TYPE-INFORMATION
1853
     is; I suspect that it means that this is a string of
1854
     TYPE-INFORMATION (thus allowing a string of integers, a string of
1855
     wide characters, etc., as well as a string of characters).  Not
1856
     sure what the format of this type is.  This is an AIX feature.
1857
 
1858
`z TYPE-INFORMATION ; BYTES'
1859
     Just like `n' except that this is a gstring, not an ordinary
1860
     string.  I don't know the difference.
1861
 
1862
`N'
1863
     Pascal Stringptr.  What is this?  This is an AIX feature.
1864
 
1865
   Languages, such as CHILL which have a string type which is basically
1866
just an array of characters use the `S' type attribute (*note String
1867
Field::).
1868
 
1869

1870
File: stabs.info,  Node: Enumerations,  Next: Structures,  Prev: Strings,  Up: Types
1871
 
1872
5.7 Enumerations
1873
================
1874
 
1875
Enumerations are defined with the `e' type descriptor.
1876
 
1877
   The source line below declares an enumeration type at file scope.
1878
The type definition is located after the `N_RBRAC' that marks the end of
1879
the previous procedure's block scope, and before the `N_FUN' that marks
1880
the beginning of the next procedure's block scope.  Therefore it does
1881
not describe a block local symbol, but a file local one.
1882
 
1883
   The source line:
1884
 
1885
     enum e_places {first,second=3,last};
1886
 
1887
generates the following stab:
1888
 
1889
     .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
1890
 
1891
   The symbol descriptor (`T') says that the stab describes a
1892
structure, enumeration, or union tag.  The type descriptor `e',
1893
following the `22=' of the type definition narrows it down to an
1894
enumeration type.  Following the `e' is a list of the elements of the
1895
enumeration.  The format is `NAME:VALUE,'.  The list of elements ends
1896
with `;'.  The fact that VALUE is specified as an integer can cause
1897
problems if the value is large.  GCC 2.5.2 tries to output it in octal
1898
in that case with a leading zero, which is probably a good thing,
1899
although GDB 4.11 supports octal only in cases where decimal is
1900
perfectly good.  Negative decimal values are supported by both GDB and
1901
dbx.
1902
 
1903
   There is no standard way to specify the size of an enumeration type;
1904
it is determined by the architecture (normally all enumerations types
1905
are 32 bits).  Type attributes can be used to specify an enumeration
1906
type of another size for debuggers which support them; see *Note String
1907
Field::.
1908
 
1909
   Enumeration types are unusual in that they define symbols for the
1910
enumeration values (`first', `second', and `third' in the above
1911
example), and even though these symbols are visible in the file as a
1912
whole (rather than being in a more local namespace like structure
1913
member names), they are defined in the type definition for the
1914
enumeration type rather than each having their own symbol.  In order to
1915
be fast, GDB will only get symbols from such types (in its initial scan
1916
of the stabs) if the type is the first thing defined after a `T' or `t'
1917
symbol descriptor (the above example fulfills this requirement).  If
1918
the type does not have a name, the compiler should emit it in a
1919
nameless stab (*note String Field::); GCC does this.
1920
 
1921

1922
File: stabs.info,  Node: Structures,  Next: Typedefs,  Prev: Enumerations,  Up: Types
1923
 
1924
5.8 Structures
1925
==============
1926
 
1927
The encoding of structures in stabs can be shown with an example.
1928
 
1929
   The following source code declares a structure tag and defines an
1930
instance of the structure in global scope. Then a `typedef' equates the
1931
structure tag with a new type.  Separate stabs are generated for the
1932
structure tag, the structure `typedef', and the structure instance.  The
1933
stabs for the tag and the `typedef' are emitted when the definitions are
1934
encountered.  Since the structure elements are not initialized, the
1935
stab and code for the structure variable itself is located at the end
1936
of the program in the bss section.
1937
 
1938
     struct s_tag {
1939
       int   s_int;
1940
       float s_float;
1941
       char  s_char_vec[8];
1942
       struct s_tag* s_next;
1943
     } g_an_s;
1944
 
1945
     typedef struct s_tag s_typedef;
1946
 
1947
   The structure tag has an `N_LSYM' stab type because, like the
1948
enumeration, the symbol has file scope.  Like the enumeration, the
1949
symbol descriptor is `T', for enumeration, structure, or tag type.  The
1950
type descriptor `s' following the `16=' of the type definition narrows
1951
the symbol type to structure.
1952
 
1953
   Following the `s' type descriptor is the number of bytes the
1954
structure occupies, followed by a description of each structure element.
1955
The structure element descriptions are of the form `NAME:TYPE, BIT
1956
OFFSET FROM THE START OF THE STRUCT, NUMBER OF BITS IN THE ELEMENT'.
1957
 
1958
     # 128 is N_LSYM
1959
     .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;
1960
             s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
1961
 
1962
   In this example, the first two structure elements are previously
1963
defined types.  For these, the type following the `NAME:' part of the
1964
element description is a simple type reference.  The other two structure
1965
elements are new types.  In this case there is a type definition
1966
embedded after the `NAME:'.  The type definition for the array element
1967
looks just like a type definition for a stand-alone array.  The
1968
`s_next' field is a pointer to the same kind of structure that the
1969
field is an element of.  So the definition of structure type 16
1970
contains a type definition for an element which is a pointer to type 16.
1971
 
1972
   If a field is a static member (this is a C++ feature in which a
1973
single variable appears to be a field of every structure of a given
1974
type) it still starts out with the field name, a colon, and the type,
1975
but then instead of a comma, bit position, comma, and bit size, there
1976
is a colon followed by the name of the variable which each such field
1977
refers to.
1978
 
1979
   If the structure has methods (a C++ feature), they follow the
1980
non-method fields; see *Note Cplusplus::.
1981
 
1982

1983
File: stabs.info,  Node: Typedefs,  Next: Unions,  Prev: Structures,  Up: Types
1984
 
1985
5.9 Giving a Type a Name
1986
========================
1987
 
1988
To give a type a name, use the `t' symbol descriptor.  The type is
1989
specified by the type information (*note String Field::) for the stab.
1990
For example,
1991
 
1992
     .stabs "s_typedef:t16",128,0,0,0     # 128 is N_LSYM
1993
 
1994
   specifies that `s_typedef' refers to type number 16.  Such stabs
1995
have symbol type `N_LSYM' (or `C_DECL' for XCOFF).  (The Sun
1996
documentation mentions using `N_GSYM' in some cases).
1997
 
1998
   If you are specifying the tag name for a structure, union, or
1999
enumeration, use the `T' symbol descriptor instead.  I believe C is the
2000
only language with this feature.
2001
 
2002
   If the type is an opaque type (I believe this is a Modula-2 feature),
2003
AIX provides a type descriptor to specify it.  The type descriptor is
2004
`o' and is followed by a name.  I don't know what the name means--is it
2005
always the same as the name of the type, or is this type descriptor
2006
used with a nameless stab (*note String Field::)?  There optionally
2007
follows a comma followed by type information which defines the type of
2008
this type.  If omitted, a semicolon is used in place of the comma and
2009
the type information, and the type is much like a generic pointer
2010
type--it has a known size but little else about it is specified.
2011
 
2012

2013
File: stabs.info,  Node: Unions,  Next: Function Types,  Prev: Typedefs,  Up: Types
2014
 
2015
5.10 Unions
2016
===========
2017
 
2018
     union u_tag {
2019
       int  u_int;
2020
       float u_float;
2021
       char* u_char;
2022
     } an_u;
2023
 
2024
   This code generates a stab for a union tag and a stab for a union
2025
variable.  Both use the `N_LSYM' stab type.  If a union variable is
2026
scoped locally to the procedure in which it is defined, its stab is
2027
located immediately preceding the `N_LBRAC' for the procedure's block
2028
start.
2029
 
2030
   The stab for the union tag, however, is located preceding the code
2031
for the procedure in which it is defined.  The stab type is `N_LSYM'.
2032
This would seem to imply that the union type is file scope, like the
2033
struct type `s_tag'.  This is not true.  The contents and position of
2034
the stab for `u_type' do not convey any information about its procedure
2035
local scope.
2036
 
2037
     # 128 is N_LSYM
2038
     .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
2039
            128,0,0,0
2040
 
2041
   The symbol descriptor `T', following the `name:' means that the stab
2042
describes an enumeration, structure, or union tag.  The type descriptor
2043
`u', following the `23=' of the type definition, narrows it down to a
2044
union type definition.  Following the `u' is the number of bytes in the
2045
union.  After that is a list of union element descriptions.  Their
2046
format is `NAME:TYPE, BIT OFFSET INTO THE UNION, NUMBER OF BYTES FOR
2047
THE ELEMENT;'.
2048
 
2049
   The stab for the union variable is:
2050
 
2051
     .stabs "an_u:23",128,0,0,-20     # 128 is N_LSYM
2052
 
2053
   `-20' specifies where the variable is stored (*note Stack
2054
Variables::).
2055
 
2056

2057
File: stabs.info,  Node: Function Types,  Prev: Unions,  Up: Types
2058
 
2059
5.11 Function Types
2060
===================
2061
 
2062
Various types can be defined for function variables.  These types are
2063
not used in defining functions (*note Procedures::); they are used for
2064
things like pointers to functions.
2065
 
2066
   The simple, traditional, type is type descriptor `f' is followed by
2067
type information for the return type of the function, followed by a
2068
semicolon.
2069
 
2070
   This does not deal with functions for which the number and types of
2071
the parameters are part of the type, as in Modula-2 or ANSI C.  AIX
2072
provides extensions to specify these, using the `f', `F', `p', and `R'
2073
type descriptors.
2074
 
2075
   First comes the type descriptor.  If it is `f' or `F', this type
2076
involves a function rather than a procedure, and the type information
2077
for the return type of the function follows, followed by a comma.  Then
2078
comes the number of parameters to the function and a semicolon.  Then,
2079
for each parameter, there is the name of the parameter followed by a
2080
colon (this is only present for type descriptors `R' and `F' which
2081
represent Pascal function or procedure parameters), type information
2082
for the parameter, a comma, 0 if passed by reference or 1 if passed by
2083
value, and a semicolon.  The type definition ends with a semicolon.
2084
 
2085
   For example, this variable definition:
2086
 
2087
     int (*g_pf)();
2088
 
2089
generates the following code:
2090
 
2091
     .stabs "g_pf:G24=*25=f1",32,0,0,0
2092
         .common _g_pf,4,"bss"
2093
 
2094
   The variable defines a new type, 24, which is a pointer to another
2095
new type, 25, which is a function returning `int'.
2096
 
2097

2098
File: stabs.info,  Node: Macro define and undefine,  Next: Symbol Tables,  Prev: Types,  Up: Top
2099
 
2100
6 Representation of #define and #undef
2101
**************************************
2102
 
2103
This section describes the stabs support for macro define and undefine
2104
information, supported on some systems.  (e.g., with `-g3' `-gstabs'
2105
when using GCC).
2106
 
2107
   A `#define MACRO-NAME MACRO-BODY' is represented with an
2108
`N_MAC_DEFINE' stab with a string field of `MACRO-NAME MACRO-BODY'.
2109
 
2110
   An `#undef MACRO-NAME' is represented with an `N_MAC_UNDEF' stabs
2111
with a string field of simply `MACRO-NAME'.
2112
 
2113
   For both `N_MAC_DEFINE' and `N_MAC_UNDEF', the desc field is the
2114
line number within the file where the corresponding `#define' or
2115
`#undef' occurred.
2116
 
2117
   For example, the following C code:
2118
 
2119
         #define NONE   42
2120
         #define TWO(a, b)      (a + (a) + 2 * b)
2121
         #define ONE(c) (c + 19)
2122
 
2123
         main(int argc, char *argv[])
2124
         {
2125
           func(NONE, TWO(10, 11));
2126
           func(NONE, ONE(23));
2127
 
2128
         #undef ONE
2129
         #define ONE(c) (c + 23)
2130
 
2131
           func(NONE, ONE(-23));
2132
 
2133
           return (0);
2134
         }
2135
 
2136
         int global;
2137
 
2138
         func(int arg1, int arg2)
2139
         {
2140
           global = arg1 + arg2;
2141
         }
2142
 
2143
produces the following stabs (as well as many others):
2144
 
2145
         .stabs "NONE 42",54,0,1,0
2146
         .stabs "TWO(a,b) (a + (a) + 2 * b)",54,0,2,0
2147
         .stabs "ONE(c) (c + 19)",54,0,3,0
2148
         .stabs "ONE",58,0,10,0
2149
         .stabs "ONE(c) (c + 23)",54,0,11,0
2150
 
2151
NOTE: In the above example, `54' is `N_MAC_DEFINE' and `58' is
2152
`N_MAC_UNDEF'.
2153
 
2154

2155
File: stabs.info,  Node: Symbol Tables,  Next: Cplusplus,  Prev: Macro define and undefine,  Up: Top
2156
 
2157
7 Symbol Information in Symbol Tables
2158
*************************************
2159
 
2160
This chapter describes the format of symbol table entries and how stab
2161
assembler directives map to them.  It also describes the
2162
transformations that the assembler and linker make on data from stabs.
2163
 
2164
* Menu:
2165
 
2166
* Symbol Table Format::
2167
* Transformations On Symbol Tables::
2168
 
2169

2170
File: stabs.info,  Node: Symbol Table Format,  Next: Transformations On Symbol Tables,  Up: Symbol Tables
2171
 
2172
7.1 Symbol Table Format
2173
=======================
2174
 
2175
Each time the assembler encounters a stab directive, it puts each field
2176
of the stab into a corresponding field in a symbol table entry of its
2177
output file.  If the stab contains a string field, the symbol table
2178
entry for that stab points to a string table entry containing the
2179
string data from the stab.  Assembler labels become relocatable
2180
addresses.  Symbol table entries in a.out have the format:
2181
 
2182
     struct internal_nlist {
2183
       unsigned long n_strx;         /* index into string table of name */
2184
       unsigned char n_type;         /* type of symbol */
2185
       unsigned char n_other;        /* misc info (usually empty) */
2186
       unsigned short n_desc;        /* description field */
2187
       bfd_vma n_value;              /* value of symbol */
2188
     };
2189
 
2190
   If the stab has a string, the `n_strx' field holds the offset in
2191
bytes of the string within the string table.  The string is terminated
2192
by a NUL character.  If the stab lacks a string (for example, it was
2193
produced by a `.stabn' or `.stabd' directive), the `n_strx' field is
2194
zero.
2195
 
2196
   Symbol table entries with `n_type' field values greater than 0x1f
2197
originated as stabs generated by the compiler (with one random
2198
exception).  The other entries were placed in the symbol table of the
2199
executable by the assembler or the linker.
2200
 
2201

2202
File: stabs.info,  Node: Transformations On Symbol Tables,  Prev: Symbol Table Format,  Up: Symbol Tables
2203
 
2204
7.2 Transformations on Symbol Tables
2205
====================================
2206
 
2207
The linker concatenates object files and does fixups of externally
2208
defined symbols.
2209
 
2210
   You can see the transformations made on stab data by the assembler
2211
and linker by examining the symbol table after each pass of the build.
2212
To do this, use `nm -ap', which dumps the symbol table, including
2213
debugging information, unsorted.  For stab entries the columns are:
2214
VALUE, OTHER, DESC, TYPE, STRING.  For assembler and linker symbols,
2215
the columns are: VALUE, TYPE, STRING.
2216
 
2217
   The low 5 bits of the stab type tell the linker how to relocate the
2218
value of the stab.  Thus for stab types like `N_RSYM' and `N_LSYM',
2219
where the value is an offset or a register number, the low 5 bits are
2220
`N_ABS', which tells the linker not to relocate the value.
2221
 
2222
   Where the value of a stab contains an assembly language label, it is
2223
transformed by each build step.  The assembler turns it into a
2224
relocatable address and the linker turns it into an absolute address.
2225
 
2226
* Menu:
2227
 
2228
* Transformations On Static Variables::
2229
* Transformations On Global Variables::
2230
* Stab Section Transformations::           For some object file formats,
2231
                                           things are a bit different.
2232
 
2233

2234
File: stabs.info,  Node: Transformations On Static Variables,  Next: Transformations On Global Variables,  Up: Transformations On Symbol Tables
2235
 
2236
7.2.1 Transformations on Static Variables
2237
-----------------------------------------
2238
 
2239
This source line defines a static variable at file scope:
2240
 
2241
     static int s_g_repeat
2242
 
2243
The following stab describes the symbol:
2244
 
2245
     .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
2246
 
2247
The assembler transforms the stab into this symbol table entry in the
2248
`.o' file.  The location is expressed as a data segment offset.
2249
 
2250
     00000084 - 00 0000 STSYM s_g_repeat:S1
2251
 
2252
In the symbol table entry from the executable, the linker has made the
2253
relocatable address absolute.
2254
 
2255
     0000e00c - 00 0000 STSYM s_g_repeat:S1
2256
 
2257

2258
File: stabs.info,  Node: Transformations On Global Variables,  Next: Stab Section Transformations,  Prev: Transformations On Static Variables,  Up: Transformations On Symbol Tables
2259
 
2260
7.2.2 Transformations on Global Variables
2261
-----------------------------------------
2262
 
2263
Stabs for global variables do not contain location information. In this
2264
case, the debugger finds location information in the assembler or
2265
linker symbol table entry describing the variable.  The source line:
2266
 
2267
     char g_foo = 'c';
2268
 
2269
generates the stab:
2270
 
2271
     .stabs "g_foo:G2",32,0,0,0
2272
 
2273
   The variable is represented by two symbol table entries in the object
2274
file (see below).  The first one originated as a stab.  The second one
2275
is an external symbol.  The upper case `D' signifies that the `n_type'
2276
field of the symbol table contains 7, `N_DATA' with local linkage.  The
2277
stab's value is zero since the value is not used for `N_GSYM' stabs.
2278
The value of the linker symbol is the relocatable address corresponding
2279
to the variable.
2280
 
2281
     00000000 - 00 0000  GSYM g_foo:G2
2282
     00000080 D _g_foo
2283
 
2284
These entries as transformed by the linker.  The linker symbol table
2285
entry now holds an absolute address:
2286
 
2287
     00000000 - 00 0000  GSYM g_foo:G2
2288
     ...
2289
     0000e008 D _g_foo
2290
 
2291

2292
File: stabs.info,  Node: Stab Section Transformations,  Prev: Transformations On Global Variables,  Up: Transformations On Symbol Tables
2293
 
2294
7.2.3 Transformations of Stabs in separate sections
2295
---------------------------------------------------
2296
 
2297
For object file formats using stabs in separate sections (*note Stab
2298
Sections::), use `objdump --stabs' instead of `nm' to show the stabs in
2299
an object or executable file.  `objdump' is a GNU utility; Sun does not
2300
provide any equivalent.
2301
 
2302
   The following example is for a stab whose value is an address is
2303
relative to the compilation unit (*note ELF Linker Relocation::).  For
2304
example, if the source line
2305
 
2306
     static int ld = 5;
2307
 
2308
   appears within a function, then the assembly language output from the
2309
compiler contains:
2310
 
2311
     .Ddata.data:
2312
     ...
2313
             .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data    # 0x26 is N_STSYM
2314
     ...
2315
     .L18:
2316
             .align 4
2317
             .word 0x5
2318
 
2319
   Because the value is formed by subtracting one symbol from another,
2320
the value is absolute, not relocatable, and so the object file contains
2321
 
2322
     Symnum n_type n_othr n_desc n_value  n_strx String
2323
     31     STSYM  0      4      00000004 680    ld:V(0,3)
2324
 
2325
   without any relocations, and the executable file also contains
2326
 
2327
     Symnum n_type n_othr n_desc n_value  n_strx String
2328
     31     STSYM  0      4      00000004 680    ld:V(0,3)
2329
 
2330

2331
File: stabs.info,  Node: Cplusplus,  Next: Stab Types,  Prev: Symbol Tables,  Up: Top
2332
 
2333
8 GNU C++ Stabs
2334
***************
2335
 
2336
* Menu:
2337
 
2338
* Class Names::                 C++ class names are both tags and typedefs.
2339
* Nested Symbols::              C++ symbol names can be within other types.
2340
* Basic Cplusplus Types::
2341
* Simple Classes::
2342
* Class Instance::
2343
* Methods::                     Method definition
2344
* Method Type Descriptor::      The `#' type descriptor
2345
* Member Type Descriptor::      The `@' type descriptor
2346
* Protections::
2347
* Method Modifiers::
2348
* Virtual Methods::
2349
* Inheritance::
2350
* Virtual Base Classes::
2351
* Static Members::
2352
 
2353

2354
File: stabs.info,  Node: Class Names,  Next: Nested Symbols,  Up: Cplusplus
2355
 
2356
8.1 C++ Class Names
2357
===================
2358
 
2359
In C++, a class name which is declared with `class', `struct', or
2360
`union', is not only a tag, as in C, but also a type name.  Thus there
2361
should be stabs with both `t' and `T' symbol descriptors (*note
2362
Typedefs::).
2363
 
2364
   To save space, there is a special abbreviation for this case.  If the
2365
`T' symbol descriptor is followed by `t', then the stab defines both a
2366
type name and a tag.
2367
 
2368
   For example, the C++ code
2369
 
2370
     struct foo {int x;};
2371
 
2372
   can be represented as either
2373
 
2374
     .stabs "foo:T19=s4x:1,0,32;;",128,0,0,0       # 128 is N_LSYM
2375
     .stabs "foo:t19",128,0,0,0
2376
 
2377
   or
2378
 
2379
     .stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0
2380
 
2381

2382
File: stabs.info,  Node: Nested Symbols,  Next: Basic Cplusplus Types,  Prev: Class Names,  Up: Cplusplus
2383
 
2384
8.2 Defining a Symbol Within Another Type
2385
=========================================
2386
 
2387
In C++, a symbol (such as a type name) can be defined within another
2388
type.
2389
 
2390
   In stabs, this is sometimes represented by making the name of a
2391
symbol which contains `::'.  Such a pair of colons does not end the name
2392
of the symbol, the way a single colon would (*note String Field::).  I'm
2393
not sure how consistently used or well thought out this mechanism is.
2394
So that a pair of colons in this position always has this meaning, `:'
2395
cannot be used as a symbol descriptor.
2396
 
2397
   For example, if the string for a stab is `foo::bar::baz:t5=*6', then
2398
`foo::bar::baz' is the name of the symbol, `t' is the symbol
2399
descriptor, and `5=*6' is the type information.
2400
 
2401

2402
File: stabs.info,  Node: Basic Cplusplus Types,  Next: Simple Classes,  Prev: Nested Symbols,  Up: Cplusplus
2403
 
2404
8.3 Basic Types For C++
2405
=======================
2406
 
2407
<< the examples that follow are based on a01.C >>
2408
 
2409
   C++ adds two more builtin types to the set defined for C.  These are
2410
the unknown type and the vtable record type.  The unknown type, type
2411
16, is defined in terms of itself like the void type.
2412
 
2413
   The vtable record type, type 17, is defined as a structure type and
2414
then as a structure tag.  The structure has four fields: delta, index,
2415
pfn, and delta2.  pfn is the function pointer.
2416
 
2417
   << In boilerplate $vtbl_ptr_type, what are the fields delta, index,
2418
and delta2 used for? >>
2419
 
2420
   This basic type is present in all C++ programs even if there are no
2421
virtual methods defined.
2422
 
2423
     .stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8)
2424
             elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16);
2425
             elem_name(index):type_ref(short int),bit_offset(16),field_bits(16);
2426
             elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void),
2427
                                         bit_offset(32),field_bits(32);
2428
             elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;"
2429
             N_LSYM, NIL, NIL
2430
 
2431
     .stabs "$vtbl_ptr_type:t17=s8
2432
             delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;"
2433
             ,128,0,0,0
2434
 
2435
     .stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL
2436
 
2437
     .stabs "$vtbl_ptr_type:T17",128,0,0,0
2438
 
2439

2440
File: stabs.info,  Node: Simple Classes,  Next: Class Instance,  Prev: Basic Cplusplus Types,  Up: Cplusplus
2441
 
2442
8.4 Simple Class Definition
2443
===========================
2444
 
2445
The stabs describing C++ language features are an extension of the
2446
stabs describing C.  Stabs representing C++ class types elaborate
2447
extensively on the stab format used to describe structure types in C.
2448
Stabs representing class type variables look just like stabs
2449
representing C language variables.
2450
 
2451
   Consider the following very simple class definition.
2452
 
2453
     class baseA {
2454
     public:
2455
             int Adat;
2456
             int Ameth(int in, char other);
2457
     };
2458
 
2459
   The class `baseA' is represented by two stabs.  The first stab
2460
describes the class as a structure type.  The second stab describes a
2461
structure tag of the class type.  Both stabs are of stab type `N_LSYM'.
2462
Since the stab is not located between an `N_FUN' and an `N_LBRAC' stab
2463
this indicates that the class is defined at file scope.  If it were,
2464
then the `N_LSYM' would signify a local variable.
2465
 
2466
   A stab describing a C++ class type is similar in format to a stab
2467
describing a C struct, with each class member shown as a field in the
2468
structure.  The part of the struct format describing fields is expanded
2469
to include extra information relevant to C++ class members.  In
2470
addition, if the class has multiple base classes or virtual functions
2471
the struct format outside of the field parts is also augmented.
2472
 
2473
   In this simple example the field part of the C++ class stab
2474
representing member data looks just like the field part of a C struct
2475
stab.  The section on protections describes how its format is sometimes
2476
extended for member data.
2477
 
2478
   The field part of a C++ class stab representing a member function
2479
differs substantially from the field part of a C struct stab.  It still
2480
begins with `name:' but then goes on to define a new type number for
2481
the member function, describe its return type, its argument types, its
2482
protection level, any qualifiers applied to the method definition, and
2483
whether the method is virtual or not.  If the method is virtual then
2484
the method description goes on to give the vtable index of the method,
2485
and the type number of the first base class defining the method.
2486
 
2487
   When the field name is a method name it is followed by two colons
2488
rather than one.  This is followed by a new type definition for the
2489
method.  This is a number followed by an equal sign and the type of the
2490
method.  Normally this will be a type declared using the `#' type
2491
descriptor; see *Note Method Type Descriptor::; static member functions
2492
are declared using the `f' type descriptor instead; see *Note Function
2493
Types::.
2494
 
2495
   The format of an overloaded operator method name differs from that of
2496
other methods.  It is `op$::OPERATOR-NAME.' where OPERATOR-NAME is the
2497
operator name such as `+' or `+='.  The name ends with a period, and
2498
any characters except the period can occur in the OPERATOR-NAME string.
2499
 
2500
   The next part of the method description represents the arguments to
2501
the method, preceded by a colon and ending with a semi-colon.  The
2502
types of the arguments are expressed in the same way argument types are
2503
expressed in C++ name mangling.  In this example an `int' and a `char'
2504
map to `ic'.
2505
 
2506
   This is followed by a number, a letter, and an asterisk or period,
2507
followed by another semicolon.  The number indicates the protections
2508
that apply to the member function.  Here the 2 means public.  The
2509
letter encodes any qualifier applied to the method definition.  In this
2510
case, `A' means that it is a normal function definition.  The dot shows
2511
that the method is not virtual.  The sections that follow elaborate
2512
further on these fields and describe the additional information present
2513
for virtual methods.
2514
 
2515
     .stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4)
2516
             field_name(Adat):type(int),bit_offset(0),field_bits(32);
2517
 
2518
             method_name(Ameth)::type_def(21)=type_desc(method)return_type(int);
2519
             :arg_types(int char);
2520
             protection(public)qualifier(normal)virtual(no);;"
2521
             N_LSYM,NIL,NIL,NIL
2522
 
2523
     .stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0
2524
 
2525
     .stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL
2526
 
2527
     .stabs "baseA:T20",128,0,0,0
2528
 
2529

2530
File: stabs.info,  Node: Class Instance,  Next: Methods,  Prev: Simple Classes,  Up: Cplusplus
2531
 
2532
8.5 Class Instance
2533
==================
2534
 
2535
As shown above, describing even a simple C++ class definition is
2536
accomplished by massively extending the stab format used in C to
2537
describe structure types.  However, once the class is defined, C stabs
2538
with no modifications can be used to describe class instances.  The
2539
following source:
2540
 
2541
     main () {
2542
             baseA AbaseA;
2543
     }
2544
 
2545
yields the following stab describing the class instance.  It looks no
2546
different from a standard C stab describing a local variable.
2547
 
2548
     .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset
2549
 
2550
     .stabs "AbaseA:20",128,0,0,-20
2551
 
2552

2553
File: stabs.info,  Node: Methods,  Next: Method Type Descriptor,  Prev: Class Instance,  Up: Cplusplus
2554
 
2555
8.6 Method Definition
2556
=====================
2557
 
2558
The class definition shown above declares Ameth.  The C++ source below
2559
defines Ameth:
2560
 
2561
     int
2562
     baseA::Ameth(int in, char other)
2563
     {
2564
             return in;
2565
     };
2566
 
2567
   This method definition yields three stabs following the code of the
2568
method.  One stab describes the method itself and following two describe
2569
its parameters.  Although there is only one formal argument all methods
2570
have an implicit argument which is the `this' pointer.  The `this'
2571
pointer is a pointer to the object on which the method was called.  Note
2572
that the method name is mangled to encode the class name and argument
2573
types.  Name mangling is described in the ARM (`The Annotated C++
2574
Reference Manual', by Ellis and Stroustrup, ISBN 0-201-51459-1);
2575
`gpcompare.texi' in Cygnus GCC distributions describes the differences
2576
between GNU mangling and ARM mangling.
2577
 
2578
     .stabs "name:symbol_descriptor(global function)return_type(int)",
2579
             N_FUN, NIL, NIL, code_addr_of_method_start
2580
 
2581
     .stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic
2582
 
2583
   Here is the stab for the `this' pointer implicit argument.  The name
2584
of the `this' pointer is always `this'.  Type 19, the `this' pointer is
2585
defined as a pointer to type 20, `baseA', but a stab defining `baseA'
2586
has not yet been emitted.  Since the compiler knows it will be emitted
2587
shortly, here it just outputs a cross reference to the undefined
2588
symbol, by prefixing the symbol name with `xs'.
2589
 
2590
     .stabs "name:sym_desc(register param)type_def(19)=
2591
             type_desc(ptr to)type_ref(baseA)=
2592
             type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number
2593
 
2594
     .stabs "this:P19=*20=xsbaseA:",64,0,0,8
2595
 
2596
   The stab for the explicit integer argument looks just like a
2597
parameter to a C function.  The last field of the stab is the offset
2598
from the argument pointer, which in most systems is the same as the
2599
frame pointer.
2600
 
2601
     .stabs "name:sym_desc(value parameter)type_ref(int)",
2602
             N_PSYM,NIL,NIL,offset_from_arg_ptr
2603
 
2604
     .stabs "in:p1",160,0,0,72
2605
 
2606
   << The examples that follow are based on A1.C >>
2607
 
2608

2609
File: stabs.info,  Node: Method Type Descriptor,  Next: Member Type Descriptor,  Prev: Methods,  Up: Cplusplus
2610
 
2611
8.7 The `#' Type Descriptor
2612
===========================
2613
 
2614
This is used to describe a class method.  This is a function which takes
2615
an extra argument as its first argument, for the `this' pointer.
2616
 
2617
   If the `#' is immediately followed by another `#', the second one
2618
will be followed by the return type and a semicolon.  The class and
2619
argument types are not specified, and must be determined by demangling
2620
the name of the method if it is available.
2621
 
2622
   Otherwise, the single `#' is followed by the class type, a comma,
2623
the return type, a comma, and zero or more parameter types separated by
2624
commas.  The list of arguments is terminated by a semicolon.  In the
2625
debugging output generated by gcc, a final argument type of `void'
2626
indicates a method which does not take a variable number of arguments.
2627
If the final argument type of `void' does not appear, the method was
2628
declared with an ellipsis.
2629
 
2630
   Note that although such a type will normally be used to describe
2631
fields in structures, unions, or classes, for at least some versions of
2632
the compiler it can also be used in other contexts.
2633
 
2634

2635
File: stabs.info,  Node: Member Type Descriptor,  Next: Protections,  Prev: Method Type Descriptor,  Up: Cplusplus
2636
 
2637
8.8 The `@' Type Descriptor
2638
===========================
2639
 
2640
The `@' type descriptor is used for a pointer-to-non-static-member-data
2641
type.  It is followed by type information for the class (or union), a
2642
comma, and type information for the member data.
2643
 
2644
   The following C++ source:
2645
 
2646
     typedef int A::*int_in_a;
2647
 
2648
   generates the following stab:
2649
 
2650
     .stabs "int_in_a:t20=21=@19,1",128,0,0,0
2651
 
2652
   Note that there is a conflict between this and type attributes
2653
(*note String Field::); both use type descriptor `@'.  Fortunately, the
2654
`@' type descriptor used in this C++ sense always will be followed by a
2655
digit, `(', or `-', and type attributes never start with those things.
2656
 
2657

2658
File: stabs.info,  Node: Protections,  Next: Method Modifiers,  Prev: Member Type Descriptor,  Up: Cplusplus
2659
 
2660
8.9 Protections
2661
===============
2662
 
2663
In the simple class definition shown above all member data and
2664
functions were publicly accessible.  The example that follows contrasts
2665
public, protected and privately accessible fields and shows how these
2666
protections are encoded in C++ stabs.
2667
 
2668
   If the character following the `FIELD-NAME:' part of the string is
2669
`/', then the next character is the visibility.  `0' means private, `1'
2670
means protected, and `2' means public.  Debuggers should ignore
2671
visibility characters they do not recognize, and assume a reasonable
2672
default (such as public) (GDB 4.11 does not, but this should be fixed
2673
in the next GDB release).  If no visibility is specified the field is
2674
public.  The visibility `9' means that the field has been optimized out
2675
and is public (there is no way to specify an optimized out field with a
2676
private or protected visibility).  Visibility `9' is not supported by
2677
GDB 4.11; this should be fixed in the next GDB release.
2678
 
2679
   The following C++ source:
2680
 
2681
     class vis {
2682
     private:
2683
             int   priv;
2684
     protected:
2685
             char  prot;
2686
     public:
2687
             float pub;
2688
     };
2689
 
2690
generates the following stab:
2691
 
2692
     # 128 is N_LSYM
2693
     .stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0
2694
 
2695
   `vis:T19=s12' indicates that type number 19 is a 12 byte structure
2696
named `vis' The `priv' field has public visibility (`/0'), type int
2697
(`1'), and offset and size `,0,32;'.  The `prot' field has protected
2698
visibility (`/1'), type char (`2') and offset and size `,32,8;'.  The
2699
`pub' field has type float (`12'), and offset and size `,64,32;'.
2700
 
2701
   Protections for member functions are signified by one digit embedded
2702
in the field part of the stab describing the method.  The digit is 0 if
2703
private, 1 if protected and 2 if public.  Consider the C++ class
2704
definition below:
2705
 
2706
     class all_methods {
2707
     private:
2708
             int   priv_meth(int in){return in;};
2709
     protected:
2710
             char  protMeth(char in){return in;};
2711
     public:
2712
             float pubMeth(float in){return in;};
2713
     };
2714
 
2715
   It generates the following stab.  The digit in question is to the
2716
left of an `A' in each case.  Notice also that in this case two symbol
2717
descriptors apply to the class name struct tag and struct type.
2718
 
2719
     .stabs "class_name:sym_desc(struct tag&type)type_def(21)=
2720
             sym_desc(struct)struct_bytes(1)
2721
             meth_name::type_def(22)=sym_desc(method)returning(int);
2722
             :args(int);protection(private)modifier(normal)virtual(no);
2723
             meth_name::type_def(23)=sym_desc(method)returning(char);
2724
             :args(char);protection(protected)modifier(normal)virtual(no);
2725
             meth_name::type_def(24)=sym_desc(method)returning(float);
2726
             :args(float);protection(public)modifier(normal)virtual(no);;",
2727
             N_LSYM,NIL,NIL,NIL
2728
 
2729
     .stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.;
2730
             pubMeth::24=##12;:f;2A.;;",128,0,0,0
2731
 
2732

2733
File: stabs.info,  Node: Method Modifiers,  Next: Virtual Methods,  Prev: Protections,  Up: Cplusplus
2734
 
2735
8.10 Method Modifiers (`const', `volatile', `const volatile')
2736
=============================================================
2737
 
2738
<< based on a6.C >>
2739
 
2740
   In the class example described above all the methods have the normal
2741
modifier.  This method modifier information is located just after the
2742
protection information for the method.  This field has four possible
2743
character values.  Normal methods use `A', const methods use `B',
2744
volatile methods use `C', and const volatile methods use `D'.  Consider
2745
the class definition below:
2746
 
2747
     class A {
2748
     public:
2749
             int ConstMeth (int arg) const { return arg; };
2750
             char VolatileMeth (char arg) volatile { return arg; };
2751
             float ConstVolMeth (float arg) const volatile {return arg; };
2752
     };
2753
 
2754
   This class is described by the following stab:
2755
 
2756
     .stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1)
2757
             meth_name(ConstMeth)::type_def(21)sym_desc(method)
2758
             returning(int);:arg(int);protection(public)modifier(const)virtual(no);
2759
             meth_name(VolatileMeth)::type_def(22)=sym_desc(method)
2760
             returning(char);:arg(char);protection(public)modifier(volatile)virt(no)
2761
             meth_name(ConstVolMeth)::type_def(23)=sym_desc(method)
2762
             returning(float);:arg(float);protection(public)modifier(const volatile)
2763
             virtual(no);;", ...
2764
 
2765
     .stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.;
2766
                  ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0
2767
 
2768

2769
File: stabs.info,  Node: Virtual Methods,  Next: Inheritance,  Prev: Method Modifiers,  Up: Cplusplus
2770
 
2771
8.11 Virtual Methods
2772
====================
2773
 
2774
<< The following examples are based on a4.C >>
2775
 
2776
   The presence of virtual methods in a class definition adds additional
2777
data to the class description.  The extra data is appended to the
2778
description of the virtual method and to the end of the class
2779
description.  Consider the class definition below:
2780
 
2781
     class A {
2782
     public:
2783
             int Adat;
2784
             virtual int A_virt (int arg) { return arg; };
2785
     };
2786
 
2787
   This results in the stab below describing class A.  It defines a new
2788
type (20) which is an 8 byte structure.  The first field of the class
2789
struct is `Adat', an integer, starting at structure offset 0 and
2790
occupying 32 bits.
2791
 
2792
   The second field in the class struct is not explicitly defined by the
2793
C++ class definition but is implied by the fact that the class contains
2794
a virtual method.  This field is the vtable pointer.  The name of the
2795
vtable pointer field starts with `$vf' and continues with a type
2796
reference to the class it is part of.  In this example the type
2797
reference for class A is 20 so the name of its vtable pointer field is
2798
`$vf20', followed by the usual colon.
2799
 
2800
   Next there is a type definition for the vtable pointer type (21).
2801
This is in turn defined as a pointer to another new type (22).
2802
 
2803
   Type 22 is the vtable itself, which is defined as an array, indexed
2804
by a range of integers between 0 and 1, and whose elements are of type
2805
17.  Type 17 was the vtable record type defined by the boilerplate C++
2806
type definitions, as shown earlier.
2807
 
2808
   The bit offset of the vtable pointer field is 32.  The number of bits
2809
in the field are not specified when the field is a vtable pointer.
2810
 
2811
   Next is the method definition for the virtual member function
2812
`A_virt'.  Its description starts out using the same format as the
2813
non-virtual member functions described above, except instead of a dot
2814
after the `A' there is an asterisk, indicating that the function is
2815
virtual.  Since is is virtual some addition information is appended to
2816
the end of the method description.
2817
 
2818
   The first number represents the vtable index of the method.  This is
2819
a 32 bit unsigned number with the high bit set, followed by a
2820
semi-colon.
2821
 
2822
   The second number is a type reference to the first base class in the
2823
inheritance hierarchy defining the virtual member function.  In this
2824
case the class stab describes a base class so the virtual function is
2825
not overriding any other definition of the method.  Therefore the
2826
reference is to the type number of the class that the stab is
2827
describing (20).
2828
 
2829
   This is followed by three semi-colons.  One marks the end of the
2830
current sub-section, one marks the end of the method field, and the
2831
third marks the end of the struct definition.
2832
 
2833
   For classes containing virtual functions the very last section of the
2834
string part of the stab holds a type reference to the first base class.
2835
This is preceded by `~%' and followed by a final semi-colon.
2836
 
2837
     .stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8)
2838
             field_name(Adat):type_ref(int),bit_offset(0),field_bits(32);
2839
             field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)=
2840
             sym_desc(array)index_type_ref(range of int from 0 to 1);
2841
             elem_type_ref(vtbl elem type),
2842
             bit_offset(32);
2843
             meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int);
2844
             :arg_type(int),protection(public)normal(yes)virtual(yes)
2845
             vtable_index(1);class_first_defining(A);;;~%first_base(A);",
2846
             N_LSYM,NIL,NIL,NIL
2847
 
2848
     .stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
2849
             A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
2850
 
2851

2852
File: stabs.info,  Node: Inheritance,  Next: Virtual Base Classes,  Prev: Virtual Methods,  Up: Cplusplus
2853
 
2854
8.12 Inheritance
2855
================
2856
 
2857
Stabs describing C++ derived classes include additional sections that
2858
describe the inheritance hierarchy of the class.  A derived class stab
2859
also encodes the number of base classes.  For each base class it tells
2860
if the base class is virtual or not, and if the inheritance is private
2861
or public.  It also gives the offset into the object of the portion of
2862
the object corresponding to each base class.
2863
 
2864
   This additional information is embedded in the class stab following
2865
the number of bytes in the struct.  First the number of base classes
2866
appears bracketed by an exclamation point and a comma.
2867
 
2868
   Then for each base type there repeats a series: a virtual character,
2869
a visibility character, a number, a comma, another number, and a
2870
semi-colon.
2871
 
2872
   The virtual character is `1' if the base class is virtual and `0' if
2873
not.  The visibility character is `2' if the derivation is public, `1'
2874
if it is protected, and `0' if it is private.  Debuggers should ignore
2875
virtual or visibility characters they do not recognize, and assume a
2876
reasonable default (such as public and non-virtual) (GDB 4.11 does not,
2877
but this should be fixed in the next GDB release).
2878
 
2879
   The number following the virtual and visibility characters is the
2880
offset from the start of the object to the part of the object
2881
pertaining to the base class.
2882
 
2883
   After the comma, the second number is a type_descriptor for the base
2884
type.  Finally a semi-colon ends the series, which repeats for each
2885
base class.
2886
 
2887
   The source below defines three base classes `A', `B', and `C' and
2888
the derived class `D'.
2889
 
2890
     class A {
2891
     public:
2892
             int Adat;
2893
             virtual int A_virt (int arg) { return arg; };
2894
     };
2895
 
2896
     class B {
2897
     public:
2898
             int B_dat;
2899
             virtual int B_virt (int arg) {return arg; };
2900
     };
2901
 
2902
     class C {
2903
     public:
2904
             int Cdat;
2905
             virtual int C_virt (int arg) {return arg; };
2906
     };
2907
 
2908
     class D : A, virtual B, public C {
2909
     public:
2910
             int Ddat;
2911
             virtual int A_virt (int arg ) { return arg+1; };
2912
             virtual int B_virt (int arg)  { return arg+2; };
2913
             virtual int C_virt (int arg)  { return arg+3; };
2914
             virtual int D_virt (int arg)  { return arg; };
2915
     };
2916
 
2917
   Class stabs similar to the ones described earlier are generated for
2918
each base class.
2919
 
2920
     .stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
2921
             A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
2922
 
2923
     .stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1;
2924
             :i;2A*-2147483647;25;;;~%25;",128,0,0,0
2925
 
2926
     .stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1;
2927
             :i;2A*-2147483647;28;;;~%28;",128,0,0,0
2928
 
2929
   In the stab describing derived class `D' below, the information about
2930
the derivation of this class is encoded as follows.
2931
 
2932
     .stabs "derived_class_name:symbol_descriptors(struct tag&type)=
2933
             type_descriptor(struct)struct_bytes(32)!num_bases(3),
2934
             base_virtual(no)inheritance_public(no)base_offset(0),
2935
             base_class_type_ref(A);
2936
             base_virtual(yes)inheritance_public(no)base_offset(NIL),
2937
             base_class_type_ref(B);
2938
             base_virtual(no)inheritance_public(yes)base_offset(64),
2939
             base_class_type_ref(C); ...
2940
 
2941
     .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:
2942
             1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt:
2943
             :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;
2944
             28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
2945
 
2946

2947
File: stabs.info,  Node: Virtual Base Classes,  Next: Static Members,  Prev: Inheritance,  Up: Cplusplus
2948
 
2949
8.13 Virtual Base Classes
2950
=========================
2951
 
2952
A derived class object consists of a concatenation in memory of the data
2953
areas defined by each base class, starting with the leftmost and ending
2954
with the rightmost in the list of base classes.  The exception to this
2955
rule is for virtual inheritance.  In the example above, class `D'
2956
inherits virtually from base class `B'.  This means that an instance of
2957
a `D' object will not contain its own `B' part but merely a pointer to
2958
a `B' part, known as a virtual base pointer.
2959
 
2960
   In a derived class stab, the base offset part of the derivation
2961
information, described above, shows how the base class parts are
2962
ordered.  The base offset for a virtual base class is always given as 0.
2963
Notice that the base offset for `B' is given as 0 even though `B' is
2964
not the first base class.  The first base class `A' starts at offset 0.
2965
 
2966
   The field information part of the stab for class `D' describes the
2967
field which is the pointer to the virtual base class `B'. The vbase
2968
pointer name is `$vb' followed by a type reference to the virtual base
2969
class.  Since the type id for `B' in this example is 25, the vbase
2970
pointer name is `$vb25'.
2971
 
2972
     .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1,
2973
            160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i;
2974
            2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt:
2975
            :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
2976
 
2977
   Following the name and a semicolon is a type reference describing the
2978
type of the virtual base class pointer, in this case 24.  Type 24 was
2979
defined earlier as the type of the `B' class `this' pointer.  The
2980
`this' pointer for a class is a pointer to the class type.
2981
 
2982
     .stabs "this:P24=*25=xsB:",64,0,0,8
2983
 
2984
   Finally the field offset part of the vbase pointer field description
2985
shows that the vbase pointer is the first field in the `D' object,
2986
before any data fields defined by the class.  The layout of a `D' class
2987
object is a follows, `Adat' at 0, the vtable pointer for `A' at 32,
2988
`Cdat' at 64, the vtable pointer for C at 96, the virtual base pointer
2989
for `B' at 128, and `Ddat' at 160.
2990
 
2991

2992
File: stabs.info,  Node: Static Members,  Prev: Virtual Base Classes,  Up: Cplusplus
2993
 
2994
8.14 Static Members
2995
===================
2996
 
2997
The data area for a class is a concatenation of the space used by the
2998
data members of the class.  If the class has virtual methods, a vtable
2999
pointer follows the class data.  The field offset part of each field
3000
description in the class stab shows this ordering.
3001
 
3002
   << How is this reflected in stabs?  See Cygnus bug #677 for some
3003
info.  >>
3004
 
3005

3006
File: stabs.info,  Node: Stab Types,  Next: Symbol Descriptors,  Prev: Cplusplus,  Up: Top
3007
 
3008
Appendix A Table of Stab Types
3009
******************************
3010
 
3011
The following are all the possible values for the stab type field, for
3012
a.out files, in numeric order.  This does not apply to XCOFF, but it
3013
does apply to stabs in sections (*note Stab Sections::).  Stabs in
3014
ECOFF use these values but add 0x8f300 to distinguish them from non-stab
3015
symbols.
3016
 
3017
   The symbolic names are defined in the file `include/aout/stabs.def'.
3018
 
3019
* Menu:
3020
 
3021
* Non-Stab Symbol Types::       Types from 0 to 0x1f
3022
* Stab Symbol Types::           Types from 0x20 to 0xff
3023
 
3024

3025
File: stabs.info,  Node: Non-Stab Symbol Types,  Next: Stab Symbol Types,  Up: Stab Types
3026
 
3027
A.1 Non-Stab Symbol Types
3028
=========================
3029
 
3030
The following types are used by the linker and assembler, not by stab
3031
directives.  Since this document does not attempt to describe aspects of
3032
object file format other than the debugging format, no details are
3033
given.
3034
 
3035
`0x0     N_UNDF'
3036
     Undefined symbol
3037
 
3038
`0x2     N_ABS'
3039
     File scope absolute symbol
3040
 
3041
`0x3     N_ABS | N_EXT'
3042
     External absolute symbol
3043
 
3044
`0x4     N_TEXT'
3045
     File scope text symbol
3046
 
3047
`0x5     N_TEXT | N_EXT'
3048
     External text symbol
3049
 
3050
`0x6     N_DATA'
3051
     File scope data symbol
3052
 
3053
`0x7     N_DATA | N_EXT'
3054
     External data symbol
3055
 
3056
`0x8     N_BSS'
3057
     File scope BSS symbol
3058
 
3059
`0x9     N_BSS | N_EXT'
3060
     External BSS symbol
3061
 
3062
`0x0c    N_FN_SEQ'
3063
     Same as `N_FN', for Sequent compilers
3064
 
3065
`0x0a    N_INDR'
3066
     Symbol is indirected to another symbol
3067
 
3068
`0x12    N_COMM'
3069
     Common--visible after shared library dynamic link
3070
 
3071
`0x14 N_SETA'
3072
`0x15 N_SETA | N_EXT'
3073
     Absolute set element
3074
 
3075
`0x16 N_SETT'
3076
`0x17 N_SETT | N_EXT'
3077
     Text segment set element
3078
 
3079
`0x18 N_SETD'
3080
`0x19 N_SETD | N_EXT'
3081
     Data segment set element
3082
 
3083
`0x1a N_SETB'
3084
`0x1b N_SETB | N_EXT'
3085
     BSS segment set element
3086
 
3087
`0x1c N_SETV'
3088
`0x1d N_SETV | N_EXT'
3089
     Pointer to set vector
3090
 
3091
`0x1e N_WARNING'
3092
     Print a warning message during linking
3093
 
3094
`0x1f    N_FN'
3095
     File name of a `.o' file
3096
 
3097

3098
File: stabs.info,  Node: Stab Symbol Types,  Prev: Non-Stab Symbol Types,  Up: Stab Types
3099
 
3100
A.2 Stab Symbol Types
3101
=====================
3102
 
3103
The following symbol types indicate that this is a stab.  This is the
3104
full list of stab numbers, including stab types that are used in
3105
languages other than C.
3106
 
3107
`0x20     N_GSYM'
3108
     Global symbol; see *Note Global Variables::.
3109
 
3110
`0x22     N_FNAME'
3111
     Function name (for BSD Fortran); see *Note Procedures::.
3112
 
3113
`0x24     N_FUN'
3114
     Function name (*note Procedures::) or text segment variable (*note
3115
     Statics::).
3116
 
3117
`0x26 N_STSYM'
3118
     Data segment file-scope variable; see *Note Statics::.
3119
 
3120
`0x28 N_LCSYM'
3121
     BSS segment file-scope variable; see *Note Statics::.
3122
 
3123
`0x2a N_MAIN'
3124
     Name of main routine; see *Note Main Program::.
3125
 
3126
`0x2c N_ROSYM'
3127
     Variable in `.rodata' section; see *Note Statics::.
3128
 
3129
`0x30     N_PC'
3130
     Global symbol (for Pascal); see *Note N_PC::.
3131
 
3132
`0x32     N_NSYMS'
3133
     Number of symbols (according to Ultrix V4.0); see *Note N_NSYMS::.
3134
 
3135
`0x34     N_NOMAP'
3136
     No DST map; see *Note N_NOMAP::.
3137
 
3138
`0x36     N_MAC_DEFINE'
3139
     Name and body of a `#define'd macro; see *Note Macro define and
3140
     undefine::.
3141
 
3142
`0x38 N_OBJ'
3143
     Object file (Solaris2).
3144
 
3145
`0x3a     N_MAC_UNDEF'
3146
     Name of an `#undef'ed macro; see *Note Macro define and undefine::.
3147
 
3148
`0x3c N_OPT'
3149
     Debugger options (Solaris2).
3150
 
3151
`0x40     N_RSYM'
3152
     Register variable; see *Note Register Variables::.
3153
 
3154
`0x42     N_M2C'
3155
     Modula-2 compilation unit; see *Note N_M2C::.
3156
 
3157
`0x44     N_SLINE'
3158
     Line number in text segment; see *Note Line Numbers::.
3159
 
3160
`0x46     N_DSLINE'
3161
     Line number in data segment; see *Note Line Numbers::.
3162
 
3163
`0x48     N_BSLINE'
3164
     Line number in bss segment; see *Note Line Numbers::.
3165
 
3166
`0x48     N_BROWS'
3167
     Sun source code browser, path to `.cb' file; see *Note N_BROWS::.
3168
 
3169
`0x4a     N_DEFD'
3170
     GNU Modula2 definition module dependency; see *Note N_DEFD::.
3171
 
3172
`0x4c N_FLINE'
3173
     Function start/body/end line numbers (Solaris2).
3174
 
3175
`0x50     N_EHDECL'
3176
     GNU C++ exception variable; see *Note N_EHDECL::.
3177
 
3178
`0x50     N_MOD2'
3179
     Modula2 info "for imc" (according to Ultrix V4.0); see *Note
3180
     N_MOD2::.
3181
 
3182
`0x54     N_CATCH'
3183
     GNU C++ `catch' clause; see *Note N_CATCH::.
3184
 
3185
`0x60     N_SSYM'
3186
     Structure of union element; see *Note N_SSYM::.
3187
 
3188
`0x62 N_ENDM'
3189
     Last stab for module (Solaris2).
3190
 
3191
`0x64     N_SO'
3192
     Path and name of source file; see *Note Source Files::.
3193
 
3194
`0x80 N_LSYM'
3195
     Stack variable (*note Stack Variables::) or type (*note
3196
     Typedefs::).
3197
 
3198
`0x82     N_BINCL'
3199
     Beginning of an include file (Sun only); see *Note Include Files::.
3200
 
3201
`0x84     N_SOL'
3202
     Name of include file; see *Note Include Files::.
3203
 
3204
`0xa0     N_PSYM'
3205
     Parameter variable; see *Note Parameters::.
3206
 
3207
`0xa2     N_EINCL'
3208
     End of an include file; see *Note Include Files::.
3209
 
3210
`0xa4     N_ENTRY'
3211
     Alternate entry point; see *Note Alternate Entry Points::.
3212
 
3213
`0xc0     N_LBRAC'
3214
     Beginning of a lexical block; see *Note Block Structure::.
3215
 
3216
`0xc2     N_EXCL'
3217
     Place holder for a deleted include file; see *Note Include Files::.
3218
 
3219
`0xc4     N_SCOPE'
3220
     Modula2 scope information (Sun linker); see *Note N_SCOPE::.
3221
 
3222
`0xe0     N_RBRAC'
3223
     End of a lexical block; see *Note Block Structure::.
3224
 
3225
`0xe2     N_BCOMM'
3226
     Begin named common block; see *Note Common Blocks::.
3227
 
3228
`0xe4     N_ECOMM'
3229
     End named common block; see *Note Common Blocks::.
3230
 
3231
`0xe8     N_ECOML'
3232
     Member of a common block; see *Note Common Blocks::.
3233
 
3234
`0xea N_WITH'
3235
     Pascal `with' statement: type,,0,0,offset (Solaris2).
3236
 
3237
`0xf0     N_NBTEXT'
3238
     Gould non-base registers; see *Note Gould::.
3239
 
3240
`0xf2     N_NBDATA'
3241
     Gould non-base registers; see *Note Gould::.
3242
 
3243
`0xf4     N_NBBSS'
3244
     Gould non-base registers; see *Note Gould::.
3245
 
3246
`0xf6     N_NBSTS'
3247
     Gould non-base registers; see *Note Gould::.
3248
 
3249
`0xf8     N_NBLCS'
3250
     Gould non-base registers; see *Note Gould::.
3251
 
3252

3253
File: stabs.info,  Node: Symbol Descriptors,  Next: Type Descriptors,  Prev: Stab Types,  Up: Top
3254
 
3255
Appendix B Table of Symbol Descriptors
3256
**************************************
3257
 
3258
The symbol descriptor is the character which follows the colon in many
3259
stabs, and which tells what kind of stab it is.  *Note String Field::,
3260
for more information about their use.
3261
 
3262
`DIGIT'
3263
`('
3264
`-'
3265
     Variable on the stack; see *Note Stack Variables::.
3266
 
3267
`:'
3268
     C++ nested symbol; see *Note Nested Symbols::.
3269
 
3270
`a'
3271
     Parameter passed by reference in register; see *Note Reference
3272
     Parameters::.
3273
 
3274
`b'
3275
     Based variable; see *Note Based Variables::.
3276
 
3277
`c'
3278
     Constant; see *Note Constants::.
3279
 
3280
`C'
3281
     Conformant array bound (Pascal, maybe other languages); *Note
3282
     Conformant Arrays::.  Name of a caught exception (GNU C++).  These
3283
     can be distinguished because the latter uses `N_CATCH' and the
3284
     former uses another symbol type.
3285
 
3286
`d'
3287
     Floating point register variable; see *Note Register Variables::.
3288
 
3289
`D'
3290
     Parameter in floating point register; see *Note Register
3291
     Parameters::.
3292
 
3293
`f'
3294
     File scope function; see *Note Procedures::.
3295
 
3296
`F'
3297
     Global function; see *Note Procedures::.
3298
 
3299
`G'
3300
     Global variable; see *Note Global Variables::.
3301
 
3302
`i'
3303
     *Note Register Parameters::.
3304
 
3305
`I'
3306
     Internal (nested) procedure; see *Note Nested Procedures::.
3307
 
3308
`J'
3309
     Internal (nested) function; see *Note Nested Procedures::.
3310
 
3311
`L'
3312
     Label name (documented by AIX, no further information known).
3313
 
3314
`m'
3315
     Module; see *Note Procedures::.
3316
 
3317
`p'
3318
     Argument list parameter; see *Note Parameters::.
3319
 
3320
`pP'
3321
     *Note Parameters::.
3322
 
3323
`pF'
3324
     Fortran Function parameter; see *Note Parameters::.
3325
 
3326
`P'
3327
     Unfortunately, three separate meanings have been independently
3328
     invented for this symbol descriptor.  At least the GNU and Sun
3329
     uses can be distinguished by the symbol type.  Global Procedure
3330
     (AIX) (symbol type used unknown); see *Note Procedures::.
3331
     Register parameter (GNU) (symbol type `N_PSYM'); see *Note
3332
     Parameters::.  Prototype of function referenced by this file (Sun
3333
     `acc') (symbol type `N_FUN').
3334
 
3335
`Q'
3336
     Static Procedure; see *Note Procedures::.
3337
 
3338
`R'
3339
     Register parameter; see *Note Register Parameters::.
3340
 
3341
`r'
3342
     Register variable; see *Note Register Variables::.
3343
 
3344
`S'
3345
     File scope variable; see *Note Statics::.
3346
 
3347
`s'
3348
     Local variable (OS9000).
3349
 
3350
`t'
3351
     Type name; see *Note Typedefs::.
3352
 
3353
`T'
3354
     Enumeration, structure, or union tag; see *Note Typedefs::.
3355
 
3356
`v'
3357
     Parameter passed by reference; see *Note Reference Parameters::.
3358
 
3359
`V'
3360
     Procedure scope static variable; see *Note Statics::.
3361
 
3362
`x'
3363
     Conformant array; see *Note Conformant Arrays::.
3364
 
3365
`X'
3366
     Function return variable; see *Note Parameters::.
3367
 
3368

3369
File: stabs.info,  Node: Type Descriptors,  Next: Expanded Reference,  Prev: Symbol Descriptors,  Up: Top
3370
 
3371
Appendix C Table of Type Descriptors
3372
************************************
3373
 
3374
The type descriptor is the character which follows the type number and
3375
an equals sign.  It specifies what kind of type is being defined.
3376
*Note String Field::, for more information about their use.
3377
 
3378
`DIGIT'
3379
`('
3380
     Type reference; see *Note String Field::.
3381
 
3382
`-'
3383
     Reference to builtin type; see *Note Negative Type Numbers::.
3384
 
3385
`#'
3386
     Method (C++); see *Note Method Type Descriptor::.
3387
 
3388
`*'
3389
     Pointer; see *Note Miscellaneous Types::.
3390
 
3391
`&'
3392
     Reference (C++).
3393
 
3394
`@'
3395
     Type Attributes (AIX); see *Note String Field::.  Member (class
3396
     and variable) type (GNU C++); see *Note Member Type Descriptor::.
3397
 
3398
`a'
3399
     Array; see *Note Arrays::.
3400
 
3401
`A'
3402
     Open array; see *Note Arrays::.
3403
 
3404
`b'
3405
     Pascal space type (AIX); see *Note Miscellaneous Types::.  Builtin
3406
     integer type (Sun); see *Note Builtin Type Descriptors::.  Const
3407
     and volatile qualified type (OS9000).
3408
 
3409
`B'
3410
     Volatile-qualified type; see *Note Miscellaneous Types::.
3411
 
3412
`c'
3413
     Complex builtin type (AIX); see *Note Builtin Type Descriptors::.
3414
     Const-qualified type (OS9000).
3415
 
3416
`C'
3417
     COBOL Picture type.  See AIX documentation for details.
3418
 
3419
`d'
3420
     File type; see *Note Miscellaneous Types::.
3421
 
3422
`D'
3423
     N-dimensional dynamic array; see *Note Arrays::.
3424
 
3425
`e'
3426
     Enumeration type; see *Note Enumerations::.
3427
 
3428
`E'
3429
     N-dimensional subarray; see *Note Arrays::.
3430
 
3431
`f'
3432
     Function type; see *Note Function Types::.
3433
 
3434
`F'
3435
     Pascal function parameter; see *Note Function Types::
3436
 
3437
`g'
3438
     Builtin floating point type; see *Note Builtin Type Descriptors::.
3439
 
3440
`G'
3441
     COBOL Group.  See AIX documentation for details.
3442
 
3443
`i'
3444
     Imported type (AIX); see *Note Cross-References::.
3445
     Volatile-qualified type (OS9000).
3446
 
3447
`k'
3448
     Const-qualified type; see *Note Miscellaneous Types::.
3449
 
3450
`K'
3451
     COBOL File Descriptor.  See AIX documentation for details.
3452
 
3453
`M'
3454
     Multiple instance type; see *Note Miscellaneous Types::.
3455
 
3456
`n'
3457
     String type; see *Note Strings::.
3458
 
3459
`N'
3460
     Stringptr; see *Note Strings::.
3461
 
3462
`o'
3463
     Opaque type; see *Note Typedefs::.
3464
 
3465
`p'
3466
     Procedure; see *Note Function Types::.
3467
 
3468
`P'
3469
     Packed array; see *Note Arrays::.
3470
 
3471
`r'
3472
     Range type; see *Note Subranges::.
3473
 
3474
`R'
3475
     Builtin floating type; see *Note Builtin Type Descriptors:: (Sun).
3476
     Pascal subroutine parameter; see *Note Function Types:: (AIX).
3477
     Detecting this conflict is possible with careful parsing (hint: a
3478
     Pascal subroutine parameter type will always contain a comma, and
3479
     a builtin type descriptor never will).
3480
 
3481
`s'
3482
     Structure type; see *Note Structures::.
3483
 
3484
`S'
3485
     Set type; see *Note Miscellaneous Types::.
3486
 
3487
`u'
3488
     Union; see *Note Unions::.
3489
 
3490
`v'
3491
     Variant record.  This is a Pascal and Modula-2 feature which is
3492
     like a union within a struct in C.  See AIX documentation for
3493
     details.
3494
 
3495
`w'
3496
     Wide character; see *Note Builtin Type Descriptors::.
3497
 
3498
`x'
3499
     Cross-reference; see *Note Cross-References::.
3500
 
3501
`Y'
3502
     Used by IBM's xlC C++ compiler (for structures, I think).
3503
 
3504
`z'
3505
     gstring; see *Note Strings::.
3506
 
3507

3508
File: stabs.info,  Node: Expanded Reference,  Next: Questions,  Prev: Type Descriptors,  Up: Top
3509
 
3510
Appendix D Expanded Reference by Stab Type
3511
******************************************
3512
 
3513
For a full list of stab types, and cross-references to where they are
3514
described, see *Note Stab Types::.  This appendix just covers certain
3515
stabs which are not yet described in the main body of this document;
3516
eventually the information will all be in one place.
3517
 
3518
   Format of an entry:
3519
 
3520
   The first line is the symbol type (see `include/aout/stab.def').
3521
 
3522
   The second line describes the language constructs the symbol type
3523
represents.
3524
 
3525
   The third line is the stab format with the significant stab fields
3526
named and the rest NIL.
3527
 
3528
   Subsequent lines expand upon the meaning and possible values for each
3529
significant stab field.
3530
 
3531
   Finally, any further information.
3532
 
3533
* Menu:
3534
 
3535
* N_PC::                        Pascal global symbol
3536
* N_NSYMS::                     Number of symbols
3537
* N_NOMAP::                     No DST map
3538
* N_M2C::                       Modula-2 compilation unit
3539
* N_BROWS::                     Path to .cb file for Sun source code browser
3540
* N_DEFD::                      GNU Modula2 definition module dependency
3541
* N_EHDECL::                    GNU C++ exception variable
3542
* N_MOD2::                      Modula2 information "for imc"
3543
* N_CATCH::                     GNU C++ "catch" clause
3544
* N_SSYM::                      Structure or union element
3545
* N_SCOPE::                     Modula2 scope information (Sun only)
3546
* Gould::                       non-base register symbols used on Gould systems
3547
* N_LENG::                      Length of preceding entry
3548
 
3549

3550
File: stabs.info,  Node: N_PC,  Next: N_NSYMS,  Up: Expanded Reference
3551
 
3552
D.1 N_PC
3553
========
3554
 
3555
 -- `.stabs': N_PC
3556
     Global symbol (for Pascal).
3557
 
3558
          "name" -> "symbol_name"  <>
3559
          value  -> supposedly the line number (stab.def is skeptical)
3560
 
3561
          `stabdump.c' says:
3562
 
3563
          global pascal symbol: name,,0,subtype,line
3564
          << subtype? >>
3565
 
3566

3567
File: stabs.info,  Node: N_NSYMS,  Next: N_NOMAP,  Prev: N_PC,  Up: Expanded Reference
3568
 
3569
D.2 N_NSYMS
3570
===========
3571
 
3572
 -- `.stabn': N_NSYMS
3573
     Number of symbols (according to Ultrix V4.0).
3574
 
3575
                  0, files,,funcs,lines (stab.def)
3576
 
3577

3578
File: stabs.info,  Node: N_NOMAP,  Next: N_M2C,  Prev: N_NSYMS,  Up: Expanded Reference
3579
 
3580
D.3 N_NOMAP
3581
===========
3582
 
3583
 -- `.stabs': N_NOMAP
3584
     No DST map for symbol (according to Ultrix V4.0).  I think this
3585
     means a variable has been optimized out.
3586
 
3587
                  name, ,0,type,ignored (stab.def)
3588
 
3589

3590
File: stabs.info,  Node: N_M2C,  Next: N_BROWS,  Prev: N_NOMAP,  Up: Expanded Reference
3591
 
3592
D.4 N_M2C
3593
=========
3594
 
3595
 -- `.stabs': N_M2C
3596
     Modula-2 compilation unit.
3597
 
3598
          "string" -> "unit_name,unit_time_stamp[,code_time_stamp]"
3599
          desc   -> unit_number
3600
          value  -> 0 (main unit)
3601
                    1 (any other unit)
3602
 
3603
     See `Dbx and Dbxtool Interfaces', 2nd edition, by Sun, 1988, for
3604
     more information.
3605
 
3606
 
3607

3608
File: stabs.info,  Node: N_BROWS,  Next: N_DEFD,  Prev: N_M2C,  Up: Expanded Reference
3609
 
3610
D.5 N_BROWS
3611
===========
3612
 
3613
 -- `.stabs': N_BROWS
3614
     Sun source code browser, path to `.cb' file
3615
 
3616
     <> "path to associated `.cb' file"
3617
 
3618
     Note: N_BROWS has the same value as N_BSLINE.
3619
 
3620

3621
File: stabs.info,  Node: N_DEFD,  Next: N_EHDECL,  Prev: N_BROWS,  Up: Expanded Reference
3622
 
3623
D.6 N_DEFD
3624
==========
3625
 
3626
 -- `.stabn': N_DEFD
3627
     GNU Modula2 definition module dependency.
3628
 
3629
     GNU Modula-2 definition module dependency.  The value is the
3630
     modification time of the definition file.  The other field is
3631
     non-zero if it is imported with the GNU M2 keyword `%INITIALIZE'.
3632
     Perhaps `N_M2C' can be used if there are enough empty fields?
3633
 
3634

3635
File: stabs.info,  Node: N_EHDECL,  Next: N_MOD2,  Prev: N_DEFD,  Up: Expanded Reference
3636
 
3637
D.7 N_EHDECL
3638
============
3639
 
3640
 -- `.stabs': N_EHDECL
3641
     GNU C++ exception variable <>.
3642
 
3643
     "STRING is variable name"
3644
 
3645
     Note: conflicts with `N_MOD2'.
3646
 
3647

3648
File: stabs.info,  Node: N_MOD2,  Next: N_CATCH,  Prev: N_EHDECL,  Up: Expanded Reference
3649
 
3650
D.8 N_MOD2
3651
==========
3652
 
3653
 -- `.stab?': N_MOD2
3654
     Modula2 info "for imc" (according to Ultrix V4.0)
3655
 
3656
     Note: conflicts with `N_EHDECL'  <>
3657
 
3658

3659
File: stabs.info,  Node: N_CATCH,  Next: N_SSYM,  Prev: N_MOD2,  Up: Expanded Reference
3660
 
3661
D.9 N_CATCH
3662
===========
3663
 
3664
 -- `.stabn': N_CATCH
3665
     GNU C++ `catch' clause
3666
 
3667
     GNU C++ `catch' clause.  The value is its address.  The desc field
3668
     is nonzero if this entry is immediately followed by a `CAUGHT' stab
3669
     saying what exception was caught.  Multiple `CAUGHT' stabs means
3670
     that multiple exceptions can be caught here.  If desc is 0, it
3671
     means all exceptions are caught here.
3672
 
3673

3674
File: stabs.info,  Node: N_SSYM,  Next: N_SCOPE,  Prev: N_CATCH,  Up: Expanded Reference
3675
 
3676
D.10 N_SSYM
3677
===========
3678
 
3679
 -- `.stabn': N_SSYM
3680
     Structure or union element.
3681
 
3682
     The value is the offset in the structure.
3683
 
3684
     <>
3685
 
3686

3687
File: stabs.info,  Node: N_SCOPE,  Next: Gould,  Prev: N_SSYM,  Up: Expanded Reference
3688
 
3689
D.11 N_SCOPE
3690
============
3691
 
3692
 -- `.stab?': N_SCOPE
3693
     Modula2 scope information (Sun linker) <>
3694
 
3695

3696
File: stabs.info,  Node: Gould,  Next: N_LENG,  Prev: N_SCOPE,  Up: Expanded Reference
3697
 
3698
D.12 Non-base registers on Gould systems
3699
========================================
3700
 
3701
 -- `.stab?': N_NBTEXT
3702
 -- `.stab?': N_NBDATA
3703
 -- `.stab?': N_NBBSS
3704
 -- `.stab?': N_NBSTS
3705
 -- `.stab?': N_NBLCS
3706
     These are used on Gould systems for non-base registers syms.
3707
 
3708
     However, the following values are not the values used by Gould;
3709
     they are the values which GNU has been documenting for these
3710
     values for a long time, without actually checking what Gould uses.
3711
     I include these values only because perhaps some someone actually
3712
     did something with the GNU information (I hope not, why GNU
3713
     knowingly assigned wrong values to these in the header file is a
3714
     complete mystery to me).
3715
 
3716
          240    0xf0     N_NBTEXT  ??
3717
          242    0xf2     N_NBDATA  ??
3718
          244    0xf4     N_NBBSS   ??
3719
          246    0xf6     N_NBSTS   ??
3720
          248    0xf8     N_NBLCS   ??
3721
 
3722

3723
File: stabs.info,  Node: N_LENG,  Prev: Gould,  Up: Expanded Reference
3724
 
3725
D.13 N_LENG
3726
===========
3727
 
3728
 -- `.stabn': N_LENG
3729
     Second symbol entry containing a length-value for the preceding
3730
     entry.  The value is the length.
3731
 
3732

3733
File: stabs.info,  Node: Questions,  Next: Stab Sections,  Prev: Expanded Reference,  Up: Top
3734
 
3735
Appendix E Questions and Anomalies
3736
**********************************
3737
 
3738
   * For GNU C stabs defining local and global variables (`N_LSYM' and
3739
     `N_GSYM'), the desc field is supposed to contain the source line
3740
     number on which the variable is defined.  In reality the desc
3741
     field is always 0.  (This behavior is defined in `dbxout.c' and
3742
     putting a line number in desc is controlled by `#ifdef
3743
     WINNING_GDB', which defaults to false). GDB supposedly uses this
3744
     information if you say `list VAR'.  In reality, VAR can be a
3745
     variable defined in the program and GDB says `function VAR not
3746
     defined'.
3747
 
3748
   * In GNU C stabs, there seems to be no way to differentiate tag
3749
     types: structures, unions, and enums (symbol descriptor `T') and
3750
     typedefs (symbol descriptor `t') defined at file scope from types
3751
     defined locally to a procedure or other more local scope.  They
3752
     all use the `N_LSYM' stab type.  Types defined at procedure scope
3753
     are emitted after the `N_RBRAC' of the preceding function and
3754
     before the code of the procedure in which they are defined.  This
3755
     is exactly the same as types defined in the source file between
3756
     the two procedure bodies.  GDB over-compensates by placing all
3757
     types in block #1, the block for symbols of file scope.  This is
3758
     true for default, `-ansi' and `-traditional' compiler options.
3759
     (Bugs gcc/1063, gdb/1066.)
3760
 
3761
   * What ends the procedure scope?  Is it the proc block's `N_RBRAC'
3762
     or the next `N_FUN'?  (I believe its the first.)
3763
 
3764

3765
File: stabs.info,  Node: Stab Sections,  Next: Symbol Types Index,  Prev: Questions,  Up: Top
3766
 
3767
Appendix F Using Stabs in Their Own Sections
3768
********************************************
3769
 
3770
Many object file formats allow tools to create object files with custom
3771
sections containing any arbitrary data.  For any such object file
3772
format, stabs can be embedded in special sections.  This is how stabs
3773
are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs
3774
are used with COFF.
3775
 
3776
* Menu:
3777
 
3778
* Stab Section Basics::    How to embed stabs in sections
3779
* ELF Linker Relocation::  Sun ELF hacks
3780
 
3781

3782
File: stabs.info,  Node: Stab Section Basics,  Next: ELF Linker Relocation,  Up: Stab Sections
3783
 
3784
F.1 How to Embed Stabs in Sections
3785
==================================
3786
 
3787
The assembler creates two custom sections, a section named `.stab'
3788
which contains an array of fixed length structures, one struct per stab,
3789
and a section named `.stabstr' containing all the variable length
3790
strings that are referenced by stabs in the `.stab' section.  The byte
3791
order of the stabs binary data depends on the object file format.  For
3792
ELF, it matches the byte order of the ELF file itself, as determined
3793
from the `EI_DATA' field in the `e_ident' member of the ELF header.
3794
For SOM, it is always big-endian (is this true??? FIXME).  For COFF, it
3795
matches the byte order of the COFF headers.  The meaning of the fields
3796
is the same as for a.out (*note Symbol Table Format::), except that the
3797
`n_strx' field is relative to the strings for the current compilation
3798
unit (which can be found using the synthetic N_UNDF stab described
3799
below), rather than the entire string table.
3800
 
3801
   The first stab in the `.stab' section for each compilation unit is
3802
synthetic, generated entirely by the assembler, with no corresponding
3803
`.stab' directive as input to the assembler.  This stab contains the
3804
following fields:
3805
 
3806
`n_strx'
3807
     Offset in the `.stabstr' section to the source filename.
3808
 
3809
`n_type'
3810
     `N_UNDF'.
3811
 
3812
`n_other'
3813
     Unused field, always zero.  This may eventually be used to hold
3814
     overflows from the count in the `n_desc' field.
3815
 
3816
`n_desc'
3817
     Count of upcoming symbols, i.e., the number of remaining stabs for
3818
     this source file.
3819
 
3820
`n_value'
3821
     Size of the string table fragment associated with this source
3822
     file, in bytes.
3823
 
3824
   The `.stabstr' section always starts with a null byte (so that string
3825
offsets of zero reference a null string), followed by random length
3826
strings, each of which is null byte terminated.
3827
 
3828
   The ELF section header for the `.stab' section has its `sh_link'
3829
member set to the section number of the `.stabstr' section, and the
3830
`.stabstr' section has its ELF section header `sh_type' member set to
3831
`SHT_STRTAB' to mark it as a string table.  SOM and COFF have no way of
3832
linking the sections together or marking them as string tables.
3833
 
3834
   For COFF, the `.stab' and `.stabstr' sections may be simply
3835
concatenated by the linker.  GDB then uses the `n_desc' fields to
3836
figure out the extent of the original sections.  Similarly, the
3837
`n_value' fields of the header symbols are added together in order to
3838
get the actual position of the strings in a desired `.stabstr' section.
3839
Although this design obviates any need for the linker to relocate or
3840
otherwise manipulate `.stab' and `.stabstr' sections, it also requires
3841
some care to ensure that the offsets are calculated correctly.  For
3842
instance, if the linker were to pad in between the `.stabstr' sections
3843
before concatenating, then the offsets to strings in the middle of the
3844
executable's `.stabstr' section would be wrong.
3845
 
3846
   The GNU linker is able to optimize stabs information by merging
3847
duplicate strings and removing duplicate header file information (*note
3848
Include Files::).  When some versions of the GNU linker optimize stabs
3849
in sections, they remove the leading `N_UNDF' symbol and arranges for
3850
all the `n_strx' fields to be relative to the start of the `.stabstr'
3851
section.
3852
 
3853

3854
File: stabs.info,  Node: ELF Linker Relocation,  Prev: Stab Section Basics,  Up: Stab Sections
3855
 
3856
F.2 Having the Linker Relocate Stabs in ELF
3857
===========================================
3858
 
3859
This section describes some Sun hacks for Stabs in ELF; it does not
3860
apply to COFF or SOM.
3861
 
3862
   To keep linking fast, you don't want the linker to have to relocate
3863
very many stabs.  Making sure this is done for `N_SLINE', `N_RBRAC',
3864
and `N_LBRAC' stabs is the most important thing (see the descriptions
3865
of those stabs for more information).  But Sun's stabs in ELF has taken
3866
this further, to make all addresses in the `n_value' field (functions
3867
and static variables) relative to the source file.  For the `N_SO'
3868
symbol itself, Sun simply omits the address.  To find the address of
3869
each section corresponding to a given source file, the compiler puts
3870
out symbols giving the address of each section for a given source file.
3871
Since these are ELF (not stab) symbols, the linker relocates them
3872
correctly without having to touch the stabs section.  They are named
3873
`Bbss.bss' for the bss section, `Ddata.data' for the data section, and
3874
`Drodata.rodata' for the rodata section.  For the text section, there
3875
is no such symbol (but there should be, see below).  For an example of
3876
how these symbols work, *Note Stab Section Transformations::.  GCC does
3877
not provide these symbols; it instead relies on the stabs getting
3878
relocated.  Thus addresses which would normally be relative to
3879
`Bbss.bss', etc., are already relocated.  The Sun linker provided with
3880
Solaris 2.2 and earlier relocates stabs using normal ELF relocation
3881
information, as it would do for any section.  Sun has been threatening
3882
to kludge their linker to not do this (to speed up linking), even
3883
though the correct way to avoid having the linker do these relocations
3884
is to have the compiler no longer output relocatable values.  Last I
3885
heard they had been talked out of the linker kludge.  See Sun point
3886
patch 101052-01 and Sun bug 1142109.  With the Sun compiler this
3887
affects `S' symbol descriptor stabs (*note Statics::) and functions
3888
(*note Procedures::).  In the latter case, to adopt the clean solution
3889
(making the value of the stab relative to the start of the compilation
3890
unit), it would be necessary to invent a `Ttext.text' symbol, analogous
3891
to the `Bbss.bss', etc., symbols.  I recommend this rather than using a
3892
zero value and getting the address from the ELF symbols.
3893
 
3894
   Finding the correct `Bbss.bss', etc., symbol is difficult, because
3895
the linker simply concatenates the `.stab' sections from each `.o' file
3896
without including any information about which part of a `.stab' section
3897
comes from which `.o' file.  The way GDB does this is to look for an
3898
ELF `STT_FILE' symbol which has the same name as the last component of
3899
the file name from the `N_SO' symbol in the stabs (for example, if the
3900
file name is `../../gdb/main.c', it looks for an ELF `STT_FILE' symbol
3901
named `main.c').  This loses if different files have the same name
3902
(they could be in different directories, a library could have been
3903
copied from one system to another, etc.).  It would be much cleaner to
3904
have the `Bbss.bss' symbols in the stabs themselves.  Having the linker
3905
relocate them there is no more work than having the linker relocate ELF
3906
symbols, and it solves the problem of having to associate the ELF and
3907
stab symbols.  However, no one has yet designed or implemented such a
3908
scheme.
3909
 
3910

3911
File: stabs.info,  Node: GNU Free Documentation License,  Prev: Symbol Types Index,  Up: Top
3912
 
3913
Appendix G GNU Free Documentation License
3914
*****************************************
3915
 
3916
                      Version 1.2, November 2002
3917
 
3918
     Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
3919
     51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
3920
 
3921
     Everyone is permitted to copy and distribute verbatim copies
3922
     of this license document, but changing it is not allowed.
3923
 
3924
  0. PREAMBLE
3925
 
3926
     The purpose of this License is to make a manual, textbook, or other
3927
     functional and useful document "free" in the sense of freedom: to
3928
     assure everyone the effective freedom to copy and redistribute it,
3929
     with or without modifying it, either commercially or
3930
     noncommercially.  Secondarily, this License preserves for the
3931
     author and publisher a way to get credit for their work, while not
3932
     being considered responsible for modifications made by others.
3933
 
3934
     This License is a kind of "copyleft", which means that derivative
3935
     works of the document must themselves be free in the same sense.
3936
     It complements the GNU General Public License, which is a copyleft
3937
     license designed for free software.
3938
 
3939
     We have designed this License in order to use it for manuals for
3940
     free software, because free software needs free documentation: a
3941
     free program should come with manuals providing the same freedoms
3942
     that the software does.  But this License is not limited to
3943
     software manuals; it can be used for any textual work, regardless
3944
     of subject matter or whether it is published as a printed book.
3945
     We recommend this License principally for works whose purpose is
3946
     instruction or reference.
3947
 
3948
  1. APPLICABILITY AND DEFINITIONS
3949
 
3950
     This License applies to any manual or other work, in any medium,
3951
     that contains a notice placed by the copyright holder saying it
3952
     can be distributed under the terms of this License.  Such a notice
3953
     grants a world-wide, royalty-free license, unlimited in duration,
3954
     to use that work under the conditions stated herein.  The
3955
     "Document", below, refers to any such manual or work.  Any member
3956
     of the public is a licensee, and is addressed as "you".  You
3957
     accept the license if you copy, modify or distribute the work in a
3958
     way requiring permission under copyright law.
3959
 
3960
     A "Modified Version" of the Document means any work containing the
3961
     Document or a portion of it, either copied verbatim, or with
3962
     modifications and/or translated into another language.
3963
 
3964
     A "Secondary Section" is a named appendix or a front-matter section
3965
     of the Document that deals exclusively with the relationship of the
3966
     publishers or authors of the Document to the Document's overall
3967
     subject (or to related matters) and contains nothing that could
3968
     fall directly within that overall subject.  (Thus, if the Document
3969
     is in part a textbook of mathematics, a Secondary Section may not
3970
     explain any mathematics.)  The relationship could be a matter of
3971
     historical connection with the subject or with related matters, or
3972
     of legal, commercial, philosophical, ethical or political position
3973
     regarding them.
3974
 
3975
     The "Invariant Sections" are certain Secondary Sections whose
3976
     titles are designated, as being those of Invariant Sections, in
3977
     the notice that says that the Document is released under this
3978
     License.  If a section does not fit the above definition of
3979
     Secondary then it is not allowed to be designated as Invariant.
3980
     The Document may contain zero Invariant Sections.  If the Document
3981
     does not identify any Invariant Sections then there are none.
3982
 
3983
     The "Cover Texts" are certain short passages of text that are
3984
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
3985
     that says that the Document is released under this License.  A
3986
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
3987
     be at most 25 words.
3988
 
3989
     A "Transparent" copy of the Document means a machine-readable copy,
3990
     represented in a format whose specification is available to the
3991
     general public, that is suitable for revising the document
3992
     straightforwardly with generic text editors or (for images
3993
     composed of pixels) generic paint programs or (for drawings) some
3994
     widely available drawing editor, and that is suitable for input to
3995
     text formatters or for automatic translation to a variety of
3996
     formats suitable for input to text formatters.  A copy made in an
3997
     otherwise Transparent file format whose markup, or absence of
3998
     markup, has been arranged to thwart or discourage subsequent
3999
     modification by readers is not Transparent.  An image format is
4000
     not Transparent if used for any substantial amount of text.  A
4001
     copy that is not "Transparent" is called "Opaque".
4002
 
4003
     Examples of suitable formats for Transparent copies include plain
4004
     ASCII without markup, Texinfo input format, LaTeX input format,
4005
     SGML or XML using a publicly available DTD, and
4006
     standard-conforming simple HTML, PostScript or PDF designed for
4007
     human modification.  Examples of transparent image formats include
4008
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
4009
     can be read and edited only by proprietary word processors, SGML or
4010
     XML for which the DTD and/or processing tools are not generally
4011
     available, and the machine-generated HTML, PostScript or PDF
4012
     produced by some word processors for output purposes only.
4013
 
4014
     The "Title Page" means, for a printed book, the title page itself,
4015
     plus such following pages as are needed to hold, legibly, the
4016
     material this License requires to appear in the title page.  For
4017
     works in formats which do not have any title page as such, "Title
4018
     Page" means the text near the most prominent appearance of the
4019
     work's title, preceding the beginning of the body of the text.
4020
 
4021
     A section "Entitled XYZ" means a named subunit of the Document
4022
     whose title either is precisely XYZ or contains XYZ in parentheses
4023
     following text that translates XYZ in another language.  (Here XYZ
4024
     stands for a specific section name mentioned below, such as
4025
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
4026
     To "Preserve the Title" of such a section when you modify the
4027
     Document means that it remains a section "Entitled XYZ" according
4028
     to this definition.
4029
 
4030
     The Document may include Warranty Disclaimers next to the notice
4031
     which states that this License applies to the Document.  These
4032
     Warranty Disclaimers are considered to be included by reference in
4033
     this License, but only as regards disclaiming warranties: any other
4034
     implication that these Warranty Disclaimers may have is void and
4035
     has no effect on the meaning of this License.
4036
 
4037
  2. VERBATIM COPYING
4038
 
4039
     You may copy and distribute the Document in any medium, either
4040
     commercially or noncommercially, provided that this License, the
4041
     copyright notices, and the license notice saying this License
4042
     applies to the Document are reproduced in all copies, and that you
4043
     add no other conditions whatsoever to those of this License.  You
4044
     may not use technical measures to obstruct or control the reading
4045
     or further copying of the copies you make or distribute.  However,
4046
     you may accept compensation in exchange for copies.  If you
4047
     distribute a large enough number of copies you must also follow
4048
     the conditions in section 3.
4049
 
4050
     You may also lend copies, under the same conditions stated above,
4051
     and you may publicly display copies.
4052
 
4053
  3. COPYING IN QUANTITY
4054
 
4055
     If you publish printed copies (or copies in media that commonly
4056
     have printed covers) of the Document, numbering more than 100, and
4057
     the Document's license notice requires Cover Texts, you must
4058
     enclose the copies in covers that carry, clearly and legibly, all
4059
     these Cover Texts: Front-Cover Texts on the front cover, and
4060
     Back-Cover Texts on the back cover.  Both covers must also clearly
4061
     and legibly identify you as the publisher of these copies.  The
4062
     front cover must present the full title with all words of the
4063
     title equally prominent and visible.  You may add other material
4064
     on the covers in addition.  Copying with changes limited to the
4065
     covers, as long as they preserve the title of the Document and
4066
     satisfy these conditions, can be treated as verbatim copying in
4067
     other respects.
4068
 
4069
     If the required texts for either cover are too voluminous to fit
4070
     legibly, you should put the first ones listed (as many as fit
4071
     reasonably) on the actual cover, and continue the rest onto
4072
     adjacent pages.
4073
 
4074
     If you publish or distribute Opaque copies of the Document
4075
     numbering more than 100, you must either include a
4076
     machine-readable Transparent copy along with each Opaque copy, or
4077
     state in or with each Opaque copy a computer-network location from
4078
     which the general network-using public has access to download
4079
     using public-standard network protocols a complete Transparent
4080
     copy of the Document, free of added material.  If you use the
4081
     latter option, you must take reasonably prudent steps, when you
4082
     begin distribution of Opaque copies in quantity, to ensure that
4083
     this Transparent copy will remain thus accessible at the stated
4084
     location until at least one year after the last time you
4085
     distribute an Opaque copy (directly or through your agents or
4086
     retailers) of that edition to the public.
4087
 
4088
     It is requested, but not required, that you contact the authors of
4089
     the Document well before redistributing any large number of
4090
     copies, to give them a chance to provide you with an updated
4091
     version of the Document.
4092
 
4093
  4. MODIFICATIONS
4094
 
4095
     You may copy and distribute a Modified Version of the Document
4096
     under the conditions of sections 2 and 3 above, provided that you
4097
     release the Modified Version under precisely this License, with
4098
     the Modified Version filling the role of the Document, thus
4099
     licensing distribution and modification of the Modified Version to
4100
     whoever possesses a copy of it.  In addition, you must do these
4101
     things in the Modified Version:
4102
 
4103
       A. Use in the Title Page (and on the covers, if any) a title
4104
          distinct from that of the Document, and from those of
4105
          previous versions (which should, if there were any, be listed
4106
          in the History section of the Document).  You may use the
4107
          same title as a previous version if the original publisher of
4108
          that version gives permission.
4109
 
4110
       B. List on the Title Page, as authors, one or more persons or
4111
          entities responsible for authorship of the modifications in
4112
          the Modified Version, together with at least five of the
4113
          principal authors of the Document (all of its principal
4114
          authors, if it has fewer than five), unless they release you
4115
          from this requirement.
4116
 
4117
       C. State on the Title page the name of the publisher of the
4118
          Modified Version, as the publisher.
4119
 
4120
       D. Preserve all the copyright notices of the Document.
4121
 
4122
       E. Add an appropriate copyright notice for your modifications
4123
          adjacent to the other copyright notices.
4124
 
4125
       F. Include, immediately after the copyright notices, a license
4126
          notice giving the public permission to use the Modified
4127
          Version under the terms of this License, in the form shown in
4128
          the Addendum below.
4129
 
4130
       G. Preserve in that license notice the full lists of Invariant
4131
          Sections and required Cover Texts given in the Document's
4132
          license notice.
4133
 
4134
       H. Include an unaltered copy of this License.
4135
 
4136
       I. Preserve the section Entitled "History", Preserve its Title,
4137
          and add to it an item stating at least the title, year, new
4138
          authors, and publisher of the Modified Version as given on
4139
          the Title Page.  If there is no section Entitled "History" in
4140
          the Document, create one stating the title, year, authors,
4141
          and publisher of the Document as given on its Title Page,
4142
          then add an item describing the Modified Version as stated in
4143
          the previous sentence.
4144
 
4145
       J. Preserve the network location, if any, given in the Document
4146
          for public access to a Transparent copy of the Document, and
4147
          likewise the network locations given in the Document for
4148
          previous versions it was based on.  These may be placed in
4149
          the "History" section.  You may omit a network location for a
4150
          work that was published at least four years before the
4151
          Document itself, or if the original publisher of the version
4152
          it refers to gives permission.
4153
 
4154
       K. For any section Entitled "Acknowledgements" or "Dedications",
4155
          Preserve the Title of the section, and preserve in the
4156
          section all the substance and tone of each of the contributor
4157
          acknowledgements and/or dedications given therein.
4158
 
4159
       L. Preserve all the Invariant Sections of the Document,
4160
          unaltered in their text and in their titles.  Section numbers
4161
          or the equivalent are not considered part of the section
4162
          titles.
4163
 
4164
       M. Delete any section Entitled "Endorsements".  Such a section
4165
          may not be included in the Modified Version.
4166
 
4167
       N. Do not retitle any existing section to be Entitled
4168
          "Endorsements" or to conflict in title with any Invariant
4169
          Section.
4170
 
4171
       O. Preserve any Warranty Disclaimers.
4172
 
4173
     If the Modified Version includes new front-matter sections or
4174
     appendices that qualify as Secondary Sections and contain no
4175
     material copied from the Document, you may at your option
4176
     designate some or all of these sections as invariant.  To do this,
4177
     add their titles to the list of Invariant Sections in the Modified
4178
     Version's license notice.  These titles must be distinct from any
4179
     other section titles.
4180
 
4181
     You may add a section Entitled "Endorsements", provided it contains
4182
     nothing but endorsements of your Modified Version by various
4183
     parties--for example, statements of peer review or that the text
4184
     has been approved by an organization as the authoritative
4185
     definition of a standard.
4186
 
4187
     You may add a passage of up to five words as a Front-Cover Text,
4188
     and a passage of up to 25 words as a Back-Cover Text, to the end
4189
     of the list of Cover Texts in the Modified Version.  Only one
4190
     passage of Front-Cover Text and one of Back-Cover Text may be
4191
     added by (or through arrangements made by) any one entity.  If the
4192
     Document already includes a cover text for the same cover,
4193
     previously added by you or by arrangement made by the same entity
4194
     you are acting on behalf of, you may not add another; but you may
4195
     replace the old one, on explicit permission from the previous
4196
     publisher that added the old one.
4197
 
4198
     The author(s) and publisher(s) of the Document do not by this
4199
     License give permission to use their names for publicity for or to
4200
     assert or imply endorsement of any Modified Version.
4201
 
4202
  5. COMBINING DOCUMENTS
4203
 
4204
     You may combine the Document with other documents released under
4205
     this License, under the terms defined in section 4 above for
4206
     modified versions, provided that you include in the combination
4207
     all of the Invariant Sections of all of the original documents,
4208
     unmodified, and list them all as Invariant Sections of your
4209
     combined work in its license notice, and that you preserve all
4210
     their Warranty Disclaimers.
4211
 
4212
     The combined work need only contain one copy of this License, and
4213
     multiple identical Invariant Sections may be replaced with a single
4214
     copy.  If there are multiple Invariant Sections with the same name
4215
     but different contents, make the title of each such section unique
4216
     by adding at the end of it, in parentheses, the name of the
4217
     original author or publisher of that section if known, or else a
4218
     unique number.  Make the same adjustment to the section titles in
4219
     the list of Invariant Sections in the license notice of the
4220
     combined work.
4221
 
4222
     In the combination, you must combine any sections Entitled
4223
     "History" in the various original documents, forming one section
4224
     Entitled "History"; likewise combine any sections Entitled
4225
     "Acknowledgements", and any sections Entitled "Dedications".  You
4226
     must delete all sections Entitled "Endorsements."
4227
 
4228
  6. COLLECTIONS OF DOCUMENTS
4229
 
4230
     You may make a collection consisting of the Document and other
4231
     documents released under this License, and replace the individual
4232
     copies of this License in the various documents with a single copy
4233
     that is included in the collection, provided that you follow the
4234
     rules of this License for verbatim copying of each of the
4235
     documents in all other respects.
4236
 
4237
     You may extract a single document from such a collection, and
4238
     distribute it individually under this License, provided you insert
4239
     a copy of this License into the extracted document, and follow
4240
     this License in all other respects regarding verbatim copying of
4241
     that document.
4242
 
4243
  7. AGGREGATION WITH INDEPENDENT WORKS
4244
 
4245
     A compilation of the Document or its derivatives with other
4246
     separate and independent documents or works, in or on a volume of
4247
     a storage or distribution medium, is called an "aggregate" if the
4248
     copyright resulting from the compilation is not used to limit the
4249
     legal rights of the compilation's users beyond what the individual
4250
     works permit.  When the Document is included in an aggregate, this
4251
     License does not apply to the other works in the aggregate which
4252
     are not themselves derivative works of the Document.
4253
 
4254
     If the Cover Text requirement of section 3 is applicable to these
4255
     copies of the Document, then if the Document is less than one half
4256
     of the entire aggregate, the Document's Cover Texts may be placed
4257
     on covers that bracket the Document within the aggregate, or the
4258
     electronic equivalent of covers if the Document is in electronic
4259
     form.  Otherwise they must appear on printed covers that bracket
4260
     the whole aggregate.
4261
 
4262
  8. TRANSLATION
4263
 
4264
     Translation is considered a kind of modification, so you may
4265
     distribute translations of the Document under the terms of section
4266
     4.  Replacing Invariant Sections with translations requires special
4267
     permission from their copyright holders, but you may include
4268
     translations of some or all Invariant Sections in addition to the
4269
     original versions of these Invariant Sections.  You may include a
4270
     translation of this License, and all the license notices in the
4271
     Document, and any Warranty Disclaimers, provided that you also
4272
     include the original English version of this License and the
4273
     original versions of those notices and disclaimers.  In case of a
4274
     disagreement between the translation and the original version of
4275
     this License or a notice or disclaimer, the original version will
4276
     prevail.
4277
 
4278
     If a section in the Document is Entitled "Acknowledgements",
4279
     "Dedications", or "History", the requirement (section 4) to
4280
     Preserve its Title (section 1) will typically require changing the
4281
     actual title.
4282
 
4283
  9. TERMINATION
4284
 
4285
     You may not copy, modify, sublicense, or distribute the Document
4286
     except as expressly provided for under this License.  Any other
4287
     attempt to copy, modify, sublicense or distribute the Document is
4288
     void, and will automatically terminate your rights under this
4289
     License.  However, parties who have received copies, or rights,
4290
     from you under this License will not have their licenses
4291
     terminated so long as such parties remain in full compliance.
4292
 
4293
 10. FUTURE REVISIONS OF THIS LICENSE
4294
 
4295
     The Free Software Foundation may publish new, revised versions of
4296
     the GNU Free Documentation License from time to time.  Such new
4297
     versions will be similar in spirit to the present version, but may
4298
     differ in detail to address new problems or concerns.  See
4299
     `http://www.gnu.org/copyleft/'.
4300
 
4301
     Each version of the License is given a distinguishing version
4302
     number.  If the Document specifies that a particular numbered
4303
     version of this License "or any later version" applies to it, you
4304
     have the option of following the terms and conditions either of
4305
     that specified version or of any later version that has been
4306
     published (not as a draft) by the Free Software Foundation.  If
4307
     the Document does not specify a version number of this License,
4308
     you may choose any version ever published (not as a draft) by the
4309
     Free Software Foundation.
4310
 
4311
G.1 ADDENDUM: How to use this License for your documents
4312
========================================================
4313
 
4314
To use this License in a document you have written, include a copy of
4315
the License in the document and put the following copyright and license
4316
notices just after the title page:
4317
 
4318
       Copyright (C)  YEAR  YOUR NAME.
4319
       Permission is granted to copy, distribute and/or modify this document
4320
       under the terms of the GNU Free Documentation License, Version 1.2
4321
       or any later version published by the Free Software Foundation;
4322
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
4323
       Texts.  A copy of the license is included in the section entitled ``GNU
4324
       Free Documentation License''.
4325
 
4326
   If you have Invariant Sections, Front-Cover Texts and Back-Cover
4327
Texts, replace the "with...Texts." line with this:
4328
 
4329
         with the Invariant Sections being LIST THEIR TITLES, with
4330
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
4331
         being LIST.
4332
 
4333
   If you have Invariant Sections without Cover Texts, or some other
4334
combination of the three, merge those two alternatives to suit the
4335
situation.
4336
 
4337
   If your document contains nontrivial examples of program code, we
4338
recommend releasing these examples in parallel under your choice of
4339
free software license, such as the GNU General Public License, to
4340
permit their use in free software.
4341
 
4342

4343
File: stabs.info,  Node: Symbol Types Index,  Next: GNU Free Documentation License,  Prev: Stab Sections,  Up: Top
4344
 
4345
Symbol Types Index
4346
******************
4347
 
4348
 
4349
* Menu:
4350
4351
* .bb:                                   Block Structure.      (line 26)
4352
* .be:                                   Block Structure.      (line 26)
4353
* C_BCOMM:                               Common Blocks.        (line 10)
4354
* C_BINCL:                               Include Files.        (line 41)
4355
* C_BLOCK:                               Block Structure.      (line 26)
4356
* C_BSTAT:                               Statics.              (line 31)
4357
* C_DECL, for types:                     Typedefs.             (line  6)
4358
* C_ECOML:                               Common Blocks.        (line 17)
4359
* C_ECOMM:                               Common Blocks.        (line 10)
4360
* C_EINCL:                               Include Files.        (line 41)
4361
* C_ENTRY:                               Alternate Entry Points.
4362
                                                               (line  6)
4363
* C_ESTAT:                               Statics.              (line 31)
4364
* C_FILE:                                Source Files.         (line 61)
4365
* C_FUN:                                 Procedures.           (line 18)
4366
* C_GSYM:                                Global Variables.     (line  6)
4367
* C_LSYM:                                Stack Variables.      (line 11)
4368
* C_PSYM:                                Parameters.           (line 12)
4369
* C_RPSYM:                               Register Parameters.  (line 15)
4370
* C_RSYM:                                Register Variables.   (line  6)
4371
* C_STSYM:                               Statics.              (line 31)
4372
* N_BCOMM:                               Common Blocks.        (line 10)
4373
* N_BINCL:                               Include Files.        (line 17)
4374
* N_BROWS:                               N_BROWS.              (line  7)
4375
* N_BSLINE:                              Line Numbers.         (line 12)
4376
* N_CATCH:                               N_CATCH.              (line  7)
4377
* N_DEFD:                                N_DEFD.               (line  7)
4378
* N_DSLINE:                              Line Numbers.         (line 12)
4379
* N_ECOML:                               Common Blocks.        (line 17)
4380
* N_ECOMM:                               Common Blocks.        (line 10)
4381
* N_EHDECL:                              N_EHDECL.             (line  7)
4382
* N_EINCL:                               Include Files.        (line 17)
4383
* N_ENTRY:                               Alternate Entry Points.
4384
                                                               (line  6)
4385
* N_EXCL:                                Include Files.        (line 17)
4386
* N_FNAME:                               Procedures.           (line  6)
4387
* N_FUN, for functions:                  Procedures.           (line  6)
4388
* N_FUN, for variables:                  Statics.              (line 12)
4389
* N_GSYM:                                Global Variables.     (line  6)
4390
* N_GSYM, for functions (Sun acc):       Procedures.           (line  6)
4391
* N_LBRAC:                               Block Structure.      (line  6)
4392
* N_LCSYM:                               Statics.              (line 12)
4393
* N_LENG:                                N_LENG.               (line  7)
4394
* N_LSYM, for parameter:                 Local Variable Parameters.
4395
                                                               (line 35)
4396
* N_LSYM, for stack variables:           Stack Variables.      (line 11)
4397
* N_LSYM, for types:                     Typedefs.             (line  6)
4398
* N_M2C:                                 N_M2C.                (line  7)
4399
* N_MAC_DEFINE:                          Macro define and undefine.
4400
                                                               (line 11)
4401
* N_MAC_UNDEF:                           Macro define and undefine.
4402
                                                               (line 14)
4403
* N_MAIN:                                Main Program.         (line  6)
4404
* N_MOD2:                                N_MOD2.               (line  7)
4405
* N_NBBSS:                               Gould.                (line  9)
4406
* N_NBDATA:                              Gould.                (line  8)
4407
* N_NBLCS:                               Gould.                (line 11)
4408
* N_NBSTS:                               Gould.                (line 10)
4409
* N_NBTEXT:                              Gould.                (line  7)
4410
* N_NOMAP:                               N_NOMAP.              (line  7)
4411
* N_NSYMS:                               N_NSYMS.              (line  7)
4412
* N_PC:                                  N_PC.                 (line  7)
4413
* N_PSYM:                                Parameters.           (line 12)
4414
* N_RBRAC:                               Block Structure.      (line  6)
4415
* N_ROSYM:                               Statics.              (line 12)
4416
* N_RSYM:                                Register Variables.   (line  6)
4417
* N_RSYM, for parameters:                Register Parameters.  (line 15)
4418
* N_SCOPE:                               N_SCOPE.              (line  7)
4419
* N_SLINE:                               Line Numbers.         (line  6)
4420
* N_SO:                                  Source Files.         (line  6)
4421
* N_SOL:                                 Include Files.        (line 11)
4422
 
4423
 
4424
* N_STSYM, for functions (Sun acc):      Procedures.           (line  6)
4425
4426
4427

4428
Tag Table:
4429
Node: Top877
4430
Node: Overview1924
4431
Node: Flow3339
4432
Node: Stabs Format4865
4433
Node: String Field6427
4434
Node: C Example11858
4435
Node: Assembly Code12403
4436
Node: Program Structure14374
4437
Node: Main Program15100
4438
Node: Source Files15661
4439
Node: Include Files18113
4440
Node: Line Numbers20778
4441
Node: Procedures22312
4442
Node: Nested Procedures28202
4443
Node: Block Structure29378
4444
Node: Alternate Entry Points30784
4445
Node: Constants31517
4446
Node: Variables34629
4447
Node: Stack Variables35317
4448
Node: Global Variables37018
4449
Node: Register Variables38174
4450
Node: Common Blocks38996
4451
Node: Statics40250
4452
Node: Based Variables42829
4453
Node: Parameters44214
4454
Node: Register Parameters45826
4455
Node: Local Variable Parameters48087
4456
Node: Reference Parameters51002
4457
Node: Conformant Arrays51622
4458
Node: Types52339
4459
Node: Builtin Types53286
4460
Node: Traditional Builtin Types54432
4461
Node: Traditional Integer Types54833
4462
Node: Traditional Other Types57141
4463
Node: Builtin Type Descriptors58055
4464
Node: Negative Type Numbers61555
4465
Node: Miscellaneous Types67910
4466
Node: Cross-References69796
4467
Node: Subranges71471
4468
Node: Arrays72710
4469
Node: Strings75935
4470
Node: Enumerations76997
4471
Node: Structures79382
4472
Node: Typedefs82089
4473
Node: Unions83413
4474
Node: Function Types84994
4475
Node: Macro define and undefine86576
4476
Node: Symbol Tables88153
4477
Node: Symbol Table Format88605
4478
Node: Transformations On Symbol Tables90053
4479
Node: Transformations On Static Variables91407
4480
Node: Transformations On Global Variables92143
4481
Node: Stab Section Transformations93386
4482
Node: Cplusplus94769
4483
Node: Class Names95352
4484
Node: Nested Symbols96097
4485
Node: Basic Cplusplus Types96943
4486
Node: Simple Classes98503
4487
Node: Class Instance102797
4488
Node: Methods103514
4489
Node: Method Type Descriptor105733
4490
Node: Member Type Descriptor106933
4491
Node: Protections107725
4492
Node: Method Modifiers110815
4493
Node: Virtual Methods112443
4494
Node: Inheritance116244
4495
Node: Virtual Base Classes119940
4496
Node: Static Members122184
4497
Node: Stab Types122654
4498
Node: Non-Stab Symbol Types123278
4499
Node: Stab Symbol Types124709
4500
Node: Symbol Descriptors128640
4501
Node: Type Descriptors131419
4502
Node: Expanded Reference134631
4503
Node: N_PC136049
4504
Node: N_NSYMS136417
4505
Node: N_NOMAP136658
4506
Node: N_M2C136964
4507
Node: N_BROWS137398
4508
Node: N_DEFD137681
4509
Node: N_EHDECL138138
4510
Node: N_MOD2138389
4511
Node: N_CATCH138627
4512
Node: N_SSYM139121
4513
Node: N_SCOPE139406
4514
Node: Gould139596
4515
Node: N_LENG140588
4516
Node: Questions140816
4517
Node: Stab Sections142460
4518
Node: Stab Section Basics143058
4519
Node: ELF Linker Relocation146399
4520
Node: GNU Free Documentation License149809

powered by: WebSVN 2.1.0

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