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

Subversion Repositories or1k

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

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 363 markom
This is stabs.info, produced by makeinfo version 4.0 from
2 106 markom
./stabs.texinfo.
3
 
4
START-INFO-DIR-ENTRY
5
* Stabs: (stabs).                 The "stabs" debugging information format.
6
END-INFO-DIR-ENTRY
7
 
8
   This document describes the stabs debugging symbol tables.
9
 
10
   Copyright 1992, 93, 94, 95, 97, 1998 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 make and distribute verbatim copies of this
15
manual provided the copyright notice and this permission notice are
16
preserved on all copies.
17
 
18
   Permission is granted to copy or distribute modified versions of this
19
manual under the terms of the GPL (for which purpose this text may be
20
regarded as a program in the language TeX).
21
 
22

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

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

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

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

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

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

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

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

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

372
File: stabs.info,  Node: Source Files,  Next: Include Files,  Prev: Main Program,  Up: Program Structure
373
 
374
Paths and Names of the Source Files
375
===================================
376
 
377
   Before any other stabs occur, there must be a stab specifying the
378
source file.  This information is contained in a symbol of stab type
379
`N_SO'; the string field contains the name of the file.  The value of
380
the symbol is the start address of the portion of the text section
381
corresponding to that file.
382
 
383
   With the Sun Solaris2 compiler, the desc field contains a
384
source-language code.
385
 
386
   Some compilers (for example, GCC2 and SunOS4 `/bin/cc') also include
387
the directory in which the source was compiled, in a second `N_SO'
388
symbol preceding the one containing the file name.  This symbol can be
389
distinguished by the fact that it ends in a slash.  Code from the
390
`cfront' C++ compiler can have additional `N_SO' symbols for
391
nonexistent source files after the `N_SO' for the real source file;
392
these are believed to contain no useful information.
393
 
394
   For example:
395
 
396
     .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0     # 100 is N_SO
397
     .stabs "hello.c",100,0,0,Ltext0
398
             .text
399
     Ltext0:
400
 
401
   Instead of `N_SO' symbols, XCOFF uses a `.file' assembler directive
402
which assembles to a `C_FILE' symbol; explaining this in detail is
403
outside the scope of this document.
404
 
405
   If it is useful to indicate the end of a source file, this is done
406
with an `N_SO' symbol with an empty string for the name.  The value is
407
the address of the end of the text section for the file.  For some
408
systems, there is no indication of the end of a source file, and you
409
just need to figure it ended when you see an `N_SO' for a different
410
source file, or a symbol ending in `.o' (which at least some linkers
411
insert to mark the start of a new `.o' file).
412
 
413

414
File: stabs.info,  Node: Include Files,  Next: Line Numbers,  Prev: Source Files,  Up: Program Structure
415
 
416
Names of Include Files
417
======================
418
 
419
   There are several schemes for dealing with include files: the
420
traditional `N_SOL' approach, Sun's `N_BINCL' approach, and the XCOFF
421
`C_BINCL' approach (which despite the similar name has little in common
422
with `N_BINCL').
423
 
424
   An `N_SOL' symbol specifies which include file subsequent symbols
425
refer to.  The string field is the name of the file and the value is the
426
text address corresponding to the end of the previous include file and
427
the start of this one.  To specify the main source file again, use an
428
`N_SOL' symbol with the name of the main source file.
429
 
430
   The `N_BINCL' approach works as follows.  An `N_BINCL' symbol
431
specifies the start of an include file.  In an object file, only the
432
string is significant; the linker puts data into some of the other
433
fields.  The end of the include file is marked by an `N_EINCL' symbol
434
(which has no string field).  In an object file, there is no
435
significant data in the `N_EINCL' symbol.  `N_BINCL' and `N_EINCL' can
436
be nested.
437
 
438
   If the linker detects that two source files have identical stabs
439
between an `N_BINCL' and `N_EINCL' pair (as will generally be the case
440
for a header file), then it only puts out the stabs once.  Each
441
additional occurance is replaced by an `N_EXCL' symbol.  I believe the
442
GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
443
ones which supports this feature.
444
 
445
   A linker which supports this feature will set the value of a
446
`N_BINCL' symbol to the total of all the characters in the stabs
447
strings included in the header file, omitting any file numbers.  The
448
value of an `N_EXCL' symbol is the same as the value of the `N_BINCL'
449
symbol it replaces.  This information can be used to match up `N_EXCL'
450
and `N_BINCL' symbols which have the same filename.  The `N_EINCL'
451
value, and the values of the other and description fields for all
452
three, appear to always be zero.
453
 
