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

Subversion Repositories openrisc

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

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

Line No. Rev Author Line
1 227 jeremybenn
This is stabs.info, produced by makeinfo version 4.8 from
2
./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
   Copyright (C) 1992, 1993, 1994, 1995, 1997, 1998, 2000, 2001, 2002,
10
2003, 2004, 2005, 2006, 2007, 2009, 2010 Free Software Foundation, Inc.
11
Contributed by Cygnus Support.  Written by Julia Menapace, Jim Kingdon,
12
and David MacKenzie.
13
 
14
   Permission is granted to copy, distribute and/or modify this document
15
under the terms of the GNU Free Documentation License, Version 1.1 or
16
any later version published by the Free Software Foundation; with no
17
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
18
Texts.  A copy of the license is included in the section entitled "GNU
19
Free Documentation License".
20
 
21
   This document describes the stabs debugging symbol tables.
22
 
23
   Copyright (C) 1992, 1993, 1994, 1995, 1997, 1998, 2000, 2001, 2002,
24
2003, 2004, 2005, 2006, 2007, 2009, 2010 Free Software Foundation, Inc.
25
Contributed by Cygnus Support.  Written by Julia Menapace, Jim Kingdon,
26
and David MacKenzie.
27
 
28
   Permission is granted to copy, distribute and/or modify this document
29
under the terms of the GNU Free Documentation License, Version 1.1 or
30
any later version published by the Free Software Foundation; with no
31
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
32
Texts.  A copy of the license is included in the section entitled "GNU
33
Free Documentation License".
34
 
35

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

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

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

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

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

277
File: stabs.info,  Node: C Example,  Next: Assembly Code,  Prev: String Field,  Up: Overview
278
 
279
1.4 A Simple Example in C Source
280
================================
281
 
282
To get the flavor of how stabs describe source information for a C
283
program, let's look at the simple program:
284
 
285
     main()
286
     {
287
             printf("Hello world");
288
     }
289
 
290
   When compiled with `-g', the program above yields the following `.s'
