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