454
   For the start of an include file in XCOFF, use the `.bi' assembler
455
directive, which generates a `C_BINCL' symbol.  A `.ei' directive,
456
which generates a `C_EINCL' symbol, denotes the end of the include
457
file.  Both directives are followed by the name of the source file in
458
quotes, which becomes the string for the symbol.  The value of each
459
symbol, produced automatically by the assembler and linker, is the
460
offset into the executable of the beginning (inclusive, as you'd
461
expect) or end (inclusive, as you would not expect) of the portion of
462
the COFF line table that corresponds to this include file.  `C_BINCL'
463
and `C_EINCL' do not nest.
464
 
465

466
File: stabs.info,  Node: Line Numbers,  Next: Procedures,  Prev: Include Files,  Up: Program Structure
467
 
468
Line Numbers
469
============
470
 
471
   An `N_SLINE' symbol represents the start of a source line.  The desc
472
field contains the line number and the value contains the code address
473
for the start of that source line.  On most machines the address is
474 363 markom
absolute; for stabs in sections (*note Stab Sections::), it is relative
475
to the function in which the `N_SLINE' symbol occurs.
476 106 markom
 
477
   GNU documents `N_DSLINE' and `N_BSLINE' symbols for line numbers in
478
the data or bss segments, respectively.  They are identical to
479
`N_SLINE' but are relocated differently by the linker.  They were
480
intended to be used to describe the source location of a variable
481
declaration, but I believe that GCC2 actually puts the line number in
482
the desc field of the stab for the variable itself.  GDB has been
483
ignoring these symbols (unless they contain a string field) since at
484
least GDB 3.5.
485
 
486
   For single source lines that generate discontiguous code, such as
487
flow of control statements, there may be more than one line number
488
entry for the same source line.  In this case there is a line number
489
entry at the start of each code range, each with the same line number.
490
 
491
   XCOFF does not use stabs for line numbers.  Instead, it uses COFF
492
line numbers (which are outside the scope of this document).  Standard
493
COFF line numbers cannot deal with include files, but in XCOFF this is
494
fixed with the `C_BINCL' method of marking include files (*note Include
495 363 markom
Files::).
496 106 markom
 
497

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

605
File: stabs.info,  Node: Nested Procedures,  Next: Block Structure,  Prev: Procedures,  Up: Program Structure
606
 
607
Nested Procedures
608
=================
609
 
610
   For any of the symbol descriptors representing procedures, after the
