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