291
file.  Line numbers have been added to make it easier to refer to parts
292
of the `.s' file in the description of the stabs that follows.
293
 
294

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

357
File: stabs.info,  Node: Program Structure,  Next: Constants,  Prev: Overview,  Up: Top
358
 
359
2 Encoding the Structure of the Program
360
***************************************
361
 
362
The elements of the program structure that stabs encode include the name
363
of the main function, the names of the source and include files, the
364
line numbers, procedure names and types, and the beginnings and ends of
365
blocks of code.
366
 
367
* Menu:
368
 
369
* Main Program::                Indicate what the main program is
370
* Source Files::                The path and name of the source file
371
* Include Files::               Names of include files
372
* Line Numbers::
373
* Procedures::
374
* Nested Procedures::
375
* Block Structure::
376
* Alternate Entry Points::      Entering procedures except at the beginning.
377
 
378

379
File: stabs.info,  Node: Main Program,  Next: Source Files,  Up: Program Structure
380
 
381
2.1 Main Program
382
================
383
 
384
Most languages allow the main program to have any name.  The `N_MAIN'
385
stab type tells the debugger the name that is used in this program.
386
Only the string field is significant; it is the name of a function
387
which is the main program.  Most C compilers do not use this stab (they
388
expect the debugger to assume that the name is `main'), but some C
389
compilers emit an `N_MAIN' stab for the `main' function.  I'm not sure
390
how XCOFF handles this.
391
 
392

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

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

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

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

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

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

724
File: stabs.info,  Node: Alternate Entry Points,  Prev: Block Structure,  Up: Program Structure
725
 
726
2.8 Alternate Entry Points
727
==========================
728
 
729
Some languages, like Fortran, have the ability to enter procedures at
730
some place other than the beginning.  One can declare an alternate entry
731
point.  The `N_ENTRY' stab is for this; however, the Sun FORTRAN
732
compiler doesn't use it.  According to AIX documentation, only the name
733
of a `C_ENTRY' stab is significant; the address of the alternate entry
734
point comes from the corresponding external symbol.  A previous
735
revision of this document said that the value of an `N_ENTRY' stab was
736
the address of the alternate entry point, but I don't know the source
737
for that information.
738
 
739

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

809
File: stabs.info,  Node: Variables,  Next: Types,  Prev: Constants,  Up: Top
810
 
811
4 Variables
812
***********
813
 
814
Different types of stabs describe the various ways that variables can be
815
allocated: on the stack, globally, in registers, in common blocks,
816
statically, or as arguments to a function.
817
 
818
* Menu:
819
 
820
* Stack Variables::             Variables allocated on the stack.
821
* Global Variables::            Variables used by more than one source file.
822
* Register Variables::          Variables in registers.
823
* Common Blocks::               Variables statically allocated together.
824
* Statics::                     Variables local to one source file.
825
* Based Variables::             Fortran pointer based variables.
826
* Parameters::                  Variables for arguments to functions.
827
 
828

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

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

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

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

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

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

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

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

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

1206
File: stabs.info,  Node: Reference Parameters,  Next: Conformant Arrays,  Prev: Local Variable Parameters,  Up: Parameters
1207
 
1208
4.7.3 Passing Parameters by Reference
1209
-------------------------------------
1210
 
1211
If the parameter is passed by reference (e.g., Pascal `VAR'
1212
parameters), then the symbol descriptor is `v' if it is in the argument
1213
list, or `a' if it in a register.  Other than the fact that these
1214
contain the address of the parameter rather than the parameter itself,
1215
they are identical to `p' and `R', respectively.  I believe `a' is an
1216
AIX invention; `v' is supported by all stabs-using systems as far as I
1217
know.
1218
 
1219

1220
File: stabs.info,  Node: Conformant Arrays,  Prev: Reference Parameters,  Up: Parameters
1221
 
1222
4.7.4 Passing Conformant Array Parameters
1223
-----------------------------------------
1224
 
1225
Conformant arrays are a feature of Modula-2, and perhaps other
1226
languages, in which the size of an array parameter is not known to the
1227
called function until run-time.  Such parameters have two stabs: a `x'
1228
for the array itself, and a `C', which represents the size of the
1229
array.  The value of the `x' stab is the offset in the argument list
1230
where the address of the array is stored (it this right?  it is a
1231
guess); the value of the `C' stab is the offset in the argument list
1232
where the size of the array (in elements? in bytes?) is stored.
1233
 
1234

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

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

1286
File: stabs.info,  Node: Traditional Builtin Types,  Next: Builtin Type Descriptors,  Up: Builtin Types
1287
 
1288
5.1.1 Traditional Builtin Types
1289
-------------------------------
1290
 
1291
This is the traditional, convoluted method for defining builtin types.
1292
There are several classes of such type definitions: integer, floating
1293
point, and `void'.
1294
 
1295
* Menu:
1296
 
1297
* Traditional Integer Types::
1298
* Traditional Other Types::
1299
 
1300

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

1350
File: stabs.info,  Node: Traditional Other Types,  Prev: Traditional Integer Types,  Up: Traditional Builtin Types
1351
 
1352
5.1.1.2 Traditional Other Types
1353
...............................
1354
 
1355
If the upper bound of a subrange is 0 and the lower bound is positive,
1356
the type is a floating point type, and the lower bound of the subrange
1357
indicates the number of bytes in the type:
1358
 
1359
     .stabs "float:t12=r1;4;0;",128,0,0,0
1360
     .stabs "double:t13=r1;8;0;",128,0,0,0
1361
 
1362
   However, GCC writes `long double' the same way it writes `double',
1363
so there is no way to distinguish.
1364
 
1365
     .stabs "long double:t14=r1;8;0;",128,0,0,0
1366
 
1367
   Complex types are defined the same way as floating-point types;
1368
there is no way to distinguish a single-precision complex from a
1369
double-precision floating-point type.
1370
 