611
symbol descriptor and the type information is optionally a scope
612
specifier.  This consists of a comma, the name of the procedure, another
613
comma, and the name of the enclosing procedure.  The first name is local
614
to the scope specified, and seems to be redundant with the name of the
615
symbol (before the `:').  This feature is used by GCC, and presumably
616
Pascal, Modula-2, etc., compilers, for nested functions.
617
 
618
   If procedures are nested more than one level deep, only the
619
immediately containing scope is specified.  For example, this code:
620
 
621
     int
622
     foo (int x)
623
     {
624
       int bar (int y)
625
         {
626
           int baz (int z)
627
             {
628
               return x + y + z;
629
             }
630
           return baz (x + 2 * y);
631
         }
632
       return x + bar (3 * x);
633
     }
634
 
635
produces the stabs:
636
 
637
     .stabs "baz:f1,baz,bar",36,0,0,_baz.15         # 36 is N_FUN
638
     .stabs "bar:f1,bar,foo",36,0,0,_bar.12
639
     .stabs "foo:F1",36,0,0,_foo
640
 
641

642
File: stabs.info,  Node: Block Structure,  Next: Alternate Entry Points,  Prev: Nested Procedures,  Up: Program Structure
643
 
644
Block Structure
645
===============
646
 
647
   The program's block structure is represented by the `N_LBRAC' (left
648
brace) and the `N_RBRAC' (right brace) stab types.  The variables
649
defined inside a block precede the `N_LBRAC' symbol for most compilers,
650
including GCC.  Other compilers, such as the Convex, Acorn RISC
651
machine, and Sun `acc' compilers, put the variables after the `N_LBRAC'
652
symbol.  The values of the `N_LBRAC' and `N_RBRAC' symbols are the
653
start and end addresses of the code of the block, respectively.  For
654
most machines, they are relative to the starting address of this source
655
file.  For the Gould NP1, they are absolute.  For stabs in sections
656 363 markom
(*note Stab Sections::), they are relative to the function in which
657 106 markom
they occur.
658
 
659
   The `N_LBRAC' and `N_RBRAC' stabs that describe the block scope of a
660
procedure are located after the `N_FUN' stab that represents the
661
procedure itself.
662
 
663
   Sun documents the desc field of `N_LBRAC' and `N_RBRAC' symbols as
664
containing the nesting level of the block.  However, dbx seems to not
665
care, and GCC always sets desc to zero.
666
 
667
   For XCOFF, block scope is indicated with `C_BLOCK' symbols.  If the
668
name of the symbol is `.bb', then it is the beginning of the block; if
669
the name of the symbol is `.be'; it is the end of the block.
670
 
671

672
File: stabs.info,  Node: Alternate Entry Points,  Prev: Block Structure,  Up: Program Structure
673
 
674
Alternate Entry Points
675
======================
676
 
677
   Some languages, like Fortran, have the ability to enter procedures at
678
some place other than the beginning.  One can declare an alternate entry
679
point.  The `N_ENTRY' stab is for this; however, the Sun FORTRAN
680
compiler doesn't use it.  According to AIX documentation, only the name
681
of a `C_ENTRY' stab is significant; the address of the alternate entry
682
point comes from the corresponding external symbol.  A previous
683
revision of this document said that the value of an `N_ENTRY' stab was
684
the address of the alternate entry point, but I don't know the source
685
for that information.
686
 
687

688
File: stabs.info,  Node: Constants,  Next: Variables,  Prev: Program Structure,  Up: Top
689
 
690
Constants
691
*********
692
 
693
   The `c' symbol descriptor indicates that this stab represents a
694
constant.  This symbol descriptor is an exception to the general rule
695
that symbol descriptors are followed by type information.  Instead, it
696
is followed by `=' and one of the following:
697
 
698
`b VALUE'
699
     Boolean constant.  VALUE is a numeric value; I assume it is 0 for
700
     false or 1 for true.
701
 
702
`c VALUE'
703
     Character constant.  VALUE is the numeric value of the constant.
704
 
705
`e TYPE-INFORMATION , VALUE'
706
     Constant whose value can be represented as integral.
707
     TYPE-INFORMATION is the type of the constant, as it would appear
708 363 markom
     after a symbol descriptor (*note String Field::).  VALUE is the
709 106 markom
     numeric value of the constant.  GDB 4.9 does not actually get the
710
     right value if VALUE does not fit in a host `int', but it does not
711
     do anything violent, and future debuggers could be extended to
712
     accept integers of any size (whether unsigned or not).  This
713
     constant type is usually documented as being only for enumeration
714
     constants, but GDB has never imposed that restriction; I don't
715
     know about other debuggers.
716
 
717
`i VALUE'
718
     Integer constant.  VALUE is the numeric value.  The type is some
719
     sort of generic integer type (for GDB, a host `int'); to specify
720
     the type explicitly, use `e' instead.
721
 
722
`r VALUE'
723
     Real constant.  VALUE is the real value, which can be `INF'
724
     (optionally preceded by a sign) for infinity, `QNAN' for a quiet
