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