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