725
     NaN (not-a-number), or `SNAN' for a signalling NaN.  If it is a
726
     normal number the format is that accepted by the C library function
727
     `atof'.
728
 
729
`s STRING'
730
     String constant.  STRING is a string enclosed in either `'' (in
731
     which case `'' characters within the string are represented as
732
     `\'' or `"' (in which case `"' characters within the string are
733
     represented as `\"').
734
 
735
`S TYPE-INFORMATION , ELEMENTS , BITS , PATTERN'
736
     Set constant.  TYPE-INFORMATION is the type of the constant, as it
737 363 markom
     would appear after a symbol descriptor (*note String Field::).
738 106 markom
     ELEMENTS is the number of elements in the set (does this means how
739
     many bits of PATTERN are actually used, which would be redundant
740
     with the type, or perhaps the number of bits set in PATTERN?  I
741
     don't get it), BITS is the number of bits in the constant (meaning
742
     it specifies the length of PATTERN, I think), and PATTERN is a
743
     hexadecimal representation of the set.  AIX documentation refers
744
     to a limit of 32 bytes, but I see no reason why this limit should
745
     exist.  This form could probably be used for arbitrary constants,
746
     not just sets; the only catch is that PATTERN should be understood
747
     to be target, not host, byte order and format.
748
 
749
   The boolean, character, string, and set constants are not supported
750
by GDB 4.9, but it ignores them.  GDB 4.8 and earlier gave an error
751
message and refused to read symbols from the file containing the
752
constants.
753
 
754
   The above information is followed by `;'.
755
 
756

757
File: stabs.info,  Node: Variables,  Next: Types,  Prev: Constants,  Up: Top
758
 
759
Variables
760
*********
761
 
762
   Different types of stabs describe the various ways that variables
763
can be allocated: on the stack, globally, in registers, in common
764
blocks, statically, or as arguments to a function.
765
 
766
* Menu:
767
 
768
* Stack Variables::             Variables allocated on the stack.
769
* Global Variables::            Variables used by more than one source file.
770
* Register Variables::          Variables in registers.
771
* Common Blocks::               Variables statically allocated together.
772
* Statics::                     Variables local to one source file.
773
* Based Variables::             Fortran pointer based variables.
774
* Parameters::                  Variables for arguments to functions.
775
 
776

777
File: stabs.info,  Node: Stack Variables,  Next: Global Variables,  Up: Variables
778
 
779
Automatic Variables Allocated on the Stack
780
==========================================
781
 
782
   If a variable's scope is local to a function and its lifetime is
783
only as long as that function executes (C calls such variables
784
"automatic"), it can be allocated in a register (*note Register
785 363 markom
Variables::) or on the stack.
786 106 markom
 
787
   Each variable allocated on the stack has a stab with the symbol
788
descriptor omitted.  Since type information should begin with a digit,
789
`-', or `(', only those characters precluded from being used for symbol
790
descriptors.  However, the Acorn RISC machine (ARM) is said to get this
791
wrong: it puts out a mere type definition here, without the preceding
792
`TYPE-NUMBER='.  This is a bad idea; there is no guarantee that type
793
descriptors are distinct from symbol descriptors.  Stabs for stack
794
variables use the `N_LSYM' stab type, or `C_LSYM' for XCOFF.
795
 
796
   The value of the stab is the offset of the variable within the local
797
variables.  On most machines this is an offset from the frame pointer
798
and is negative.  The location of the stab specifies which block it is
799
defined in; see *Note Block Structure::.
800
 
801
   For example, the following C code:
802
 
803
     int
804
     main ()
805
     {
806
       int x;
807
     }
808
 
809
   produces the following stabs:
810
 
811
     .stabs "main:F1",36,0,0,_main   # 36 is N_FUN
812
     .stabs "x:1",128,0,0,-12        # 128 is N_LSYM
813
     .stabn 192,0,0,LBB2             # 192 is N_LBRAC
814
     .stabn 224,0,0,LBE2             # 224 is N_RBRAC
815
 
816
   See *Note Procedures:: for more information on the `N_FUN' stab, and
817
*Note Block Structure:: for more information on the `N_LBRAC' and
818
`N_RBRAC' stabs.
819
 
820

821
File: stabs.info,  Node: Global Variables,  Next: Register Variables,  Prev: Stack Variables,  Up: Variables
822
 
823
Global Variables
824
================
825
 
826
   A variable whose scope is not specific to just one source file is
827
represented by the `G' symbol descriptor.  These stabs use the `N_GSYM'
828
stab type (C_GSYM for XCOFF).  The type information for the stab (*note
829 363 markom
String Field::) gives the type of the variable.
830 106 markom
 
831
   For example, the following source code:
832
 
833
     char g_foo = 'c';
834
 
835
yields the following assembly code:
836
 
837
     .stabs "g_foo:G2",32,0,0,0     # 32 is N_GSYM
838
          .global _g_foo
839
          .data
840
     _g_foo:
841
          .byte 99
842
 
843
   The address of the variable represented by the `N_GSYM' is not
844
contained in the `N_GSYM' stab.  The debugger gets this information
845
from the external symbol for the global variable.  In the example above,
846
the `.global _g_foo' and `_g_foo:' lines tell the assembler to produce
847
an external symbol.
848
 
849
   Some compilers, like GCC, output `N_GSYM' stabs only once, where the
850
variable is defined.  Other compilers, like SunOS4 /bin/cc, output a
851
`N_GSYM' stab for each compilation unit which references the variable.
852
 
853

854
File: stabs.info,  Node: Register Variables,  Next: Common Blocks,  Prev: Global Variables,  Up: Variables
855
 
856
Register Variables
857
==================
858
 
859
   Register variables have their own stab type, `N_RSYM' (`C_RSYM' for
860
XCOFF), and their own symbol descriptor, `r'.  The stab's value is the
861
number of the register where the variable data will be stored.
862
 
863
   AIX defines a separate symbol descriptor `d' for floating point
