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