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