864
registers.  This seems unnecessary; why not just just give floating
865
point registers different register numbers?  I have not verified whether
866
the compiler actually uses `d'.
867
 
868
   If the register is explicitly allocated to a global variable, but not
869
initialized, as in:
870
 
871
     register int g_bar asm ("%g5");
872
 
873
then the stab may be emitted at the end of the object file, with the
874
other bss symbols.
875
 
876

877
File: stabs.info,  Node: Common Blocks,  Next: Statics,  Prev: Register Variables,  Up: Variables
878
 
879
Common Blocks
880
=============
881
 
882
   A common block is a statically allocated section of memory which can
883
be referred to by several source files.  It may contain several
884
variables.  I believe Fortran is the only language with this feature.
885
 
886
   A `N_BCOMM' stab begins a common block and an `N_ECOMM' stab ends
887
it.  The only field that is significant in these two stabs is the
888
string, which names a normal (non-debugging) symbol that gives the
889
address of the common block.  According to IBM documentation, only the
890
`N_BCOMM' has the name of the common block (even though their compiler
891
actually puts it both places).
892
 
893
   The stabs for the members of the common block are between the
894
`N_BCOMM' and the `N_ECOMM'; the value of each stab is the offset
895
within the common block of that variable.  IBM uses the `C_ECOML' stab
896
type, and there is a corresponding `N_ECOML' stab type, but Sun's
897
Fortran compiler uses `N_GSYM' instead.  The variables within a common
898
block use the `V' symbol descriptor (I believe this is true of all
899
Fortran variables).  Other stabs (at least type declarations using
900
`C_DECL') can also be between the `N_BCOMM' and the `N_ECOMM'.
901
 
902

903
File: stabs.info,  Node: Statics,  Next: Based Variables,  Prev: Common Blocks,  Up: Variables
904
 
905
Static Variables
906
================
907
 
908
   Initialized static variables are represented by the `S' and `V'
909
symbol descriptors.  `S' means file scope static, and `V' means
910
procedure scope static.  One exception: in XCOFF, IBM's xlc compiler
911
always uses `V', and whether it is file scope or not is distinguished
912
by whether the stab is located within a function.
913
 
914
   In a.out files, `N_STSYM' means the data section, `N_FUN' means the
915
text section, and `N_LCSYM' means the bss section.  For those systems
916
with a read-only data section separate from the text section (Solaris),
917
`N_ROSYM' means the read-only data section.
918
 
919
   For example, the source lines:
920
 
921
     static const int var_const = 5;
922
     static int var_init = 2;
923
     static int var_noinit;
924
 
925
yield the following stabs:
926
 
927
     .stabs "var_const:S1",36,0,0,_var_const      # 36 is N_FUN
928
     ...
929
     .stabs "var_init:S1",38,0,0,_var_init        # 38 is N_STSYM
930
     ...
931
     .stabs "var_noinit:S1",40,0,0,_var_noinit    # 40 is N_LCSYM
932
 
933
   In XCOFF files, the stab type need not indicate the section;
934
`C_STSYM' can be used for all statics.  Also, each static variable is
935
enclosed in a static block.  A `C_BSTAT' (emitted with a `.bs'
936
assembler directive) symbol begins the static block; its value is the
937
symbol number of the csect symbol whose value is the address of the
938
static block, its section is the section of the variables in that
939
static block, and its name is `.bs'.  A `C_ESTAT' (emitted with a `.es'
940
assembler directive) symbol ends the static block; its name is `.es'
941
and its value and section are ignored.
942
 
943
   In ECOFF files, the storage class is used to specify the section, so
944
the stab type need not indicate the section.
945
 
946
   In ELF files, for the SunPRO compiler version 2.0.1, symbol
947
descriptor `S' means that the address is absolute (the linker relocates
948
it) and symbol descriptor `V' means that the address is relative to the
949
start of the relevant section for that compilation unit.  SunPRO has
950
plans to have the linker stop relocating stabs; I suspect that their the
951
debugger gets the address from the corresponding ELF (not stab) symbol.
952
I'm not sure how to find which symbol of that name is the right one.
953
The clean way to do all this would be to have a the value of a symbol
954
descriptor `S' symbol be an offset relative to the start of the file,
955
just like everything else, but that introduces obvious compatibility
956
problems.  For more information on linker stab relocation, *Note ELF
957
Linker Relocation::.
958
 
