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