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