959

960
File: stabs.info,  Node: Based Variables,  Next: Parameters,  Prev: Statics,  Up: Variables
961
 
962
Fortran Based Variables
963
=======================
964
 
965
   Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a
966
feature which allows allocating arrays with `malloc', but which avoids
967
blurring the line between arrays and pointers the way that C does.  In
968
stabs such a variable uses the `b' symbol descriptor.
969
 
970
   For example, the Fortran declarations
971
 
972
     real foo, foo10(10), foo10_5(10,5)
973
     pointer (foop, foo)
974
     pointer (foo10p, foo10)
975
     pointer (foo105p, foo10_5)
976
 
977
   produce the stabs
978
 
979
     foo:b6
980
     foo10:bar3;1;10;6
981
     foo10_5:bar3;1;5;ar3;1;10;6
982
 
983
   In this example, `real' is type 6 and type 3 is an integral type
984
which is the type of the subscripts of the array (probably `integer').
985
 
986
   The `b' symbol descriptor is like `V' in that it denotes a
987
statically allocated symbol whose scope is local to a function; see
988
*Note Statics::.  The value of the symbol, instead of being the address
989
of the variable itself, is the address of a pointer to that variable.
990
So in the above example, the value of the `foo' stab is the address of
991
a pointer to a real, the value of the `foo10' stab is the address of a
992
pointer to a 10-element array of reals, and the value of the `foo10_5'
993
stab is the address of a pointer to a 5-element array of 10-element
994
arrays of reals.
995
 
996

997
File: stabs.info,  Node: Parameters,  Prev: Based Variables,  Up: Variables
998
 
999
Parameters
1000
==========
1001
 
1002
   Formal parameters to a function are represented by a stab (or
1003
sometimes two; see below) for each parameter.  The stabs are in the
1004
order in which the debugger should print the parameters (i.e., the
1005
order in which the parameters are declared in the source file).  The
1006
exact form of the stab depends on how the parameter is being passed.
1007
 
1008
   Parameters passed on the stack use the symbol descriptor `p' and the