1371
   The C `void' type is defined as itself:
1372
 
1373
     .stabs "void:t15=15",128,0,0,0
1374
 
1375
   I'm not sure how a boolean type is represented.
1376
 
1377

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

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

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

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

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

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

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

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

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

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

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

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

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

2168
File: stabs.info,  Node: Symbol Tables,  Next: Cplusplus,  Prev: Macro define and undefine,  Up: Top
2169
 
2170
7 Symbol Information in Symbol Tables
2171
*************************************
2172
 
2173
This chapter describes the format of symbol table entries and how stab
2174
assembler directives map to them.  It also describes the
2175
transformations that the assembler and linker make on data from stabs.
2176
 
2177
* Menu:
2178
 
2179
* Symbol Table Format::
2180
* Transformations On Symbol Tables::
2181
 
2182

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

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

2247
File: stabs.info,  Node: Transformations On Static Variables,  Next: Transformations On Global Variables,  Up: Transformations On Symbol Tables
2248
 
2249
7.2.1 Transformations on Static Variables
2250
-----------------------------------------
2251
 
2252
This source line defines a static variable at file scope:
2253
 
2254
     static int s_g_repeat
2255
 
2256
The following stab describes the symbol:
2257
 
2258
     .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
2259
 
2260
The assembler transforms the stab into this symbol table entry in the
2261
`.o' file.  The location is expressed as a data segment offset.
2262
 
2263
     00000084 - 00 0000 STSYM s_g_repeat:S1
2264
 
2265
In the symbol table entry from the executable, the linker has made the
2266
relocatable address absolute.
2267
 
2268
     0000e00c - 00 0000 STSYM s_g_repeat:S1
2269
 
2270

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

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

2344
File: stabs.info,  Node: Cplusplus,  Next: Stab Types,  Prev: Symbol Tables,  Up: Top
2345
 
2346
8 GNU C++ Stabs
2347
***************
2348
 
2349
* Menu:
2350
 
2351
* Class Names::                 C++ class names are both tags and typedefs.
2352
* Nested Symbols::              C++ symbol names can be within other types.
2353
* Basic Cplusplus Types::
2354
* Simple Classes::
2355
* Class Instance::
2356
* Methods::                     Method definition
2357
* Method Type Descriptor::      The `#' type descriptor
2358
* Member Type Descriptor::      The `@' type descriptor
2359
* Protections::
2360
* Method Modifiers::
2361
* Virtual Methods::
2362
* Inheritance::
2363
* Virtual Base Classes::
2364
* Static Members::
2365
 
2366

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

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

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

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

2543
File: stabs.info,  Node: Class Instance,  Next: Methods,  Prev: Simple Classes,  Up: Cplusplus
2544
 
2545
8.5 Class Instance
2546
==================
2547
 
2548
As shown above, describing even a simple C++ class definition is
2549
accomplished by massively extending the stab format used in C to
2550
describe structure types.  However, once the class is defined, C stabs
2551
with no modifications can be used to describe class instances.  The
2552
following source:
2553
 
2554
     main () {
2555
             baseA AbaseA;
2556
     }
2557
 
2558
yields the following stab describing the class instance.  It looks no
2559
different from a standard C stab describing a local variable.
2560
 
2561
     .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset
2562
 
2563
     .stabs "AbaseA:20",128,0,0,-20
2564
 
2565

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

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

2648
File: stabs.info,  Node: Member Type Descriptor,  Next: Protections,  Prev: Method Type Descriptor,  Up: Cplusplus
2649
 
2650
8.8 The `@' Type Descriptor
2651
===========================
2652
 
2653
The `@' type descriptor is used for a pointer-to-non-static-member-data
2654
type.  It is followed by type information for the class (or union), a
2655
comma, and type information for the member data.
2656
 
2657
   The following C++ source:
2658
 
2659
     typedef int A::*int_in_a;
2660
 
2661
   generates the following stab:
2662
 
2663
     .stabs "int_in_a:t20=21=@19,1",128,0,0,0
