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