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