1009
`N_PSYM' symbol type (or `C_PSYM' for XCOFF).  The value of the symbol
1010
is an offset used to locate the parameter on the stack; its exact
1011
meaning is machine-dependent, but on most machines it is an offset from
1012
the frame pointer.
1013
 
1014
   As a simple example, the code:
1015
 
1016
     main (argc, argv)
1017
          int argc;
1018
          char **argv;
1019
 
1020
   produces the stabs:
1021
 
1022
     .stabs "main:F1",36,0,0,_main                 # 36 is N_FUN
1023
     .stabs "argc:p1",160,0,0,68                   # 160 is N_PSYM
1024
     .stabs "argv:p20=*21=*2",160,0,0,72
1025
 
1026
   The type definition of `argv' is interesting because it contains
1027
several type definitions.  Type 21 is pointer to type 2 (char) and
1028
`argv' (type 20) is pointer to type 21.
1029
 
1030
   The following symbol descriptors are also said to go with `N_PSYM'.
1031
The value of the symbol is said to be an offset from the argument
1032
pointer (I'm not sure whether this is true or not).
1033
 
1034
     pP (<>)
1035
     pF Fortran function parameter
1036
     X  (function result variable)
1037
 
1038
* Menu:
1039
 
1040
* Register Parameters::
1041
* Local Variable Parameters::
1042
* Reference Parameters::
1043
* Conformant Arrays::
1044
 
1045

1046
File: stabs.info,  Node: Register Parameters,  Next: Local Variable Parameters,  Up: Parameters
1047
 
1048
Passing Parameters in Registers
1049
-------------------------------
1050
 
1051
   If the parameter is passed in a register, then traditionally there
1052
are two symbols for each argument:
1053
 
1054
     .stabs "arg:p1" . . .       ; N_PSYM
1055
     .stabs "arg:r1" . . .       ; N_RSYM
1056
 
1057
   Debuggers use the second one to find the value, and the first one to
1058
know that it is an argument.
1059
 
1060
   Because that approach is kind of ugly, some compilers use symbol
1061
descriptor `P' or `R' to indicate an argument which is in a register.
1062
Symbol type `C_RPSYM' is used in XCOFF and `N_RSYM' is used otherwise.
1063
The symbol's value is the register number.  `P' and `R' mean the same
1064
thing; the difference is that `P' is a GNU invention and `R' is an IBM
1065
(XCOFF) invention.  As of version 4.9, GDB should handle either one.
1066
 
1067
   There is at least one case where GCC uses a `p' and `r' pair rather
1068
than `P'; this is where the argument is passed in the argument list and
1069
then loaded into a register.
1070
 
1071
   According to the AIX documentation, symbol descriptor `D' is for a
1072
parameter passed in a floating point register.  This seems
1073
unnecessary--why not just use `R' with a register number which
1074
indicates that it's a floating point register?  I haven't verified
1075
whether the system actually does what the documentation indicates.
1076
 
1077
   On the sparc and hppa, for a `P' symbol whose type is a structure or