2664
 
2665
   Note that there is a conflict between this and type attributes
2666
(*note String Field::); both use type descriptor `@'.  Fortunately, the
2667
`@' type descriptor used in this C++ sense always will be followed by a
2668
digit, `(', or `-', and type attributes never start with those things.
2669
 
2670

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

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

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

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

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

3005
File: stabs.info,  Node: Static Members,  Prev: Virtual Base Classes,  Up: Cplusplus
3006
 
3007
8.14 Static Members
3008
===================
3009
 
3010
The data area for a class is a concatenation of the space used by the
3011
data members of the class.  If the class has virtual methods, a vtable
3012
pointer follows the class data.  The field offset part of each field
3013
description in the class stab shows this ordering.
3014
 
3015
   << How is this reflected in stabs?  See Cygnus bug #677 for some
3016
info.  >>
3017
 
3018

3019
File: stabs.info,  Node: Stab Types,  Next: Symbol Descriptors,  Prev: Cplusplus,  Up: Top
3020
 
3021
Appendix A Table of Stab Types
3022
******************************
3023
 
3024
The following are all the possible values for the stab type field, for
3025
a.out files, in numeric order.  This does not apply to XCOFF, but it
3026
does apply to stabs in sections (*note Stab Sections::).  Stabs in
3027
ECOFF use these values but add 0x8f300 to distinguish them from non-stab
3028
symbols.
3029
 
3030
   The symbolic names are defined in the file `include/aout/stabs.def'.
3031
 
3032
* Menu:
3033
 
3034
* Non-Stab Symbol Types::       Types from 0 to 0x1f
3035
* Stab Symbol Types::           Types from 0x20 to 0xff
3036
 
3037

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

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

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

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

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

3563
File: stabs.info,  Node: N_PC,  Next: N_NSYMS,  Up: Expanded Reference
3564
 
3565
D.1 N_PC
3566
========
3567
 
3568
 -- `.stabs': N_PC
3569
     Global symbol (for Pascal).
3570
 
3571
          "name" -> "symbol_name"  <>
3572
          value  -> supposedly the line number (stab.def is skeptical)
3573
 
3574
          `stabdump.c' says:
3575
 
3576
          global pascal symbol: name,,0,subtype,line
3577
          << subtype? >>
3578
 
3579

3580
File: stabs.info,  Node: N_NSYMS,  Next: N_NOMAP,  Prev: N_PC,  Up: Expanded Reference
3581
 
3582
D.2 N_NSYMS
3583
===========
3584
 
3585
 -- `.stabn': N_NSYMS
3586
     Number of symbols (according to Ultrix V4.0).
3587
 
3588
                  0, files,,funcs,lines (stab.def)
3589
 
3590

3591
File: stabs.info,  Node: N_NOMAP,  Next: N_M2C,  Prev: N_NSYMS,  Up: Expanded Reference
3592
 
3593
D.3 N_NOMAP
3594
===========
3595
 
3596
 -- `.stabs': N_NOMAP
3597
     No DST map for symbol (according to Ultrix V4.0).  I think this
3598
     means a variable has been optimized out.
3599
 
3600
                  name, ,0,type,ignored (stab.def)
3601
 
3602

3603
File: stabs.info,  Node: N_M2C,  Next: N_BROWS,  Prev: N_NOMAP,  Up: Expanded Reference
3604
 
3605
D.4 N_M2C
3606
=========
3607
 
3608
 -- `.stabs': N_M2C
3609
     Modula-2 compilation unit.
3610
 
3611
          "string" -> "unit_name,unit_time_stamp[,code_time_stamp]"
3612
          desc   -> unit_number
3613
          value  -> 0 (main unit)
3614
                    1 (any other unit)
3615
 
3616
     See `Dbx and Dbxtool Interfaces', 2nd edition, by Sun, 1988, for
3617
     more information.
3618
 
3619
 
3620

3621
File: stabs.info,  Node: N_BROWS,  Next: N_DEFD,  Prev: N_M2C,  Up: Expanded Reference
3622
 
3623
D.5 N_BROWS
3624
===========
3625
 
3626
 -- `.stabs': N_BROWS
