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

Subversion Repositories or1k

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

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
This is stabs.info, produced by makeinfo version 4.0 from
2
./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,1993,1994,1995,1997,1998,2000,2001    Free Software
11
Foundation, Inc.  Contributed by Cygnus Support.  Written by Julia
12
Menapace, Jim Kingdon, 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 the
17
Invariant Sections being "Stabs Types" and "Stabs Sections", with the
18
Front-Cover texts being "A GNU Manual," and with the Back-Cover Texts
19
as in (a) below.
20
 
21
   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
22
modify this GNU Manual, like GNU software.  Copies published by the Free
23
Software Foundation raise funds for GNU development."
24
 
25

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

powered by: WebSVN 2.1.0

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