1078
union, the register contains the address of the structure.  On the
1079
sparc, this is also true of a `p' and `r' pair (using Sun `cc') or a
1080
`p' symbol.  However, if a (small) structure is really in a register,
1081
`r' is used.  And, to top it all off, on the hppa it might be a
1082
structure which was passed on the stack and loaded into a register and
1083
for which there is a `p' and `r' pair!  I believe that symbol
1084
descriptor `i' is supposed to deal with this case (it is said to mean
1085
"value parameter by reference, indirect access"; I don't know the
1086
source for this information), but I don't know details or what
1087
compilers or debuggers use it, if any (not GDB or GCC).  It is not
1088
clear to me whether this case needs to be dealt with differently than
1089 363 markom
parameters passed by reference (*note Reference Parameters::).
1090 106 markom
 
1091

1092
File: stabs.info,  Node: Local Variable Parameters,  Next: Reference Parameters,  Prev: Register Parameters,  Up: Parameters
1093
 
1094
Storing Parameters as Local Variables
1095
-------------------------------------
1096
 
1097
   There is a case similar to an argument in a register, which is an
1098
argument that is actually stored as a local variable.  Sometimes this
1099
happens when the argument was passed in a register and then the compiler
1100
stores it as a local variable.  If possible, the compiler should claim
1101
that it's in a register, but this isn't always done.
1102
 
1103
   If a parameter is passed as one type and converted to a smaller type
1104
by the prologue (for example, the parameter is declared as a `float',
1105
but the calling conventions specify that it is passed as a `double'),
1106
then GCC2 (sometimes) uses a pair of symbols.  The first symbol uses
1107
symbol descriptor `p' and the type which is passed.  The second symbol
1108
has the type and location which the parameter actually has after the
1109
prologue.  For example, suppose the following C code appears with no
1110
prototypes involved:
1111
 
1112
     void
1113
     subr (f)
1114
          float f;
1115
     {
1116
 
1117
   if `f' is passed as a double at stack offset 8, and the prologue
1118
converts it to a float in register number 0, then the stabs look like:
1119
 
1120
     .stabs "f:p13",160,0,3,8   # 160 is `N_PSYM', here 13 is `double'
1121
     .stabs "f:r12",64,0,3,0    # 64 is `N_RSYM', here 12 is `float'
1122
 
1123
   In both stabs 3 is the line number where `f' is declared (*note Line
1124 363 markom
Numbers::).
1125 106 markom
 
1126
   GCC, at least on the 960, has another solution to the same problem.
1127
It uses a single `p' symbol descriptor for an argument which is stored
1128
as a local variable but uses `N_LSYM' instead of `N_PSYM'.  In this
1129
case, the value of the symbol is an offset relative to the local
1130
variables for that function, not relative to the arguments; on some
1131
machines those are the same thing, but not on all.
1132
 
1133
   On the VAX or on other machines in which the calling convention
1134
includes the number of words of arguments actually passed, the debugger
1135
(GDB at least) uses the parameter symbols to keep track of whether it
1136
needs to print nameless arguments in addition to the formal parameters
1137
which it has printed because each one has a stab.  For example, in
1138
 
1139
     extern int fprintf (FILE *stream, char *format, ...);
1140
     ...
1141
     fprintf (stdout, "%d\n", x);
1142
 
1143
   there are stabs for `stream' and `format'.  On most machines, the
1144
debugger can only print those two arguments (because it has no way of
1145
knowing that additional arguments were passed), but on the VAX or other
1146
machines with a calling convention which indicates the number of words
1147
of arguments, the debugger can print all three arguments.  To do so,
1148
the parameter symbol (symbol descriptor `p') (not necessarily `r' or
1149
symbol descriptor omitted symbols) needs to contain the actual type as
1150
passed (for example, `double' not `float' if it is passed as a double
1151
and converted to a float).
1152
 
1153

1154
File: stabs.info,  Node: Reference Parameters,  Next: Conformant Arrays,  Prev: Local Variable Parameters,  Up: Parameters
1155
 
1156
Passing Parameters by Reference
1157
-------------------------------
1158
 
1159
   If the parameter is passed by reference (e.g., Pascal `VAR'
1160
parameters), then the symbol descriptor is `v' if it is in the argument
1161
list, or `a' if it in a register.  Other than the fact that these
1162
contain the address of the parameter rather than the parameter itself,
1163
they are identical to `p' and `R', respectively.  I believe `a' is an
1164
AIX invention; `v' is supported by all stabs-using systems as far as I
1165
know.
1166
 

powered by: WebSVN 2.1.0

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