3627
     Sun source code browser, path to `.cb' file
3628
 
3629
     <> "path to associated `.cb' file"
3630
 
3631
     Note: N_BROWS has the same value as N_BSLINE.
3632
 
3633

3634
File: stabs.info,  Node: N_DEFD,  Next: N_EHDECL,  Prev: N_BROWS,  Up: Expanded Reference
3635
 
3636
D.6 N_DEFD
3637
==========
3638
 
3639
 -- `.stabn': N_DEFD
3640
     GNU Modula2 definition module dependency.
3641
 
3642
     GNU Modula-2 definition module dependency.  The value is the
3643
     modification time of the definition file.  The other field is
3644
     non-zero if it is imported with the GNU M2 keyword `%INITIALIZE'.
3645
     Perhaps `N_M2C' can be used if there are enough empty fields?
3646
 
3647

3648
File: stabs.info,  Node: N_EHDECL,  Next: N_MOD2,  Prev: N_DEFD,  Up: Expanded Reference
3649
 
3650
D.7 N_EHDECL
3651
============
3652
 
3653
 -- `.stabs': N_EHDECL
3654
     GNU C++ exception variable <>.
3655
 
3656
     "STRING is variable name"
3657
 
3658
     Note: conflicts with `N_MOD2'.
3659
 
3660

3661
File: stabs.info,  Node: N_MOD2,  Next: N_CATCH,  Prev: N_EHDECL,  Up: Expanded Reference
3662
 
3663
D.8 N_MOD2
3664
==========
3665
 
3666
 -- `.stab?': N_MOD2
3667
     Modula2 info "for imc" (according to Ultrix V4.0)
3668
 
3669
     Note: conflicts with `N_EHDECL'  <>
3670
 
3671

3672
File: stabs.info,  Node: N_CATCH,  Next: N_SSYM,  Prev: N_MOD2,  Up: Expanded Reference
3673
 
3674
D.9 N_CATCH
3675
===========
3676
 
3677
 -- `.stabn': N_CATCH
3678
     GNU C++ `catch' clause
3679
 
3680
     GNU C++ `catch' clause.  The value is its address.  The desc field
3681
     is nonzero if this entry is immediately followed by a `CAUGHT' stab
3682
     saying what exception was caught.  Multiple `CAUGHT' stabs means
3683
     that multiple exceptions can be caught here.  If desc is 0, it
3684
     means all exceptions are caught here.
3685
 
3686

3687
File: stabs.info,  Node: N_SSYM,  Next: N_SCOPE,  Prev: N_CATCH,  Up: Expanded Reference
3688
 
3689
D.10 N_SSYM
3690
===========
3691
 
3692
 -- `.stabn': N_SSYM
3693
     Structure or union element.
3694
 
3695
     The value is the offset in the structure.
3696
 
3697
     <>
3698
 
3699

3700
File: stabs.info,  Node: N_SCOPE,  Next: Gould,  Prev: N_SSYM,  Up: Expanded Reference
3701
 
3702
D.11 N_SCOPE
3703
============
3704
 
3705
 -- `.stab?': N_SCOPE
3706
     Modula2 scope information (Sun linker) <>
3707
 
3708

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

3736
File: stabs.info,  Node: N_LENG,  Prev: Gould,  Up: Expanded Reference
3737
 
3738
D.13 N_LENG
3739
===========
3740
 
