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