3741
 -- `.stabn': N_LENG
3742
     Second symbol entry containing a length-value for the preceding
3743
     entry.  The value is the length.
3744
 
3745

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

3778
File: stabs.info,  Node: Stab Sections,  Next: Symbol Types Index,  Prev: Questions,  Up: Top
3779
 
3780
Appendix F Using Stabs in Their Own Sections
3781
********************************************
3782
 
3783
Many object file formats allow tools to create object files with custom
3784
sections containing any arbitrary data.  For any such object file
3785
format, stabs can be embedded in special sections.  This is how stabs
3786
are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs
3787
are used with COFF.
3788
 
3789
* Menu:
3790
 
3791
* Stab Section Basics::    How to embed stabs in sections
3792
* ELF Linker Relocation::  Sun ELF hacks
3793
 
3794

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

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

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

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

4441
Tag Table:
4442
Node: Top1534
4443
Node: Overview2581
4444
Node: Flow3996
4445
Node: Stabs Format5522
4446
Node: String Field7084
4447
Node: C Example12515
4448
Node: Assembly Code13060
4449
Node: Program Structure15031
4450
Node: Main Program15757
4451
Node: Source Files16318
4452
Node: Include Files18770
4453
Node: Line Numbers21435
4454
Node: Procedures22969
4455
Node: Nested Procedures28859
4456
Node: Block Structure30035
4457
Node: Alternate Entry Points31441
4458
Node: Constants32174
4459
Node: Variables35286
4460
Node: Stack Variables35974
4461
Node: Global Variables37675
4462
Node: Register Variables38831
4463
Node: Common Blocks39653
4464
Node: Statics40907
4465
Node: Based Variables43486
4466
Node: Parameters44871
4467
Node: Register Parameters46483
4468
Node: Local Variable Parameters48744
4469
Node: Reference Parameters51659
4470
Node: Conformant Arrays52279
4471
Node: Types52996
4472
Node: Builtin Types53943
4473
Node: Traditional Builtin Types55089
4474
Node: Traditional Integer Types55490
4475
Node: Traditional Other Types57798
4476
Node: Builtin Type Descriptors58712
4477
Node: Negative Type Numbers62212
4478
Node: Miscellaneous Types68567
4479
Node: Cross-References70453
4480
Node: Subranges72128
4481
Node: Arrays73367
4482
Node: Strings76592
4483
Node: Enumerations77654
4484
Node: Structures80039
4485
Node: Typedefs82746
4486
Node: Unions84070
4487
Node: Function Types85651
4488
Node: Macro define and undefine87233
4489
Node: Symbol Tables88810
4490
Node: Symbol Table Format89262
4491
Node: Transformations On Symbol Tables90710
4492
Node: Transformations On Static Variables92064
4493
Node: Transformations On Global Variables92800
4494
Node: Stab Section Transformations94043
4495
Node: Cplusplus95426
4496
Node: Class Names96009
4497
Node: Nested Symbols96754
4498
Node: Basic Cplusplus Types97600
4499
Node: Simple Classes99160
4500
Node: Class Instance103454
4501
Node: Methods104171
4502
Node: Method Type Descriptor106390
4503
Node: Member Type Descriptor107590
4504
Node: Protections108382
4505
Node: Method Modifiers111472
4506
Node: Virtual Methods113100
4507
Node: Inheritance116901
4508
Node: Virtual Base Classes120597
4509
Node: Static Members122841
4510
Node: Stab Types123311
4511
Node: Non-Stab Symbol Types123935
4512
Node: Stab Symbol Types125366
4513
Node: Symbol Descriptors129297
4514
Node: Type Descriptors132076
4515
Node: Expanded Reference135288
4516
Node: N_PC136706
4517
Node: N_NSYMS137074
4518
Node: N_NOMAP137315
4519
Node: N_M2C137621
4520
Node: N_BROWS138055
4521
Node: N_DEFD138338
4522
Node: N_EHDECL138795
4523
Node: N_MOD2139046
4524
Node: N_CATCH139284
4525
Node: N_SSYM139778
4526
Node: N_SCOPE140063
4527
Node: Gould140253
4528
Node: N_LENG141245
4529
Node: Questions141473
4530
Node: Stab Sections143117
4531
Node: Stab Section Basics143715
4532
Node: ELF Linker Relocation147056
4533
Node: GNU Free Documentation License150466

powered by: WebSVN 2.1.0

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