119370Spst\input texinfo 219370Spst@setfilename stabs.info 319370Spst 419370Spst@c @finalout 519370Spst 6130809Smarcel@c This is a dir.info fragment to support semi-automated addition of 7130809Smarcel@c manuals to an info tree. 8130809Smarcel@dircategory Software development 9130809Smarcel@direntry 10130809Smarcel* Stabs: (stabs). The "stabs" debugging information format. 11130809Smarcel@end direntry 1219370Spst 1319370Spst@ifinfo 1419370SpstThis document describes the stabs debugging symbol tables. 1519370Spst 1698948SobrienCopyright 1992,1993,1994,1995,1997,1998,2000,2001 1798948Sobrien Free Software Foundation, Inc. 1819370SpstContributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon, 1919370Spstand David MacKenzie. 2019370Spst 2198948SobrienPermission is granted to copy, distribute and/or modify this document 2298948Sobrienunder the terms of the GNU Free Documentation License, Version 1.1 or 2398948Sobrienany later version published by the Free Software Foundation; with no 24130809SmarcelInvariant Sections, with no Front-Cover Texts, and with no Back-Cover 25130809SmarcelTexts. A copy of the license is included in the section entitled ``GNU 26130809SmarcelFree Documentation License''. 2719370Spst@end ifinfo 2819370Spst 2919370Spst@setchapternewpage odd 3019370Spst@settitle STABS 3119370Spst@titlepage 3219370Spst@title The ``stabs'' debug format 3319370Spst@author Julia Menapace, Jim Kingdon, David MacKenzie 3419370Spst@author Cygnus Support 3519370Spst@page 3619370Spst@tex 3719370Spst\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ 3898948Sobrien\xdef\manvers{\$Revision: 2.130 $} % For use in headers, footers too 3919370Spst{\parskip=0pt 4019370Spst\hfill Cygnus Support\par 4119370Spst\hfill \manvers\par 4219370Spst\hfill \TeX{}info \texinfoversion\par 4319370Spst} 4419370Spst@end tex 4519370Spst 4619370Spst@vskip 0pt plus 1filll 4798948SobrienCopyright @copyright{} 1992,1993,1994,1995,1997,1998,2000,2001 Free Software Foundation, Inc. 4819370SpstContributed by Cygnus Support. 4919370Spst 5098948SobrienPermission is granted to copy, distribute and/or modify this document 5198948Sobrienunder the terms of the GNU Free Documentation License, Version 1.1 or 5298948Sobrienany later version published by the Free Software Foundation; with no 53130809SmarcelInvariant Sections, with no Front-Cover Texts, and with no Back-Cover 54130809SmarcelTexts. A copy of the license is included in the section entitled ``GNU 55130809SmarcelFree Documentation License''. 5619370Spst@end titlepage 5719370Spst 5819370Spst@ifinfo 5919370Spst@node Top 6019370Spst@top The "stabs" representation of debugging information 6119370Spst 6219370SpstThis document describes the stabs debugging format. 6319370Spst 6419370Spst@menu 6519370Spst* Overview:: Overview of stabs 6619370Spst* Program Structure:: Encoding of the structure of the program 6719370Spst* Constants:: Constants 6819370Spst* Variables:: 6919370Spst* Types:: Type definitions 7019370Spst* Symbol Tables:: Symbol information in symbol tables 7119370Spst* Cplusplus:: Stabs specific to C++ 7219370Spst* Stab Types:: Symbol types in a.out files 7319370Spst* Symbol Descriptors:: Table of symbol descriptors 7419370Spst* Type Descriptors:: Table of type descriptors 7519370Spst* Expanded Reference:: Reference information by stab type 7698948Sobrien* Questions:: Questions and anomalies 7719370Spst* Stab Sections:: In some object file formats, stabs are 7819370Spst in sections. 7919370Spst* Symbol Types Index:: Index of symbolic stab symbol type names. 80130809Smarcel* GNU Free Documentation License:: The license for this documentation 8119370Spst@end menu 8219370Spst@end ifinfo 8319370Spst 8498948Sobrien@c TeX can handle the contents at the start but makeinfo 3.12 can not 8598948Sobrien@iftex 8698948Sobrien@contents 8798948Sobrien@end iftex 8819370Spst 8919370Spst@node Overview 9019370Spst@chapter Overview of Stabs 9119370Spst 9219370Spst@dfn{Stabs} refers to a format for information that describes a program 9319370Spstto a debugger. This format was apparently invented by 9419370SpstPeter Kessler at 9519370Spstthe University of California at Berkeley, for the @code{pdx} Pascal 9619370Spstdebugger; the format has spread widely since then. 9719370Spst 9819370SpstThis document is one of the few published sources of documentation on 9919370Spststabs. It is believed to be comprehensive for stabs used by C. The 10019370Spstlists of symbol descriptors (@pxref{Symbol Descriptors}) and type 10119370Spstdescriptors (@pxref{Type Descriptors}) are believed to be completely 10219370Spstcomprehensive. Stabs for COBOL-specific features and for variant 10319370Spstrecords (used by Pascal and Modula-2) are poorly documented here. 10419370Spst 10519370Spst@c FIXME: Need to document all OS9000 stuff in GDB; see all references 10619370Spst@c to os9k_stabs in stabsread.c. 10719370Spst 10819370SpstOther sources of information on stabs are @cite{Dbx and Dbxtool 10919370SpstInterfaces}, 2nd edition, by Sun, 1988, and @cite{AIX Version 3.2 Files 11019370SpstReference}, Fourth Edition, September 1992, "dbx Stabstring Grammar" in 11119370Spstthe a.out section, page 2-31. This document is believed to incorporate 11219370Spstthe information from those two sources except where it explicitly directs 11319370Spstyou to them for more information. 11419370Spst 11519370Spst@menu 11619370Spst* Flow:: Overview of debugging information flow 11719370Spst* Stabs Format:: Overview of stab format 11819370Spst* String Field:: The string field 11919370Spst* C Example:: A simple example in C source 12019370Spst* Assembly Code:: The simple example at the assembly level 12119370Spst@end menu 12219370Spst 12319370Spst@node Flow 12419370Spst@section Overview of Debugging Information Flow 12519370Spst 12619370SpstThe GNU C compiler compiles C source in a @file{.c} file into assembly 12719370Spstlanguage in a @file{.s} file, which the assembler translates into 12819370Spsta @file{.o} file, which the linker combines with other @file{.o} files and 12919370Spstlibraries to produce an executable file. 13019370Spst 13119370SpstWith the @samp{-g} option, GCC puts in the @file{.s} file additional 13219370Spstdebugging information, which is slightly transformed by the assembler 13319370Spstand linker, and carried through into the final executable. This 13419370Spstdebugging information describes features of the source file like line 13519370Spstnumbers, the types and scopes of variables, and function names, 13619370Spstparameters, and scopes. 13719370Spst 13819370SpstFor some object file formats, the debugging information is encapsulated 13919370Spstin assembler directives known collectively as @dfn{stab} (symbol table) 14019370Spstdirectives, which are interspersed with the generated code. Stabs are 14119370Spstthe native format for debugging information in the a.out and XCOFF 14219370Spstobject file formats. The GNU tools can also emit stabs in the COFF and 14319370SpstECOFF object file formats. 14419370Spst 14519370SpstThe assembler adds the information from stabs to the symbol information 14619370Spstit places by default in the symbol table and the string table of the 14719370Spst@file{.o} file it is building. The linker consolidates the @file{.o} 14819370Spstfiles into one executable file, with one symbol table and one string 14919370Spsttable. Debuggers use the symbol and string tables in the executable as 15019370Spsta source of debugging information about the program. 15119370Spst 15219370Spst@node Stabs Format 15319370Spst@section Overview of Stab Format 15419370Spst 15519370SpstThere are three overall formats for stab assembler directives, 15619370Spstdifferentiated by the first word of the stab. The name of the directive 15719370Spstdescribes which combination of four possible data fields follows. It is 15819370Spsteither @code{.stabs} (string), @code{.stabn} (number), or @code{.stabd} 15919370Spst(dot). IBM's XCOFF assembler uses @code{.stabx} (and some other 16019370Spstdirectives such as @code{.file} and @code{.bi}) instead of 16119370Spst@code{.stabs}, @code{.stabn} or @code{.stabd}. 16219370Spst 16319370SpstThe overall format of each class of stab is: 16419370Spst 16519370Spst@example 16619370Spst.stabs "@var{string}",@var{type},@var{other},@var{desc},@var{value} 16719370Spst.stabn @var{type},@var{other},@var{desc},@var{value} 16819370Spst.stabd @var{type},@var{other},@var{desc} 16919370Spst.stabx "@var{string}",@var{value},@var{type},@var{sdb-type} 17019370Spst@end example 17119370Spst 17219370Spst@c what is the correct term for "current file location"? My AIX 17319370Spst@c assembler manual calls it "the value of the current location counter". 17419370SpstFor @code{.stabn} and @code{.stabd}, there is no @var{string} (the 17519370Spst@code{n_strx} field is zero; see @ref{Symbol Tables}). For 17619370Spst@code{.stabd}, the @var{value} field is implicit and has the value of 17719370Spstthe current file location. For @code{.stabx}, the @var{sdb-type} field 17819370Spstis unused for stabs and can always be set to zero. The @var{other} 17919370Spstfield is almost always unused and can be set to zero. 18019370Spst 18119370SpstThe number in the @var{type} field gives some basic information about 18219370Spstwhich type of stab this is (or whether it @emph{is} a stab, as opposed 18319370Spstto an ordinary symbol). Each valid type number defines a different stab 18419370Spsttype; further, the stab type defines the exact interpretation of, and 18519370Spstpossible values for, any remaining @var{string}, @var{desc}, or 18619370Spst@var{value} fields present in the stab. @xref{Stab Types}, for a list 18719370Spstin numeric order of the valid @var{type} field values for stab directives. 18819370Spst 18919370Spst@node String Field 19019370Spst@section The String Field 19119370Spst 19219370SpstFor most stabs the string field holds the meat of the 19319370Spstdebugging information. The flexible nature of this field 19419370Spstis what makes stabs extensible. For some stab types the string field 19519370Spstcontains only a name. For other stab types the contents can be a great 19619370Spstdeal more complex. 19719370Spst 19819370SpstThe overall format of the string field for most stab types is: 19919370Spst 20019370Spst@example 20119370Spst"@var{name}:@var{symbol-descriptor} @var{type-information}" 20219370Spst@end example 20319370Spst 20419370Spst@var{name} is the name of the symbol represented by the stab; it can 20519370Spstcontain a pair of colons (@pxref{Nested Symbols}). @var{name} can be 20619370Spstomitted, which means the stab represents an unnamed object. For 20719370Spstexample, @samp{:t10=*2} defines type 10 as a pointer to type 2, but does 20819370Spstnot give the type a name. Omitting the @var{name} field is supported by 20919370SpstAIX dbx and GDB after about version 4.8, but not other debuggers. GCC 21019370Spstsometimes uses a single space as the name instead of omitting the name 21119370Spstaltogether; apparently that is supported by most debuggers. 21219370Spst 21319370SpstThe @var{symbol-descriptor} following the @samp{:} is an alphabetic 21419370Spstcharacter that tells more specifically what kind of symbol the stab 21519370Spstrepresents. If the @var{symbol-descriptor} is omitted, but type 21619370Spstinformation follows, then the stab represents a local variable. For a 21719370Spstlist of symbol descriptors, see @ref{Symbol Descriptors}. The @samp{c} 21819370Spstsymbol descriptor is an exception in that it is not followed by type 21919370Spstinformation. @xref{Constants}. 22019370Spst 22119370Spst@var{type-information} is either a @var{type-number}, or 22219370Spst@samp{@var{type-number}=}. A @var{type-number} alone is a type 22319370Spstreference, referring directly to a type that has already been defined. 22419370Spst 22519370SpstThe @samp{@var{type-number}=} form is a type definition, where the 22619370Spstnumber represents a new type which is about to be defined. The type 22719370Spstdefinition may refer to other types by number, and those type numbers 22819370Spstmay be followed by @samp{=} and nested definitions. Also, the Lucid 22919370Spstcompiler will repeat @samp{@var{type-number}=} more than once if it 23019370Spstwants to define several type numbers at once. 23119370Spst 23219370SpstIn a type definition, if the character that follows the equals sign is 23319370Spstnon-numeric then it is a @var{type-descriptor}, and tells what kind of 23419370Spsttype is about to be defined. Any other values following the 23519370Spst@var{type-descriptor} vary, depending on the @var{type-descriptor}. 23619370Spst@xref{Type Descriptors}, for a list of @var{type-descriptor} values. If 23719370Spsta number follows the @samp{=} then the number is a @var{type-reference}. 23819370SpstFor a full description of types, @ref{Types}. 23919370Spst 24046289SdfrA @var{type-number} is often a single number. The GNU and Sun tools 24146289Sdfradditionally permit a @var{type-number} to be a pair 24246289Sdfr(@var{file-number},@var{filetype-number}) (the parentheses appear in the 24346289Sdfrstring, and serve to distinguish the two cases). The @var{file-number} 24498948Sobrienis 0 for the base source file, 1 for the first included file, 2 for the 24598948Sobriennext, and so on. The @var{filetype-number} is a number starting with 24646289Sdfr1 which is incremented for each new type defined in the file. 24746289Sdfr(Separating the file number and the type number permits the 24846289Sdfr@code{N_BINCL} optimization to succeed more often; see @ref{Include 24946289SdfrFiles}). 25046289Sdfr 25119370SpstThere is an AIX extension for type attributes. Following the @samp{=} 25219370Spstare any number of type attributes. Each one starts with @samp{@@} and 25319370Spstends with @samp{;}. Debuggers, including AIX's dbx and GDB 4.10, skip 25419370Spstany type attributes they do not recognize. GDB 4.9 and other versions 255130809Smarcelof dbx may not do this. Because of a conflict with C@t{++} 25619370Spst(@pxref{Cplusplus}), new attributes should not be defined which begin 25719370Spstwith a digit, @samp{(}, or @samp{-}; GDB may be unable to distinguish 258130809Smarcelthose from the C@t{++} type descriptor @samp{@@}. The attributes are: 25919370Spst 26019370Spst@table @code 26119370Spst@item a@var{boundary} 26219370Spst@var{boundary} is an integer specifying the alignment. I assume it 26319370Spstapplies to all variables of this type. 26419370Spst 26519370Spst@item p@var{integer} 26619370SpstPointer class (for checking). Not sure what this means, or how 26719370Spst@var{integer} is interpreted. 26819370Spst 26919370Spst@item P 27019370SpstIndicate this is a packed type, meaning that structure fields or array 27119370Spstelements are placed more closely in memory, to save memory at the 27219370Spstexpense of speed. 27319370Spst 27419370Spst@item s@var{size} 27519370SpstSize in bits of a variable of this type. This is fully supported by GDB 27619370Spst4.11 and later. 27719370Spst 27819370Spst@item S 27919370SpstIndicate that this type is a string instead of an array of characters, 28019370Spstor a bitstring instead of a set. It doesn't change the layout of the 28119370Spstdata being represented, but does enable the debugger to know which type 28219370Spstit is. 283130809Smarcel 284130809Smarcel@item V 285130809SmarcelIndicate that this type is a vector instead of an array. The only 286130809Smarcelmajor difference between vectors and arrays is that vectors are 287130809Smarcelpassed by value instead of by reference (vector coprocessor extension). 288130809Smarcel 28919370Spst@end table 29019370Spst 29119370SpstAll of this can make the string field quite long. All versions of GDB, 29219370Spstand some versions of dbx, can handle arbitrarily long strings. But many 29319370Spstversions of dbx (or assemblers or linkers, I'm not sure which) 29419370Spstcretinously limit the strings to about 80 characters, so compilers which 29519370Spstmust work with such systems need to split the @code{.stabs} directive 29619370Spstinto several @code{.stabs} directives. Each stab duplicates every field 29719370Spstexcept the string field. The string field of every stab except the last 29819370Spstis marked as continued with a backslash at the end (in the assembly code 29919370Spstthis may be written as a double backslash, depending on the assembler). 30019370SpstRemoving the backslashes and concatenating the string fields of each 30119370Spststab produces the original, long string. Just to be incompatible (or so 30219370Spstthey don't have to worry about what the assembler does with 30319370Spstbackslashes), AIX can use @samp{?} instead of backslash. 30419370Spst 30519370Spst@node C Example 30619370Spst@section A Simple Example in C Source 30719370Spst 30819370SpstTo get the flavor of how stabs describe source information for a C 30919370Spstprogram, let's look at the simple program: 31019370Spst 31119370Spst@example 31219370Spstmain() 31319370Spst@{ 31419370Spst printf("Hello world"); 31519370Spst@} 31619370Spst@end example 31719370Spst 31819370SpstWhen compiled with @samp{-g}, the program above yields the following 31919370Spst@file{.s} file. Line numbers have been added to make it easier to refer 32019370Spstto parts of the @file{.s} file in the description of the stabs that 32119370Spstfollows. 32219370Spst 32319370Spst@node Assembly Code 32419370Spst@section The Simple Example at the Assembly Level 32519370Spst 32619370SpstThis simple ``hello world'' example demonstrates several of the stab 32719370Spsttypes used to describe C language source files. 32819370Spst 32919370Spst@example 33019370Spst1 gcc2_compiled.: 33119370Spst2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 33219370Spst3 .stabs "hello.c",100,0,0,Ltext0 33319370Spst4 .text 33419370Spst5 Ltext0: 33519370Spst6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 33619370Spst7 .stabs "char:t2=r2;0;127;",128,0,0,0 33719370Spst8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0 33819370Spst9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 33919370Spst10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0 34019370Spst11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0 34119370Spst12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0 34219370Spst13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0 34319370Spst14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0 34419370Spst15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0 34519370Spst16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0 34619370Spst17 .stabs "float:t12=r1;4;0;",128,0,0,0 34719370Spst18 .stabs "double:t13=r1;8;0;",128,0,0,0 34819370Spst19 .stabs "long double:t14=r1;8;0;",128,0,0,0 34919370Spst20 .stabs "void:t15=15",128,0,0,0 35019370Spst21 .align 4 35119370Spst22 LC0: 35219370Spst23 .ascii "Hello, world!\12\0" 35319370Spst24 .align 4 35419370Spst25 .global _main 35519370Spst26 .proc 1 35619370Spst27 _main: 35719370Spst28 .stabn 68,0,4,LM1 35819370Spst29 LM1: 35919370Spst30 !#PROLOGUE# 0 36019370Spst31 save %sp,-136,%sp 36119370Spst32 !#PROLOGUE# 1 36219370Spst33 call ___main,0 36319370Spst34 nop 36419370Spst35 .stabn 68,0,5,LM2 36519370Spst36 LM2: 36619370Spst37 LBB2: 36719370Spst38 sethi %hi(LC0),%o1 36819370Spst39 or %o1,%lo(LC0),%o0 36919370Spst40 call _printf,0 37019370Spst41 nop 37119370Spst42 .stabn 68,0,6,LM3 37219370Spst43 LM3: 37319370Spst44 LBE2: 37419370Spst45 .stabn 68,0,6,LM4 37519370Spst46 LM4: 37619370Spst47 L1: 37719370Spst48 ret 37819370Spst49 restore 37919370Spst50 .stabs "main:F1",36,0,0,_main 38019370Spst51 .stabn 192,0,0,LBB2 38119370Spst52 .stabn 224,0,0,LBE2 38219370Spst@end example 38319370Spst 38419370Spst@node Program Structure 38519370Spst@chapter Encoding the Structure of the Program 38619370Spst 38719370SpstThe elements of the program structure that stabs encode include the name 38819370Spstof the main function, the names of the source and include files, the 38919370Spstline numbers, procedure names and types, and the beginnings and ends of 39019370Spstblocks of code. 39119370Spst 39219370Spst@menu 39319370Spst* Main Program:: Indicate what the main program is 39419370Spst* Source Files:: The path and name of the source file 39519370Spst* Include Files:: Names of include files 39619370Spst* Line Numbers:: 39719370Spst* Procedures:: 39819370Spst* Nested Procedures:: 39919370Spst* Block Structure:: 40019370Spst* Alternate Entry Points:: Entering procedures except at the beginning. 40119370Spst@end menu 40219370Spst 40319370Spst@node Main Program 40419370Spst@section Main Program 40519370Spst 40619370Spst@findex N_MAIN 40719370SpstMost languages allow the main program to have any name. The 40819370Spst@code{N_MAIN} stab type tells the debugger the name that is used in this 40919370Spstprogram. Only the string field is significant; it is the name of 41019370Spsta function which is the main program. Most C compilers do not use this 41119370Spststab (they expect the debugger to assume that the name is @code{main}), 41219370Spstbut some C compilers emit an @code{N_MAIN} stab for the @code{main} 41319370Spstfunction. I'm not sure how XCOFF handles this. 41419370Spst 41519370Spst@node Source Files 41619370Spst@section Paths and Names of the Source Files 41719370Spst 41819370Spst@findex N_SO 41919370SpstBefore any other stabs occur, there must be a stab specifying the source 42019370Spstfile. This information is contained in a symbol of stab type 42119370Spst@code{N_SO}; the string field contains the name of the file. The 42219370Spstvalue of the symbol is the start address of the portion of the 42319370Spsttext section corresponding to that file. 42419370Spst 42519370SpstWith the Sun Solaris2 compiler, the desc field contains a 42619370Spstsource-language code. 42719370Spst@c Do the debuggers use it? What are the codes? -djm 42819370Spst 42919370SpstSome compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also 43019370Spstinclude the directory in which the source was compiled, in a second 43119370Spst@code{N_SO} symbol preceding the one containing the file name. This 43219370Spstsymbol can be distinguished by the fact that it ends in a slash. Code 433130809Smarcelfrom the @code{cfront} C@t{++} compiler can have additional @code{N_SO} symbols for 43419370Spstnonexistent source files after the @code{N_SO} for the real source file; 43519370Spstthese are believed to contain no useful information. 43619370Spst 43719370SpstFor example: 43819370Spst 43919370Spst@example 44019370Spst.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 # @r{100 is N_SO} 44119370Spst.stabs "hello.c",100,0,0,Ltext0 44219370Spst .text 44319370SpstLtext0: 44419370Spst@end example 44519370Spst 44619370Spst@findex C_FILE 44719370SpstInstead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler 44819370Spstdirective which assembles to a @code{C_FILE} symbol; explaining this in 44919370Spstdetail is outside the scope of this document. 45019370Spst 45119370Spst@c FIXME: Exactly when should the empty N_SO be used? Why? 45219370SpstIf it is useful to indicate the end of a source file, this is done with 45319370Spstan @code{N_SO} symbol with an empty string for the name. The value is 45419370Spstthe address of the end of the text section for the file. For some 45519370Spstsystems, there is no indication of the end of a source file, and you 45619370Spstjust need to figure it ended when you see an @code{N_SO} for a different 45719370Spstsource file, or a symbol ending in @code{.o} (which at least some 45819370Spstlinkers insert to mark the start of a new @code{.o} file). 45919370Spst 46019370Spst@node Include Files 46119370Spst@section Names of Include Files 46219370Spst 46319370SpstThere are several schemes for dealing with include files: the 46419370Spsttraditional @code{N_SOL} approach, Sun's @code{N_BINCL} approach, and the 46519370SpstXCOFF @code{C_BINCL} approach (which despite the similar name has little in 46619370Spstcommon with @code{N_BINCL}). 46719370Spst 46819370Spst@findex N_SOL 46919370SpstAn @code{N_SOL} symbol specifies which include file subsequent symbols 47019370Spstrefer to. The string field is the name of the file and the value is the 47119370Spsttext address corresponding to the end of the previous include file and 47219370Spstthe start of this one. To specify the main source file again, use an 47319370Spst@code{N_SOL} symbol with the name of the main source file. 47419370Spst 47519370Spst@findex N_BINCL 47619370Spst@findex N_EINCL 47719370Spst@findex N_EXCL 47819370SpstThe @code{N_BINCL} approach works as follows. An @code{N_BINCL} symbol 47919370Spstspecifies the start of an include file. In an object file, only the 48046289Sdfrstring is significant; the linker puts data into some of the other 48119370Spstfields. The end of the include file is marked by an @code{N_EINCL} 48219370Spstsymbol (which has no string field). In an object file, there is no 48319370Spstsignificant data in the @code{N_EINCL} symbol. @code{N_BINCL} and 48419370Spst@code{N_EINCL} can be nested. 48519370Spst 48619370SpstIf the linker detects that two source files have identical stabs between 48719370Spstan @code{N_BINCL} and @code{N_EINCL} pair (as will generally be the case 48819370Spstfor a header file), then it only puts out the stabs once. Each 48998948Sobrienadditional occurrence is replaced by an @code{N_EXCL} symbol. I believe 49046289Sdfrthe GNU linker and the Sun (both SunOS4 and Solaris) linker are the only 49146289Sdfrones which supports this feature. 49219370Spst 49346289SdfrA linker which supports this feature will set the value of a 49446289Sdfr@code{N_BINCL} symbol to the total of all the characters in the stabs 49546289Sdfrstrings included in the header file, omitting any file numbers. The 49646289Sdfrvalue of an @code{N_EXCL} symbol is the same as the value of the 49746289Sdfr@code{N_BINCL} symbol it replaces. This information can be used to 49846289Sdfrmatch up @code{N_EXCL} and @code{N_BINCL} symbols which have the same 49946289Sdfrfilename. The @code{N_EINCL} value, and the values of the other and 50046289Sdfrdescription fields for all three, appear to always be zero. 50119370Spst 50219370Spst@findex C_BINCL 50319370Spst@findex C_EINCL 50419370SpstFor the start of an include file in XCOFF, use the @file{.bi} assembler 50519370Spstdirective, which generates a @code{C_BINCL} symbol. A @file{.ei} 50619370Spstdirective, which generates a @code{C_EINCL} symbol, denotes the end of 50719370Spstthe include file. Both directives are followed by the name of the 50819370Spstsource file in quotes, which becomes the string for the symbol. 50919370SpstThe value of each symbol, produced automatically by the assembler 51019370Spstand linker, is the offset into the executable of the beginning 51119370Spst(inclusive, as you'd expect) or end (inclusive, as you would not expect) 51219370Spstof the portion of the COFF line table that corresponds to this include 51319370Spstfile. @code{C_BINCL} and @code{C_EINCL} do not nest. 51419370Spst 51519370Spst@node Line Numbers 51619370Spst@section Line Numbers 51719370Spst 51819370Spst@findex N_SLINE 51919370SpstAn @code{N_SLINE} symbol represents the start of a source line. The 52019370Spstdesc field contains the line number and the value contains the code 52119370Spstaddress for the start of that source line. On most machines the address 52219370Spstis absolute; for stabs in sections (@pxref{Stab Sections}), it is 52319370Spstrelative to the function in which the @code{N_SLINE} symbol occurs. 52419370Spst 52519370Spst@findex N_DSLINE 52619370Spst@findex N_BSLINE 52719370SpstGNU documents @code{N_DSLINE} and @code{N_BSLINE} symbols for line 52819370Spstnumbers in the data or bss segments, respectively. They are identical 52919370Spstto @code{N_SLINE} but are relocated differently by the linker. They 53019370Spstwere intended to be used to describe the source location of a variable 53119370Spstdeclaration, but I believe that GCC2 actually puts the line number in 53219370Spstthe desc field of the stab for the variable itself. GDB has been 53319370Spstignoring these symbols (unless they contain a string field) since 53419370Spstat least GDB 3.5. 53519370Spst 53619370SpstFor single source lines that generate discontiguous code, such as flow 53719370Spstof control statements, there may be more than one line number entry for 53819370Spstthe same source line. In this case there is a line number entry at the 53919370Spststart of each code range, each with the same line number. 54019370Spst 54119370SpstXCOFF does not use stabs for line numbers. Instead, it uses COFF line 54219370Spstnumbers (which are outside the scope of this document). Standard COFF 54319370Spstline numbers cannot deal with include files, but in XCOFF this is fixed 54419370Spstwith the @code{C_BINCL} method of marking include files (@pxref{Include 54519370SpstFiles}). 54619370Spst 54719370Spst@node Procedures 54819370Spst@section Procedures 54919370Spst 55019370Spst@findex N_FUN, for functions 55119370Spst@findex N_FNAME 55219370Spst@findex N_STSYM, for functions (Sun acc) 55319370Spst@findex N_GSYM, for functions (Sun acc) 55419370SpstAll of the following stabs normally use the @code{N_FUN} symbol type. 55519370SpstHowever, Sun's @code{acc} compiler on SunOS4 uses @code{N_GSYM} and 55619370Spst@code{N_STSYM}, which means that the value of the stab for the function 55719370Spstis useless and the debugger must get the address of the function from 55819370Spstthe non-stab symbols instead. On systems where non-stab symbols have 55919370Spstleading underscores, the stabs will lack underscores and the debugger 56019370Spstneeds to know about the leading underscore to match up the stab and the 56119370Spstnon-stab symbol. BSD Fortran is said to use @code{N_FNAME} with the 56219370Spstsame restriction; the value of the symbol is not useful (I'm not sure it 56319370Spstreally does use this, because GDB doesn't handle this and no one has 56419370Spstcomplained). 56519370Spst 56619370Spst@findex C_FUN 56719370SpstA function is represented by an @samp{F} symbol descriptor for a global 56819370Spst(extern) function, and @samp{f} for a static (local) function. For 56919370Spsta.out, the value of the symbol is the address of the start of the 57019370Spstfunction; it is already relocated. For stabs in ELF, the SunPRO 57119370Spstcompiler version 2.0.1 and GCC put out an address which gets relocated 57219370Spstby the linker. In a future release SunPRO is planning to put out zero, 57319370Spstin which case the address can be found from the ELF (non-stab) symbol. 57419370SpstBecause looking things up in the ELF symbols would probably be slow, I'm 57519370Spstnot sure how to find which symbol of that name is the right one, and 57619370Spstthis doesn't provide any way to deal with nested functions, it would 57719370Spstprobably be better to make the value of the stab an address relative to 57819370Spstthe start of the file, or just absolute. See @ref{ELF Linker 57919370SpstRelocation} for more information on linker relocation of stabs in ELF 58019370Spstfiles. For XCOFF, the stab uses the @code{C_FUN} storage class and the 58119370Spstvalue of the stab is meaningless; the address of the function can be 58219370Spstfound from the csect symbol (XTY_LD/XMC_PR). 58319370Spst 58419370SpstThe type information of the stab represents the return type of the 58519370Spstfunction; thus @samp{foo:f5} means that foo is a function returning type 58619370Spst5. There is no need to try to get the line number of the start of the 58719370Spstfunction from the stab for the function; it is in the next 58819370Spst@code{N_SLINE} symbol. 58919370Spst 59019370Spst@c FIXME: verify whether the "I suspect" below is true or not. 59119370SpstSome compilers (such as Sun's Solaris compiler) support an extension for 59219370Spstspecifying the types of the arguments. I suspect this extension is not 59319370Spstused for old (non-prototyped) function definitions in C. If the 59419370Spstextension is in use, the type information of the stab for the function 59519370Spstis followed by type information for each argument, with each argument 59619370Spstpreceded by @samp{;}. An argument type of 0 means that additional 59719370Spstarguments are being passed, whose types and number may vary (@samp{...} 59819370Spstin ANSI C). GDB has tolerated this extension (parsed the syntax, if not 59919370Spstnecessarily used the information) since at least version 4.8; I don't 60019370Spstknow whether all versions of dbx tolerate it. The argument types given 60119370Spsthere are not redundant with the symbols for the formal parameters 60219370Spst(@pxref{Parameters}); they are the types of the arguments as they are 60319370Spstpassed, before any conversions might take place. For example, if a C 60419370Spstfunction which is declared without a prototype takes a @code{float} 60519370Spstargument, the value is passed as a @code{double} but then converted to a 60619370Spst@code{float}. Debuggers need to use the types given in the arguments 60719370Spstwhen printing values, but when calling the function they need to use the 60819370Spsttypes given in the symbol defining the function. 60919370Spst 61019370SpstIf the return type and types of arguments of a function which is defined 61119370Spstin another source file are specified (i.e., a function prototype in ANSI 61219370SpstC), traditionally compilers emit no stab; the only way for the debugger 61319370Spstto find the information is if the source file where the function is 61419370Spstdefined was also compiled with debugging symbols. As an extension the 61519370SpstSolaris compiler uses symbol descriptor @samp{P} followed by the return 61619370Spsttype of the function, followed by the arguments, each preceded by 61719370Spst@samp{;}, as in a stab with symbol descriptor @samp{f} or @samp{F}. 61819370SpstThis use of symbol descriptor @samp{P} can be distinguished from its use 61919370Spstfor register parameters (@pxref{Register Parameters}) by the fact that it has 62019370Spstsymbol type @code{N_FUN}. 62119370Spst 62219370SpstThe AIX documentation also defines symbol descriptor @samp{J} as an 62319370Spstinternal function. I assume this means a function nested within another 62419370Spstfunction. It also says symbol descriptor @samp{m} is a module in 62519370SpstModula-2 or extended Pascal. 62619370Spst 62719370SpstProcedures (functions which do not return values) are represented as 62819370Spstfunctions returning the @code{void} type in C. I don't see why this couldn't 62919370Spstbe used for all languages (inventing a @code{void} type for this purpose if 63019370Spstnecessary), but the AIX documentation defines @samp{I}, @samp{P}, and 63119370Spst@samp{Q} for internal, global, and static procedures, respectively. 63219370SpstThese symbol descriptors are unusual in that they are not followed by 63319370Spsttype information. 63419370Spst 63519370SpstThe following example shows a stab for a function @code{main} which 63619370Spstreturns type number @code{1}. The @code{_main} specified for the value 63719370Spstis a reference to an assembler label which is used to fill in the start 63819370Spstaddress of the function. 63919370Spst 64019370Spst@example 64119370Spst.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} 64219370Spst@end example 64319370Spst 64419370SpstThe stab representing a procedure is located immediately following the 64519370Spstcode of the procedure. This stab is in turn directly followed by a 64619370Spstgroup of other stabs describing elements of the procedure. These other 64719370Spststabs describe the procedure's parameters, its block local variables, and 64819370Spstits block structure. 64919370Spst 65046289SdfrIf functions can appear in different sections, then the debugger may not 65146289Sdfrbe able to find the end of a function. Recent versions of GCC will mark 65246289Sdfrthe end of a function with an @code{N_FUN} symbol with an empty string 65346289Sdfrfor the name. The value is the address of the end of the current 65446289Sdfrfunction. Without such a symbol, there is no indication of the address 65546289Sdfrof the end of a function, and you must assume that it ended at the 65646289Sdfrstarting address of the next function or at the end of the text section 65746289Sdfrfor the program. 65846289Sdfr 65919370Spst@node Nested Procedures 66019370Spst@section Nested Procedures 66119370Spst 66219370SpstFor any of the symbol descriptors representing procedures, after the 66319370Spstsymbol descriptor and the type information is optionally a scope 66419370Spstspecifier. This consists of a comma, the name of the procedure, another 66519370Spstcomma, and the name of the enclosing procedure. The first name is local 66619370Spstto the scope specified, and seems to be redundant with the name of the 66719370Spstsymbol (before the @samp{:}). This feature is used by GCC, and 66819370Spstpresumably Pascal, Modula-2, etc., compilers, for nested functions. 66919370Spst 67019370SpstIf procedures are nested more than one level deep, only the immediately 67119370Spstcontaining scope is specified. For example, this code: 67219370Spst 67319370Spst@example 67419370Spstint 67519370Spstfoo (int x) 67619370Spst@{ 67719370Spst int bar (int y) 67819370Spst @{ 67919370Spst int baz (int z) 68019370Spst @{ 68119370Spst return x + y + z; 68219370Spst @} 68319370Spst return baz (x + 2 * y); 68419370Spst @} 68519370Spst return x + bar (3 * x); 68619370Spst@} 68719370Spst@end example 68819370Spst 68919370Spst@noindent 69019370Spstproduces the stabs: 69119370Spst 69219370Spst@example 69319370Spst.stabs "baz:f1,baz,bar",36,0,0,_baz.15 # @r{36 is N_FUN} 69419370Spst.stabs "bar:f1,bar,foo",36,0,0,_bar.12 69519370Spst.stabs "foo:F1",36,0,0,_foo 69619370Spst@end example 69719370Spst 69819370Spst@node Block Structure 69919370Spst@section Block Structure 70019370Spst 70119370Spst@findex N_LBRAC 70219370Spst@findex N_RBRAC 70319370Spst@c For GCC 2.5.8 or so stabs-in-coff, these are absolute instead of 70419370Spst@c function relative (as documented below). But GDB has never been able 70519370Spst@c to deal with that (it had wanted them to be relative to the file, but 70619370Spst@c I just fixed that (between GDB 4.12 and 4.13)), so it is function 70719370Spst@c relative just like ELF and SOM and the below documentation. 70819370SpstThe program's block structure is represented by the @code{N_LBRAC} (left 70919370Spstbrace) and the @code{N_RBRAC} (right brace) stab types. The variables 71019370Spstdefined inside a block precede the @code{N_LBRAC} symbol for most 71119370Spstcompilers, including GCC. Other compilers, such as the Convex, Acorn 71219370SpstRISC machine, and Sun @code{acc} compilers, put the variables after the 71319370Spst@code{N_LBRAC} symbol. The values of the @code{N_LBRAC} and 71419370Spst@code{N_RBRAC} symbols are the start and end addresses of the code of 71519370Spstthe block, respectively. For most machines, they are relative to the 71619370Spststarting address of this source file. For the Gould NP1, they are 71719370Spstabsolute. For stabs in sections (@pxref{Stab Sections}), they are 71819370Spstrelative to the function in which they occur. 71919370Spst 72019370SpstThe @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block 72119370Spstscope of a procedure are located after the @code{N_FUN} stab that 72219370Spstrepresents the procedure itself. 72319370Spst 72419370SpstSun documents the desc field of @code{N_LBRAC} and 72519370Spst@code{N_RBRAC} symbols as containing the nesting level of the block. 72619370SpstHowever, dbx seems to not care, and GCC always sets desc to 72719370Spstzero. 72819370Spst 72919370Spst@findex .bb 73019370Spst@findex .be 73119370Spst@findex C_BLOCK 73219370SpstFor XCOFF, block scope is indicated with @code{C_BLOCK} symbols. If the 73319370Spstname of the symbol is @samp{.bb}, then it is the beginning of the block; 73419370Spstif the name of the symbol is @samp{.be}; it is the end of the block. 73519370Spst 73619370Spst@node Alternate Entry Points 73719370Spst@section Alternate Entry Points 73819370Spst 73919370Spst@findex N_ENTRY 74019370Spst@findex C_ENTRY 74119370SpstSome languages, like Fortran, have the ability to enter procedures at 74219370Spstsome place other than the beginning. One can declare an alternate entry 74319370Spstpoint. The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN 74419370Spstcompiler doesn't use it. According to AIX documentation, only the name 74519370Spstof a @code{C_ENTRY} stab is significant; the address of the alternate 74619370Spstentry point comes from the corresponding external symbol. A previous 74719370Spstrevision of this document said that the value of an @code{N_ENTRY} stab 74819370Spstwas the address of the alternate entry point, but I don't know the 74919370Spstsource for that information. 75019370Spst 75119370Spst@node Constants 75219370Spst@chapter Constants 75319370Spst 75419370SpstThe @samp{c} symbol descriptor indicates that this stab represents a 75519370Spstconstant. This symbol descriptor is an exception to the general rule 75619370Spstthat symbol descriptors are followed by type information. Instead, it 75719370Spstis followed by @samp{=} and one of the following: 75819370Spst 75919370Spst@table @code 76019370Spst@item b @var{value} 76119370SpstBoolean constant. @var{value} is a numeric value; I assume it is 0 for 76219370Spstfalse or 1 for true. 76319370Spst 76419370Spst@item c @var{value} 76519370SpstCharacter constant. @var{value} is the numeric value of the constant. 76619370Spst 76719370Spst@item e @var{type-information} , @var{value} 76819370SpstConstant whose value can be represented as integral. 76919370Spst@var{type-information} is the type of the constant, as it would appear 77019370Spstafter a symbol descriptor (@pxref{String Field}). @var{value} is the 77119370Spstnumeric value of the constant. GDB 4.9 does not actually get the right 77219370Spstvalue if @var{value} does not fit in a host @code{int}, but it does not 77319370Spstdo anything violent, and future debuggers could be extended to accept 77419370Spstintegers of any size (whether unsigned or not). This constant type is 77519370Spstusually documented as being only for enumeration constants, but GDB has 77619370Spstnever imposed that restriction; I don't know about other debuggers. 77719370Spst 77819370Spst@item i @var{value} 77919370SpstInteger constant. @var{value} is the numeric value. The type is some 78019370Spstsort of generic integer type (for GDB, a host @code{int}); to specify 78119370Spstthe type explicitly, use @samp{e} instead. 78219370Spst 78319370Spst@item r @var{value} 78419370SpstReal constant. @var{value} is the real value, which can be @samp{INF} 78519370Spst(optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet 78619370SpstNaN (not-a-number), or @samp{SNAN} for a signalling NaN. If it is a 78719370Spstnormal number the format is that accepted by the C library function 78819370Spst@code{atof}. 78919370Spst 79019370Spst@item s @var{string} 79119370SpstString constant. @var{string} is a string enclosed in either @samp{'} 79219370Spst(in which case @samp{'} characters within the string are represented as 79319370Spst@samp{\'} or @samp{"} (in which case @samp{"} characters within the 79419370Spststring are represented as @samp{\"}). 79519370Spst 79619370Spst@item S @var{type-information} , @var{elements} , @var{bits} , @var{pattern} 79719370SpstSet constant. @var{type-information} is the type of the constant, as it 79819370Spstwould appear after a symbol descriptor (@pxref{String Field}). 79919370Spst@var{elements} is the number of elements in the set (does this means 80019370Spsthow many bits of @var{pattern} are actually used, which would be 80119370Spstredundant with the type, or perhaps the number of bits set in 80219370Spst@var{pattern}? I don't get it), @var{bits} is the number of bits in the 80319370Spstconstant (meaning it specifies the length of @var{pattern}, I think), 80419370Spstand @var{pattern} is a hexadecimal representation of the set. AIX 80519370Spstdocumentation refers to a limit of 32 bytes, but I see no reason why 80619370Spstthis limit should exist. This form could probably be used for arbitrary 80719370Spstconstants, not just sets; the only catch is that @var{pattern} should be 80819370Spstunderstood to be target, not host, byte order and format. 80919370Spst@end table 81019370Spst 81119370SpstThe boolean, character, string, and set constants are not supported by 81219370SpstGDB 4.9, but it ignores them. GDB 4.8 and earlier gave an error 81319370Spstmessage and refused to read symbols from the file containing the 81419370Spstconstants. 81519370Spst 81619370SpstThe above information is followed by @samp{;}. 81719370Spst 81819370Spst@node Variables 81919370Spst@chapter Variables 82019370Spst 82119370SpstDifferent types of stabs describe the various ways that variables can be 82219370Spstallocated: on the stack, globally, in registers, in common blocks, 82319370Spststatically, or as arguments to a function. 82419370Spst 82519370Spst@menu 82619370Spst* Stack Variables:: Variables allocated on the stack. 82719370Spst* Global Variables:: Variables used by more than one source file. 82819370Spst* Register Variables:: Variables in registers. 82919370Spst* Common Blocks:: Variables statically allocated together. 83019370Spst* Statics:: Variables local to one source file. 83119370Spst* Based Variables:: Fortran pointer based variables. 83219370Spst* Parameters:: Variables for arguments to functions. 83319370Spst@end menu 83419370Spst 83519370Spst@node Stack Variables 83619370Spst@section Automatic Variables Allocated on the Stack 83719370Spst 83819370SpstIf a variable's scope is local to a function and its lifetime is only as 83919370Spstlong as that function executes (C calls such variables 84019370Spst@dfn{automatic}), it can be allocated in a register (@pxref{Register 84119370SpstVariables}) or on the stack. 84219370Spst 84319370Spst@findex N_LSYM, for stack variables 84419370Spst@findex C_LSYM 84519370SpstEach variable allocated on the stack has a stab with the symbol 84619370Spstdescriptor omitted. Since type information should begin with a digit, 84719370Spst@samp{-}, or @samp{(}, only those characters precluded from being used 84819370Spstfor symbol descriptors. However, the Acorn RISC machine (ARM) is said 84919370Spstto get this wrong: it puts out a mere type definition here, without the 85019370Spstpreceding @samp{@var{type-number}=}. This is a bad idea; there is no 85119370Spstguarantee that type descriptors are distinct from symbol descriptors. 85219370SpstStabs for stack variables use the @code{N_LSYM} stab type, or 85319370Spst@code{C_LSYM} for XCOFF. 85419370Spst 85519370SpstThe value of the stab is the offset of the variable within the 85619370Spstlocal variables. On most machines this is an offset from the frame 85719370Spstpointer and is negative. The location of the stab specifies which block 85819370Spstit is defined in; see @ref{Block Structure}. 85919370Spst 86019370SpstFor example, the following C code: 86119370Spst 86219370Spst@example 86319370Spstint 86419370Spstmain () 86519370Spst@{ 86619370Spst int x; 86719370Spst@} 86819370Spst@end example 86919370Spst 87019370Spstproduces the following stabs: 87119370Spst 87219370Spst@example 87319370Spst.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} 87419370Spst.stabs "x:1",128,0,0,-12 # @r{128 is N_LSYM} 87519370Spst.stabn 192,0,0,LBB2 # @r{192 is N_LBRAC} 87619370Spst.stabn 224,0,0,LBE2 # @r{224 is N_RBRAC} 87719370Spst@end example 87819370Spst 87998948SobrienSee @ref{Procedures} for more information on the @code{N_FUN} stab, and 88019370Spst@ref{Block Structure} for more information on the @code{N_LBRAC} and 88119370Spst@code{N_RBRAC} stabs. 88219370Spst 88319370Spst@node Global Variables 88419370Spst@section Global Variables 88519370Spst 88619370Spst@findex N_GSYM 88719370Spst@findex C_GSYM 88819370Spst@c FIXME: verify for sure that it really is C_GSYM on XCOFF 88919370SpstA variable whose scope is not specific to just one source file is 89019370Spstrepresented by the @samp{G} symbol descriptor. These stabs use the 89119370Spst@code{N_GSYM} stab type (C_GSYM for XCOFF). The type information for 89219370Spstthe stab (@pxref{String Field}) gives the type of the variable. 89319370Spst 89419370SpstFor example, the following source code: 89519370Spst 89619370Spst@example 89719370Spstchar g_foo = 'c'; 89819370Spst@end example 89919370Spst 90019370Spst@noindent 90119370Spstyields the following assembly code: 90219370Spst 90319370Spst@example 90419370Spst.stabs "g_foo:G2",32,0,0,0 # @r{32 is N_GSYM} 90519370Spst .global _g_foo 90619370Spst .data 90719370Spst_g_foo: 90819370Spst .byte 99 90919370Spst@end example 91019370Spst 91119370SpstThe address of the variable represented by the @code{N_GSYM} is not 91219370Spstcontained in the @code{N_GSYM} stab. The debugger gets this information 91319370Spstfrom the external symbol for the global variable. In the example above, 91419370Spstthe @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to 91519370Spstproduce an external symbol. 91619370Spst 91719370SpstSome compilers, like GCC, output @code{N_GSYM} stabs only once, where 91819370Spstthe variable is defined. Other compilers, like SunOS4 /bin/cc, output a 91919370Spst@code{N_GSYM} stab for each compilation unit which references the 92019370Spstvariable. 92119370Spst 92219370Spst@node Register Variables 92319370Spst@section Register Variables 92419370Spst 92519370Spst@findex N_RSYM 92619370Spst@findex C_RSYM 92719370Spst@c According to an old version of this manual, AIX uses C_RPSYM instead 92819370Spst@c of C_RSYM. I am skeptical; this should be verified. 92919370SpstRegister variables have their own stab type, @code{N_RSYM} 93019370Spst(@code{C_RSYM} for XCOFF), and their own symbol descriptor, @samp{r}. 93119370SpstThe stab's value is the number of the register where the variable data 93219370Spstwill be stored. 93319370Spst@c .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc) 93419370Spst 93519370SpstAIX defines a separate symbol descriptor @samp{d} for floating point 93619370Spstregisters. This seems unnecessary; why not just just give floating 93719370Spstpoint registers different register numbers? I have not verified whether 93819370Spstthe compiler actually uses @samp{d}. 93919370Spst 94019370SpstIf the register is explicitly allocated to a global variable, but not 94119370Spstinitialized, as in: 94219370Spst 94319370Spst@example 94419370Spstregister int g_bar asm ("%g5"); 94519370Spst@end example 94619370Spst 94719370Spst@noindent 94819370Spstthen the stab may be emitted at the end of the object file, with 94919370Spstthe other bss symbols. 95019370Spst 95119370Spst@node Common Blocks 95219370Spst@section Common Blocks 95319370Spst 95419370SpstA common block is a statically allocated section of memory which can be 95519370Spstreferred to by several source files. It may contain several variables. 95619370SpstI believe Fortran is the only language with this feature. 95719370Spst 95819370Spst@findex N_BCOMM 95919370Spst@findex N_ECOMM 96019370Spst@findex C_BCOMM 96119370Spst@findex C_ECOMM 96219370SpstA @code{N_BCOMM} stab begins a common block and an @code{N_ECOMM} stab 96319370Spstends it. The only field that is significant in these two stabs is the 96419370Spststring, which names a normal (non-debugging) symbol that gives the 96519370Spstaddress of the common block. According to IBM documentation, only the 96619370Spst@code{N_BCOMM} has the name of the common block (even though their 96719370Spstcompiler actually puts it both places). 96819370Spst 96919370Spst@findex N_ECOML 97019370Spst@findex C_ECOML 97119370SpstThe stabs for the members of the common block are between the 97219370Spst@code{N_BCOMM} and the @code{N_ECOMM}; the value of each stab is the 97319370Spstoffset within the common block of that variable. IBM uses the 97419370Spst@code{C_ECOML} stab type, and there is a corresponding @code{N_ECOML} 97519370Spststab type, but Sun's Fortran compiler uses @code{N_GSYM} instead. The 97619370Spstvariables within a common block use the @samp{V} symbol descriptor (I 97719370Spstbelieve this is true of all Fortran variables). Other stabs (at least 97819370Spsttype declarations using @code{C_DECL}) can also be between the 97919370Spst@code{N_BCOMM} and the @code{N_ECOMM}. 98019370Spst 98119370Spst@node Statics 98219370Spst@section Static Variables 98319370Spst 98419370SpstInitialized static variables are represented by the @samp{S} and 98519370Spst@samp{V} symbol descriptors. @samp{S} means file scope static, and 98619370Spst@samp{V} means procedure scope static. One exception: in XCOFF, IBM's 98719370Spstxlc compiler always uses @samp{V}, and whether it is file scope or not 98819370Spstis distinguished by whether the stab is located within a function. 98919370Spst 99019370Spst@c This is probably not worth mentioning; it is only true on the sparc 99119370Spst@c for `double' variables which although declared const are actually in 99219370Spst@c the data segment (the text segment can't guarantee 8 byte alignment). 99319370Spst@c (although GCC 99419370Spst@c 2.4.5 has a bug in that it uses @code{N_FUN}, so neither dbx nor GDB can 99519370Spst@c find the variables) 99619370Spst@findex N_STSYM 99719370Spst@findex N_LCSYM 99819370Spst@findex N_FUN, for variables 99919370Spst@findex N_ROSYM 100019370SpstIn a.out files, @code{N_STSYM} means the data section, @code{N_FUN} 100119370Spstmeans the text section, and @code{N_LCSYM} means the bss section. For 100219370Spstthose systems with a read-only data section separate from the text 100319370Spstsection (Solaris), @code{N_ROSYM} means the read-only data section. 100419370Spst 100519370SpstFor example, the source lines: 100619370Spst 100719370Spst@example 100819370Spststatic const int var_const = 5; 100919370Spststatic int var_init = 2; 101019370Spststatic int var_noinit; 101119370Spst@end example 101219370Spst 101319370Spst@noindent 101419370Spstyield the following stabs: 101519370Spst 101619370Spst@example 101719370Spst.stabs "var_const:S1",36,0,0,_var_const # @r{36 is N_FUN} 101819370Spst@dots{} 101919370Spst.stabs "var_init:S1",38,0,0,_var_init # @r{38 is N_STSYM} 102019370Spst@dots{} 102119370Spst.stabs "var_noinit:S1",40,0,0,_var_noinit # @r{40 is N_LCSYM} 102219370Spst@end example 102319370Spst 102419370Spst@findex C_STSYM 102519370Spst@findex C_BSTAT 102619370Spst@findex C_ESTAT 102719370SpstIn XCOFF files, the stab type need not indicate the section; 102819370Spst@code{C_STSYM} can be used for all statics. Also, each static variable 102919370Spstis enclosed in a static block. A @code{C_BSTAT} (emitted with a 103019370Spst@samp{.bs} assembler directive) symbol begins the static block; its 103119370Spstvalue is the symbol number of the csect symbol whose value is the 103219370Spstaddress of the static block, its section is the section of the variables 103319370Spstin that static block, and its name is @samp{.bs}. A @code{C_ESTAT} 103419370Spst(emitted with a @samp{.es} assembler directive) symbol ends the static 103519370Spstblock; its name is @samp{.es} and its value and section are ignored. 103619370Spst 103719370SpstIn ECOFF files, the storage class is used to specify the section, so the 103819370Spststab type need not indicate the section. 103919370Spst 104019370SpstIn ELF files, for the SunPRO compiler version 2.0.1, symbol descriptor 104119370Spst@samp{S} means that the address is absolute (the linker relocates it) 104219370Spstand symbol descriptor @samp{V} means that the address is relative to the 104319370Spststart of the relevant section for that compilation unit. SunPRO has 104419370Spstplans to have the linker stop relocating stabs; I suspect that their the 104519370Spstdebugger gets the address from the corresponding ELF (not stab) symbol. 104619370SpstI'm not sure how to find which symbol of that name is the right one. 104719370SpstThe clean way to do all this would be to have a the value of a symbol 104819370Spstdescriptor @samp{S} symbol be an offset relative to the start of the 104919370Spstfile, just like everything else, but that introduces obvious 105019370Spstcompatibility problems. For more information on linker stab relocation, 105119370Spst@xref{ELF Linker Relocation}. 105219370Spst 105319370Spst@node Based Variables 105419370Spst@section Fortran Based Variables 105519370Spst 105619370SpstFortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature 105719370Spstwhich allows allocating arrays with @code{malloc}, but which avoids 105819370Spstblurring the line between arrays and pointers the way that C does. In 105919370Spststabs such a variable uses the @samp{b} symbol descriptor. 106019370Spst 106119370SpstFor example, the Fortran declarations 106219370Spst 106319370Spst@example 106419370Spstreal foo, foo10(10), foo10_5(10,5) 106519370Spstpointer (foop, foo) 106619370Spstpointer (foo10p, foo10) 106719370Spstpointer (foo105p, foo10_5) 106819370Spst@end example 106919370Spst 107019370Spstproduce the stabs 107119370Spst 107219370Spst@example 107319370Spstfoo:b6 107419370Spstfoo10:bar3;1;10;6 107519370Spstfoo10_5:bar3;1;5;ar3;1;10;6 107619370Spst@end example 107719370Spst 107819370SpstIn this example, @code{real} is type 6 and type 3 is an integral type 107919370Spstwhich is the type of the subscripts of the array (probably 108019370Spst@code{integer}). 108119370Spst 108219370SpstThe @samp{b} symbol descriptor is like @samp{V} in that it denotes a 108319370Spststatically allocated symbol whose scope is local to a function; see 108419370Spst@xref{Statics}. The value of the symbol, instead of being the address 108519370Spstof the variable itself, is the address of a pointer to that variable. 108619370SpstSo in the above example, the value of the @code{foo} stab is the address 108719370Spstof a pointer to a real, the value of the @code{foo10} stab is the 108819370Spstaddress of a pointer to a 10-element array of reals, and the value of 108919370Spstthe @code{foo10_5} stab is the address of a pointer to a 5-element array 109019370Spstof 10-element arrays of reals. 109119370Spst 109219370Spst@node Parameters 109319370Spst@section Parameters 109419370Spst 109519370SpstFormal parameters to a function are represented by a stab (or sometimes 109619370Spsttwo; see below) for each parameter. The stabs are in the order in which 109719370Spstthe debugger should print the parameters (i.e., the order in which the 109819370Spstparameters are declared in the source file). The exact form of the stab 109919370Spstdepends on how the parameter is being passed. 110019370Spst 110119370Spst@findex N_PSYM 110219370Spst@findex C_PSYM 110319370SpstParameters passed on the stack use the symbol descriptor @samp{p} and 110419370Spstthe @code{N_PSYM} symbol type (or @code{C_PSYM} for XCOFF). The value 110519370Spstof the symbol is an offset used to locate the parameter on the stack; 110619370Spstits exact meaning is machine-dependent, but on most machines it is an 110719370Spstoffset from the frame pointer. 110819370Spst 110919370SpstAs a simple example, the code: 111019370Spst 111119370Spst@example 111219370Spstmain (argc, argv) 111319370Spst int argc; 111419370Spst char **argv; 111519370Spst@end example 111619370Spst 111719370Spstproduces the stabs: 111819370Spst 111919370Spst@example 112019370Spst.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} 112119370Spst.stabs "argc:p1",160,0,0,68 # @r{160 is N_PSYM} 112219370Spst.stabs "argv:p20=*21=*2",160,0,0,72 112319370Spst@end example 112419370Spst 112519370SpstThe type definition of @code{argv} is interesting because it contains 112619370Spstseveral type definitions. Type 21 is pointer to type 2 (char) and 112719370Spst@code{argv} (type 20) is pointer to type 21. 112819370Spst 112919370Spst@c FIXME: figure out what these mean and describe them coherently. 113019370SpstThe following symbol descriptors are also said to go with @code{N_PSYM}. 113119370SpstThe value of the symbol is said to be an offset from the argument 113219370Spstpointer (I'm not sure whether this is true or not). 113319370Spst 113419370Spst@example 113519370SpstpP (<<??>>) 113619370SpstpF Fortran function parameter 113719370SpstX (function result variable) 113819370Spst@end example 113919370Spst 114019370Spst@menu 114119370Spst* Register Parameters:: 114219370Spst* Local Variable Parameters:: 114319370Spst* Reference Parameters:: 114419370Spst* Conformant Arrays:: 114519370Spst@end menu 114619370Spst 114719370Spst@node Register Parameters 114819370Spst@subsection Passing Parameters in Registers 114919370Spst 115019370SpstIf the parameter is passed in a register, then traditionally there are 115119370Spsttwo symbols for each argument: 115219370Spst 115319370Spst@example 115419370Spst.stabs "arg:p1" . . . ; N_PSYM 115519370Spst.stabs "arg:r1" . . . ; N_RSYM 115619370Spst@end example 115719370Spst 115819370SpstDebuggers use the second one to find the value, and the first one to 115919370Spstknow that it is an argument. 116019370Spst 116119370Spst@findex C_RPSYM 116219370Spst@findex N_RSYM, for parameters 116319370SpstBecause that approach is kind of ugly, some compilers use symbol 116419370Spstdescriptor @samp{P} or @samp{R} to indicate an argument which is in a 116519370Spstregister. Symbol type @code{C_RPSYM} is used in XCOFF and @code{N_RSYM} 116619370Spstis used otherwise. The symbol's value is the register number. @samp{P} 116719370Spstand @samp{R} mean the same thing; the difference is that @samp{P} is a 116819370SpstGNU invention and @samp{R} is an IBM (XCOFF) invention. As of version 116919370Spst4.9, GDB should handle either one. 117019370Spst 117119370SpstThere is at least one case where GCC uses a @samp{p} and @samp{r} pair 117219370Spstrather than @samp{P}; this is where the argument is passed in the 117319370Spstargument list and then loaded into a register. 117419370Spst 117519370SpstAccording to the AIX documentation, symbol descriptor @samp{D} is for a 117619370Spstparameter passed in a floating point register. This seems 117719370Spstunnecessary---why not just use @samp{R} with a register number which 117819370Spstindicates that it's a floating point register? I haven't verified 117919370Spstwhether the system actually does what the documentation indicates. 118019370Spst 118119370Spst@c FIXME: On the hppa this is for any type > 8 bytes, I think, and not 118219370Spst@c for small structures (investigate). 118319370SpstOn the sparc and hppa, for a @samp{P} symbol whose type is a structure 118419370Spstor union, the register contains the address of the structure. On the 118519370Spstsparc, this is also true of a @samp{p} and @samp{r} pair (using Sun 118619370Spst@code{cc}) or a @samp{p} symbol. However, if a (small) structure is 118719370Spstreally in a register, @samp{r} is used. And, to top it all off, on the 118819370Spsthppa it might be a structure which was passed on the stack and loaded 118919370Spstinto a register and for which there is a @samp{p} and @samp{r} pair! I 119019370Spstbelieve that symbol descriptor @samp{i} is supposed to deal with this 119119370Spstcase (it is said to mean "value parameter by reference, indirect 119219370Spstaccess"; I don't know the source for this information), but I don't know 119319370Spstdetails or what compilers or debuggers use it, if any (not GDB or GCC). 119419370SpstIt is not clear to me whether this case needs to be dealt with 119519370Spstdifferently than parameters passed by reference (@pxref{Reference Parameters}). 119619370Spst 119719370Spst@node Local Variable Parameters 119819370Spst@subsection Storing Parameters as Local Variables 119919370Spst 120019370SpstThere is a case similar to an argument in a register, which is an 120119370Spstargument that is actually stored as a local variable. Sometimes this 120219370Spsthappens when the argument was passed in a register and then the compiler 120319370Spststores it as a local variable. If possible, the compiler should claim 120419370Spstthat it's in a register, but this isn't always done. 120519370Spst 120619370SpstIf a parameter is passed as one type and converted to a smaller type by 120719370Spstthe prologue (for example, the parameter is declared as a @code{float}, 120819370Spstbut the calling conventions specify that it is passed as a 120919370Spst@code{double}), then GCC2 (sometimes) uses a pair of symbols. The first 121019370Spstsymbol uses symbol descriptor @samp{p} and the type which is passed. 121119370SpstThe second symbol has the type and location which the parameter actually 121219370Spsthas after the prologue. For example, suppose the following C code 121319370Spstappears with no prototypes involved: 121419370Spst 121519370Spst@example 121619370Spstvoid 121719370Spstsubr (f) 121819370Spst float f; 121919370Spst@{ 122019370Spst@end example 122119370Spst 122219370Spstif @code{f} is passed as a double at stack offset 8, and the prologue 122319370Spstconverts it to a float in register number 0, then the stabs look like: 122419370Spst 122519370Spst@example 122619370Spst.stabs "f:p13",160,0,3,8 # @r{160 is @code{N_PSYM}, here 13 is @code{double}} 122719370Spst.stabs "f:r12",64,0,3,0 # @r{64 is @code{N_RSYM}, here 12 is @code{float}} 122819370Spst@end example 122919370Spst 123019370SpstIn both stabs 3 is the line number where @code{f} is declared 123119370Spst(@pxref{Line Numbers}). 123219370Spst 123319370Spst@findex N_LSYM, for parameter 123419370SpstGCC, at least on the 960, has another solution to the same problem. It 123519370Spstuses a single @samp{p} symbol descriptor for an argument which is stored 123619370Spstas a local variable but uses @code{N_LSYM} instead of @code{N_PSYM}. In 123719370Spstthis case, the value of the symbol is an offset relative to the local 123819370Spstvariables for that function, not relative to the arguments; on some 123919370Spstmachines those are the same thing, but not on all. 124019370Spst 124119370Spst@c This is mostly just background info; the part that logically belongs 124219370Spst@c here is the last sentence. 124319370SpstOn the VAX or on other machines in which the calling convention includes 124419370Spstthe number of words of arguments actually passed, the debugger (GDB at 124519370Spstleast) uses the parameter symbols to keep track of whether it needs to 124619370Spstprint nameless arguments in addition to the formal parameters which it 124719370Spsthas printed because each one has a stab. For example, in 124819370Spst 124919370Spst@example 125019370Spstextern int fprintf (FILE *stream, char *format, @dots{}); 125119370Spst@dots{} 125219370Spstfprintf (stdout, "%d\n", x); 125319370Spst@end example 125419370Spst 125519370Spstthere are stabs for @code{stream} and @code{format}. On most machines, 125619370Spstthe debugger can only print those two arguments (because it has no way 125719370Spstof knowing that additional arguments were passed), but on the VAX or 125819370Spstother machines with a calling convention which indicates the number of 125919370Spstwords of arguments, the debugger can print all three arguments. To do 126019370Spstso, the parameter symbol (symbol descriptor @samp{p}) (not necessarily 126119370Spst@samp{r} or symbol descriptor omitted symbols) needs to contain the 126219370Spstactual type as passed (for example, @code{double} not @code{float} if it 126319370Spstis passed as a double and converted to a float). 126419370Spst 126519370Spst@node Reference Parameters 126619370Spst@subsection Passing Parameters by Reference 126719370Spst 126819370SpstIf the parameter is passed by reference (e.g., Pascal @code{VAR} 126919370Spstparameters), then the symbol descriptor is @samp{v} if it is in the 127019370Spstargument list, or @samp{a} if it in a register. Other than the fact 127119370Spstthat these contain the address of the parameter rather than the 127219370Spstparameter itself, they are identical to @samp{p} and @samp{R}, 127319370Spstrespectively. I believe @samp{a} is an AIX invention; @samp{v} is 127419370Spstsupported by all stabs-using systems as far as I know. 127519370Spst 127619370Spst@node Conformant Arrays 127719370Spst@subsection Passing Conformant Array Parameters 127819370Spst 127919370Spst@c Is this paragraph correct? It is based on piecing together patchy 128019370Spst@c information and some guesswork 128119370SpstConformant arrays are a feature of Modula-2, and perhaps other 128219370Spstlanguages, in which the size of an array parameter is not known to the 128319370Spstcalled function until run-time. Such parameters have two stabs: a 128419370Spst@samp{x} for the array itself, and a @samp{C}, which represents the size 128519370Spstof the array. The value of the @samp{x} stab is the offset in the 128619370Spstargument list where the address of the array is stored (it this right? 128719370Spstit is a guess); the value of the @samp{C} stab is the offset in the 128819370Spstargument list where the size of the array (in elements? in bytes?) is 128919370Spststored. 129019370Spst 129119370Spst@node Types 129219370Spst@chapter Defining Types 129319370Spst 129419370SpstThe examples so far have described types as references to previously 129519370Spstdefined types, or defined in terms of subranges of or pointers to 129619370Spstpreviously defined types. This chapter describes the other type 129719370Spstdescriptors that may follow the @samp{=} in a type definition. 129819370Spst 129919370Spst@menu 130019370Spst* Builtin Types:: Integers, floating point, void, etc. 130119370Spst* Miscellaneous Types:: Pointers, sets, files, etc. 130219370Spst* Cross-References:: Referring to a type not yet defined. 130319370Spst* Subranges:: A type with a specific range. 130419370Spst* Arrays:: An aggregate type of same-typed elements. 130519370Spst* Strings:: Like an array but also has a length. 130619370Spst* Enumerations:: Like an integer but the values have names. 130719370Spst* Structures:: An aggregate type of different-typed elements. 130819370Spst* Typedefs:: Giving a type a name. 130919370Spst* Unions:: Different types sharing storage. 131019370Spst* Function Types:: 131119370Spst@end menu 131219370Spst 131319370Spst@node Builtin Types 131419370Spst@section Builtin Types 131519370Spst 131619370SpstCertain types are built in (@code{int}, @code{short}, @code{void}, 131719370Spst@code{float}, etc.); the debugger recognizes these types and knows how 131819370Spstto handle them. Thus, don't be surprised if some of the following ways 131919370Spstof specifying builtin types do not specify everything that a debugger 132019370Spstwould need to know about the type---in some cases they merely specify 132119370Spstenough information to distinguish the type from other types. 132219370Spst 132398948SobrienThe traditional way to define builtin types is convoluted, so new ways 132419370Spsthave been invented to describe them. Sun's @code{acc} uses special 132519370Spstbuiltin type descriptors (@samp{b} and @samp{R}), and IBM uses negative 132619370Spsttype numbers. GDB accepts all three ways, as of version 4.8; dbx just 132719370Spstaccepts the traditional builtin types and perhaps one of the other two 132819370Spstformats. The following sections describe each of these formats. 132919370Spst 133019370Spst@menu 133198948Sobrien* Traditional Builtin Types:: Put on your seat belts and prepare for kludgery 133219370Spst* Builtin Type Descriptors:: Builtin types with special type descriptors 133319370Spst* Negative Type Numbers:: Builtin types using negative type numbers 133419370Spst@end menu 133519370Spst 133619370Spst@node Traditional Builtin Types 133719370Spst@subsection Traditional Builtin Types 133819370Spst 133919370SpstThis is the traditional, convoluted method for defining builtin types. 134019370SpstThere are several classes of such type definitions: integer, floating 134119370Spstpoint, and @code{void}. 134219370Spst 134319370Spst@menu 134419370Spst* Traditional Integer Types:: 134519370Spst* Traditional Other Types:: 134619370Spst@end menu 134719370Spst 134819370Spst@node Traditional Integer Types 134919370Spst@subsubsection Traditional Integer Types 135019370Spst 135119370SpstOften types are defined as subranges of themselves. If the bounding values 135219370Spstfit within an @code{int}, then they are given normally. For example: 135319370Spst 135419370Spst@example 135519370Spst.stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 # @r{128 is N_LSYM} 135619370Spst.stabs "char:t2=r2;0;127;",128,0,0,0 135719370Spst@end example 135819370Spst 135919370SpstBuiltin types can also be described as subranges of @code{int}: 136019370Spst 136119370Spst@example 136219370Spst.stabs "unsigned short:t6=r1;0;65535;",128,0,0,0 136319370Spst@end example 136419370Spst 136519370SpstIf the lower bound of a subrange is 0 and the upper bound is -1, 136619370Spstthe type is an unsigned integral type whose bounds are too 136719370Spstbig to describe in an @code{int}. Traditionally this is only used for 136819370Spst@code{unsigned int} and @code{unsigned long}: 136919370Spst 137019370Spst@example 137119370Spst.stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 137219370Spst@end example 137319370Spst 137419370SpstFor larger types, GCC 2.4.5 puts out bounds in octal, with one or more 137519370Spstleading zeroes. In this case a negative bound consists of a number 137619370Spstwhich is a 1 bit (for the sign bit) followed by a 0 bit for each bit in 137719370Spstthe number (except the sign bit), and a positive bound is one which is a 137819370Spst1 bit for each bit in the number (except possibly the sign bit). All 137919370Spstknown versions of dbx and GDB version 4 accept this (at least in the 138019370Spstsense of not refusing to process the file), but GDB 3.5 refuses to read 138119370Spstthe whole file containing such symbols. So GCC 2.3.3 did not output the 138219370Spstproper size for these types. As an example of octal bounds, the string 138319370Spstfields of the stabs for 64 bit integer types look like: 138419370Spst 138519370Spst@c .stabs directives, etc., omitted to make it fit on the page. 138619370Spst@example 138719370Spstlong int:t3=r1;001000000000000000000000;000777777777777777777777; 138819370Spstlong unsigned int:t5=r1;000000000000000000000000;001777777777777777777777; 138919370Spst@end example 139019370Spst 139119370SpstIf the lower bound of a subrange is 0 and the upper bound is negative, 139219370Spstthe type is an unsigned integral type whose size in bytes is the 139319370Spstabsolute value of the upper bound. I believe this is a Convex 139419370Spstconvention for @code{unsigned long long}. 139519370Spst 139619370SpstIf the lower bound of a subrange is negative and the upper bound is 0, 139719370Spstthe type is a signed integral type whose size in bytes is 139819370Spstthe absolute value of the lower bound. I believe this is a Convex 139919370Spstconvention for @code{long long}. To distinguish this from a legitimate 140019370Spstsubrange, the type should be a subrange of itself. I'm not sure whether 140119370Spstthis is the case for Convex. 140219370Spst 140319370Spst@node Traditional Other Types 140419370Spst@subsubsection Traditional Other Types 140519370Spst 140619370SpstIf the upper bound of a subrange is 0 and the lower bound is positive, 140719370Spstthe type is a floating point type, and the lower bound of the subrange 140819370Spstindicates the number of bytes in the type: 140919370Spst 141019370Spst@example 141119370Spst.stabs "float:t12=r1;4;0;",128,0,0,0 141219370Spst.stabs "double:t13=r1;8;0;",128,0,0,0 141319370Spst@end example 141419370Spst 141519370SpstHowever, GCC writes @code{long double} the same way it writes 141619370Spst@code{double}, so there is no way to distinguish. 141719370Spst 141819370Spst@example 141919370Spst.stabs "long double:t14=r1;8;0;",128,0,0,0 142019370Spst@end example 142119370Spst 142219370SpstComplex types are defined the same way as floating-point types; there is 142319370Spstno way to distinguish a single-precision complex from a double-precision 142419370Spstfloating-point type. 142519370Spst 142619370SpstThe C @code{void} type is defined as itself: 142719370Spst 142819370Spst@example 142919370Spst.stabs "void:t15=15",128,0,0,0 143019370Spst@end example 143119370Spst 143219370SpstI'm not sure how a boolean type is represented. 143319370Spst 143419370Spst@node Builtin Type Descriptors 143519370Spst@subsection Defining Builtin Types Using Builtin Type Descriptors 143619370Spst 143719370SpstThis is the method used by Sun's @code{acc} for defining builtin types. 143819370SpstThese are the type descriptors to define builtin types: 143919370Spst 144019370Spst@table @code 144119370Spst@c FIXME: clean up description of width and offset, once we figure out 144219370Spst@c what they mean 144319370Spst@item b @var{signed} @var{char-flag} @var{width} ; @var{offset} ; @var{nbits} ; 144419370SpstDefine an integral type. @var{signed} is @samp{u} for unsigned or 144519370Spst@samp{s} for signed. @var{char-flag} is @samp{c} which indicates this 144619370Spstis a character type, or is omitted. I assume this is to distinguish an 144719370Spstintegral type from a character type of the same size, for example it 144819370Spstmight make sense to set it for the C type @code{wchar_t} so the debugger 144919370Spstcan print such variables differently (Solaris does not do this). Sun 145019370Spstsets it on the C types @code{signed char} and @code{unsigned char} which 145119370Spstarguably is wrong. @var{width} and @var{offset} appear to be for small 145219370Spstobjects stored in larger ones, for example a @code{short} in an 145319370Spst@code{int} register. @var{width} is normally the number of bytes in the 145419370Spsttype. @var{offset} seems to always be zero. @var{nbits} is the number 145519370Spstof bits in the type. 145619370Spst 145719370SpstNote that type descriptor @samp{b} used for builtin types conflicts with 145819370Spstits use for Pascal space types (@pxref{Miscellaneous Types}); they can 145919370Spstbe distinguished because the character following the type descriptor 146019370Spstwill be a digit, @samp{(}, or @samp{-} for a Pascal space type, or 146119370Spst@samp{u} or @samp{s} for a builtin type. 146219370Spst 146319370Spst@item w 146419370SpstDocumented by AIX to define a wide character type, but their compiler 146519370Spstactually uses negative type numbers (@pxref{Negative Type Numbers}). 146619370Spst 146719370Spst@item R @var{fp-type} ; @var{bytes} ; 146819370SpstDefine a floating point type. @var{fp-type} has one of the following values: 146919370Spst 147019370Spst@table @code 147119370Spst@item 1 (NF_SINGLE) 147219370SpstIEEE 32-bit (single precision) floating point format. 147319370Spst 147419370Spst@item 2 (NF_DOUBLE) 147519370SpstIEEE 64-bit (double precision) floating point format. 147619370Spst 147719370Spst@item 3 (NF_COMPLEX) 147819370Spst@item 4 (NF_COMPLEX16) 147919370Spst@item 5 (NF_COMPLEX32) 148019370Spst@c "GDB source" really means @file{include/aout/stab_gnu.h}, but trying 148119370Spst@c to put that here got an overfull hbox. 148219370SpstThese are for complex numbers. A comment in the GDB source describes 148319370Spstthem as Fortran @code{complex}, @code{double complex}, and 148419370Spst@code{complex*16}, respectively, but what does that mean? (i.e., Single 148598948Sobrienprecision? Double precision?). 148619370Spst 148719370Spst@item 6 (NF_LDOUBLE) 148819370SpstLong double. This should probably only be used for Sun format 148919370Spst@code{long double}, and new codes should be used for other floating 149019370Spstpoint formats (@code{NF_DOUBLE} can be used if a @code{long double} is 149119370Spstreally just an IEEE double, of course). 149219370Spst@end table 149319370Spst 149419370Spst@var{bytes} is the number of bytes occupied by the type. This allows a 149519370Spstdebugger to perform some operations with the type even if it doesn't 149619370Spstunderstand @var{fp-type}. 149719370Spst 149819370Spst@item g @var{type-information} ; @var{nbits} 149919370SpstDocumented by AIX to define a floating type, but their compiler actually 150019370Spstuses negative type numbers (@pxref{Negative Type Numbers}). 150119370Spst 150219370Spst@item c @var{type-information} ; @var{nbits} 150319370SpstDocumented by AIX to define a complex type, but their compiler actually 150419370Spstuses negative type numbers (@pxref{Negative Type Numbers}). 150519370Spst@end table 150619370Spst 150719370SpstThe C @code{void} type is defined as a signed integral type 0 bits long: 150819370Spst@example 150919370Spst.stabs "void:t19=bs0;0;0",128,0,0,0 151019370Spst@end example 151119370SpstThe Solaris compiler seems to omit the trailing semicolon in this case. 151219370SpstGetting sloppy in this way is not a swift move because if a type is 151319370Spstembedded in a more complex expression it is necessary to be able to tell 151419370Spstwhere it ends. 151519370Spst 151619370SpstI'm not sure how a boolean type is represented. 151719370Spst 151819370Spst@node Negative Type Numbers 151919370Spst@subsection Negative Type Numbers 152019370Spst 152119370SpstThis is the method used in XCOFF for defining builtin types. 152219370SpstSince the debugger knows about the builtin types anyway, the idea of 152319370Spstnegative type numbers is simply to give a special type number which 152419370Spstindicates the builtin type. There is no stab defining these types. 152519370Spst 152619370SpstThere are several subtle issues with negative type numbers. 152719370Spst 152819370SpstOne is the size of the type. A builtin type (for example the C types 152919370Spst@code{int} or @code{long}) might have different sizes depending on 153019370Spstcompiler options, the target architecture, the ABI, etc. This issue 153119370Spstdoesn't come up for IBM tools since (so far) they just target the 153219370SpstRS/6000; the sizes indicated below for each size are what the IBM 153319370SpstRS/6000 tools use. To deal with differing sizes, either define separate 153419370Spstnegative type numbers for each size (which works but requires changing 153519370Spstthe debugger, and, unless you get both AIX dbx and GDB to accept the 153619370Spstchange, introduces an incompatibility), or use a type attribute 153719370Spst(@pxref{String Field}) to define a new type with the appropriate size 153819370Spst(which merely requires a debugger which understands type attributes, 153919370Spstlike AIX dbx or GDB). For example, 154019370Spst 154119370Spst@example 154219370Spst.stabs "boolean:t10=@@s8;-16",128,0,0,0 154319370Spst@end example 154419370Spst 154519370Spstdefines an 8-bit boolean type, and 154619370Spst 154719370Spst@example 154819370Spst.stabs "boolean:t10=@@s64;-16",128,0,0,0 154919370Spst@end example 155019370Spst 155119370Spstdefines a 64-bit boolean type. 155219370Spst 155319370SpstA similar issue is the format of the type. This comes up most often for 155419370Spstfloating-point types, which could have various formats (particularly 155519370Spstextended doubles, which vary quite a bit even among IEEE systems). 155619370SpstAgain, it is best to define a new negative type number for each 155719370Spstdifferent format; changing the format based on the target system has 155819370Spstvarious problems. One such problem is that the Alpha has both VAX and 155919370SpstIEEE floating types. One can easily imagine one library using the VAX 156019370Spsttypes and another library in the same executable using the IEEE types. 156119370SpstAnother example is that the interpretation of whether a boolean is true 156219370Spstor false can be based on the least significant bit, most significant 156319370Spstbit, whether it is zero, etc., and different compilers (or different 156419370Spstoptions to the same compiler) might provide different kinds of boolean. 156519370Spst 156619370SpstThe last major issue is the names of the types. The name of a given 156719370Spsttype depends @emph{only} on the negative type number given; these do not 156819370Spstvary depending on the language, the target system, or anything else. 156919370SpstOne can always define separate type numbers---in the following list you 157019370Spstwill see for example separate @code{int} and @code{integer*4} types 157119370Spstwhich are identical except for the name. But compatibility can be 157219370Spstmaintained by not inventing new negative type numbers and instead just 157319370Spstdefining a new type with a new name. For example: 157419370Spst 157519370Spst@example 157619370Spst.stabs "CARDINAL:t10=-8",128,0,0,0 157719370Spst@end example 157819370Spst 157919370SpstHere is the list of negative type numbers. The phrase @dfn{integral 158019370Spsttype} is used to mean twos-complement (I strongly suspect that all 158119370Spstmachines which use stabs use twos-complement; most machines use 158219370Spsttwos-complement these days). 158319370Spst 158419370Spst@table @code 158519370Spst@item -1 158619370Spst@code{int}, 32 bit signed integral type. 158719370Spst 158819370Spst@item -2 158919370Spst@code{char}, 8 bit type holding a character. Both GDB and dbx on AIX 159019370Spsttreat this as signed. GCC uses this type whether @code{char} is signed 159119370Spstor not, which seems like a bad idea. The AIX compiler (@code{xlc}) seems to 159219370Spstavoid this type; it uses -5 instead for @code{char}. 159319370Spst 159419370Spst@item -3 159519370Spst@code{short}, 16 bit signed integral type. 159619370Spst 159719370Spst@item -4 159819370Spst@code{long}, 32 bit signed integral type. 159919370Spst 160019370Spst@item -5 160119370Spst@code{unsigned char}, 8 bit unsigned integral type. 160219370Spst 160319370Spst@item -6 160419370Spst@code{signed char}, 8 bit signed integral type. 160519370Spst 160619370Spst@item -7 160719370Spst@code{unsigned short}, 16 bit unsigned integral type. 160819370Spst 160919370Spst@item -8 161019370Spst@code{unsigned int}, 32 bit unsigned integral type. 161119370Spst 161219370Spst@item -9 161319370Spst@code{unsigned}, 32 bit unsigned integral type. 161419370Spst 161519370Spst@item -10 161619370Spst@code{unsigned long}, 32 bit unsigned integral type. 161719370Spst 161819370Spst@item -11 161919370Spst@code{void}, type indicating the lack of a value. 162019370Spst 162119370Spst@item -12 162219370Spst@code{float}, IEEE single precision. 162319370Spst 162419370Spst@item -13 162519370Spst@code{double}, IEEE double precision. 162619370Spst 162719370Spst@item -14 162819370Spst@code{long double}, IEEE double precision. The compiler claims the size 162919370Spstwill increase in a future release, and for binary compatibility you have 163019370Spstto avoid using @code{long double}. I hope when they increase it they 163119370Spstuse a new negative type number. 163219370Spst 163319370Spst@item -15 163419370Spst@code{integer}. 32 bit signed integral type. 163519370Spst 163619370Spst@item -16 163719370Spst@code{boolean}. 32 bit type. GDB and GCC assume that zero is false, 163819370Spstone is true, and other values have unspecified meaning. I hope this 163919370Spstagrees with how the IBM tools use the type. 164019370Spst 164119370Spst@item -17 164219370Spst@code{short real}. IEEE single precision. 164319370Spst 164419370Spst@item -18 164519370Spst@code{real}. IEEE double precision. 164619370Spst 164719370Spst@item -19 164819370Spst@code{stringptr}. @xref{Strings}. 164919370Spst 165019370Spst@item -20 165119370Spst@code{character}, 8 bit unsigned character type. 165219370Spst 165319370Spst@item -21 165419370Spst@code{logical*1}, 8 bit type. This Fortran type has a split 165519370Spstpersonality in that it is used for boolean variables, but can also be 165619370Spstused for unsigned integers. 0 is false, 1 is true, and other values are 165719370Spstnon-boolean. 165819370Spst 165919370Spst@item -22 166019370Spst@code{logical*2}, 16 bit type. This Fortran type has a split 166119370Spstpersonality in that it is used for boolean variables, but can also be 166219370Spstused for unsigned integers. 0 is false, 1 is true, and other values are 166319370Spstnon-boolean. 166419370Spst 166519370Spst@item -23 166619370Spst@code{logical*4}, 32 bit type. This Fortran type has a split 166719370Spstpersonality in that it is used for boolean variables, but can also be 166819370Spstused for unsigned integers. 0 is false, 1 is true, and other values are 166919370Spstnon-boolean. 167019370Spst 167119370Spst@item -24 167219370Spst@code{logical}, 32 bit type. This Fortran type has a split 167319370Spstpersonality in that it is used for boolean variables, but can also be 167419370Spstused for unsigned integers. 0 is false, 1 is true, and other values are 167519370Spstnon-boolean. 167619370Spst 167719370Spst@item -25 167819370Spst@code{complex}. A complex type consisting of two IEEE single-precision 167919370Spstfloating point values. 168019370Spst 168119370Spst@item -26 168219370Spst@code{complex}. A complex type consisting of two IEEE double-precision 168319370Spstfloating point values. 168419370Spst 168519370Spst@item -27 168619370Spst@code{integer*1}, 8 bit signed integral type. 168719370Spst 168819370Spst@item -28 168919370Spst@code{integer*2}, 16 bit signed integral type. 169019370Spst 169119370Spst@item -29 169219370Spst@code{integer*4}, 32 bit signed integral type. 169319370Spst 169419370Spst@item -30 169519370Spst@code{wchar}. Wide character, 16 bits wide, unsigned (what format? 169619370SpstUnicode?). 169719370Spst 169819370Spst@item -31 169919370Spst@code{long long}, 64 bit signed integral type. 170019370Spst 170119370Spst@item -32 170219370Spst@code{unsigned long long}, 64 bit unsigned integral type. 170319370Spst 170419370Spst@item -33 170519370Spst@code{logical*8}, 64 bit unsigned integral type. 170619370Spst 170719370Spst@item -34 170819370Spst@code{integer*8}, 64 bit signed integral type. 170919370Spst@end table 171019370Spst 171119370Spst@node Miscellaneous Types 171219370Spst@section Miscellaneous Types 171319370Spst 171419370Spst@table @code 171519370Spst@item b @var{type-information} ; @var{bytes} 171619370SpstPascal space type. This is documented by IBM; what does it mean? 171719370Spst 171819370SpstThis use of the @samp{b} type descriptor can be distinguished 171919370Spstfrom its use for builtin integral types (@pxref{Builtin Type 172019370SpstDescriptors}) because the character following the type descriptor is 172119370Spstalways a digit, @samp{(}, or @samp{-}. 172219370Spst 172319370Spst@item B @var{type-information} 172419370SpstA volatile-qualified version of @var{type-information}. This is 172519370Spsta Sun extension. References and stores to a variable with a 172619370Spstvolatile-qualified type must not be optimized or cached; they 172719370Spstmust occur as the user specifies them. 172819370Spst 172919370Spst@item d @var{type-information} 173019370SpstFile of type @var{type-information}. As far as I know this is only used 173119370Spstby Pascal. 173219370Spst 173319370Spst@item k @var{type-information} 173419370SpstA const-qualified version of @var{type-information}. This is a Sun 173519370Spstextension. A variable with a const-qualified type cannot be modified. 173619370Spst 173719370Spst@item M @var{type-information} ; @var{length} 173819370SpstMultiple instance type. The type seems to composed of @var{length} 173919370Spstrepetitions of @var{type-information}, for example @code{character*3} is 174019370Spstrepresented by @samp{M-2;3}, where @samp{-2} is a reference to a 174119370Spstcharacter type (@pxref{Negative Type Numbers}). I'm not sure how this 174219370Spstdiffers from an array. This appears to be a Fortran feature. 174319370Spst@var{length} is a bound, like those in range types; see @ref{Subranges}. 174419370Spst 174519370Spst@item S @var{type-information} 174619370SpstPascal set type. @var{type-information} must be a small type such as an 174719370Spstenumeration or a subrange, and the type is a bitmask whose length is 174819370Spstspecified by the number of elements in @var{type-information}. 174919370Spst 175019370SpstIn CHILL, if it is a bitstring instead of a set, also use the @samp{S} 175119370Spsttype attribute (@pxref{String Field}). 175219370Spst 175319370Spst@item * @var{type-information} 175419370SpstPointer to @var{type-information}. 175519370Spst@end table 175619370Spst 175719370Spst@node Cross-References 175819370Spst@section Cross-References to Other Types 175919370Spst 176019370SpstA type can be used before it is defined; one common way to deal with 176119370Spstthat situation is just to use a type reference to a type which has not 176219370Spstyet been defined. 176319370Spst 176419370SpstAnother way is with the @samp{x} type descriptor, which is followed by 176519370Spst@samp{s} for a structure tag, @samp{u} for a union tag, or @samp{e} for 176619370Spsta enumerator tag, followed by the name of the tag, followed by @samp{:}. 176719370SpstIf the name contains @samp{::} between a @samp{<} and @samp{>} pair (for 1768130809SmarcelC@t{++} templates), such a @samp{::} does not end the name---only a single 176919370Spst@samp{:} ends the name; see @ref{Nested Symbols}. 177019370Spst 177119370SpstFor example, the following C declarations: 177219370Spst 177319370Spst@example 177419370Spststruct foo; 177519370Spststruct foo *bar; 177619370Spst@end example 177719370Spst 177819370Spst@noindent 177919370Spstproduce: 178019370Spst 178119370Spst@example 178219370Spst.stabs "bar:G16=*17=xsfoo:",32,0,0,0 178319370Spst@end example 178419370Spst 178519370SpstNot all debuggers support the @samp{x} type descriptor, so on some 178619370Spstmachines GCC does not use it. I believe that for the above example it 178719370Spstwould just emit a reference to type 17 and never define it, but I 178819370Spsthaven't verified that. 178919370Spst 179019370SpstModula-2 imported types, at least on AIX, use the @samp{i} type 179119370Spstdescriptor, which is followed by the name of the module from which the 179219370Spsttype is imported, followed by @samp{:}, followed by the name of the 179319370Spsttype. There is then optionally a comma followed by type information for 179419370Spstthe type. This differs from merely naming the type (@pxref{Typedefs}) in 179519370Spstthat it identifies the module; I don't understand whether the name of 179619370Spstthe type given here is always just the same as the name we are giving 179719370Spstit, or whether this type descriptor is used with a nameless stab 179819370Spst(@pxref{String Field}), or what. The symbol ends with @samp{;}. 179919370Spst 180019370Spst@node Subranges 180119370Spst@section Subrange Types 180219370Spst 180319370SpstThe @samp{r} type descriptor defines a type as a subrange of another 180419370Spsttype. It is followed by type information for the type of which it is a 180519370Spstsubrange, a semicolon, an integral lower bound, a semicolon, an 180619370Spstintegral upper bound, and a semicolon. The AIX documentation does not 180719370Spstspecify the trailing semicolon, in an effort to specify array indexes 180819370Spstmore cleanly, but a subrange which is not an array index has always 180919370Spstincluded a trailing semicolon (@pxref{Arrays}). 181019370Spst 181119370SpstInstead of an integer, either bound can be one of the following: 181219370Spst 181319370Spst@table @code 181419370Spst@item A @var{offset} 181519370SpstThe bound is passed by reference on the stack at offset @var{offset} 181619370Spstfrom the argument list. @xref{Parameters}, for more information on such 181719370Spstoffsets. 181819370Spst 181919370Spst@item T @var{offset} 182019370SpstThe bound is passed by value on the stack at offset @var{offset} from 182119370Spstthe argument list. 182219370Spst 182319370Spst@item a @var{register-number} 182498948SobrienThe bound is passed by reference in register number 182519370Spst@var{register-number}. 182619370Spst 182719370Spst@item t @var{register-number} 182819370SpstThe bound is passed by value in register number @var{register-number}. 182919370Spst 183019370Spst@item J 183119370SpstThere is no bound. 183219370Spst@end table 183319370Spst 183419370SpstSubranges are also used for builtin types; see @ref{Traditional Builtin Types}. 183519370Spst 183619370Spst@node Arrays 183719370Spst@section Array Types 183819370Spst 183919370SpstArrays use the @samp{a} type descriptor. Following the type descriptor 184019370Spstis the type of the index and the type of the array elements. If the 184119370Spstindex type is a range type, it ends in a semicolon; otherwise 184219370Spst(for example, if it is a type reference), there does not 184319370Spstappear to be any way to tell where the types are separated. In an 184419370Spsteffort to clean up this mess, IBM documents the two types as being 184519370Spstseparated by a semicolon, and a range type as not ending in a semicolon 184619370Spst(but this is not right for range types which are not array indexes, 184719370Spst@pxref{Subranges}). I think probably the best solution is to specify 184819370Spstthat a semicolon ends a range type, and that the index type and element 184919370Spsttype of an array are separated by a semicolon, but that if the index 185019370Spsttype is a range type, the extra semicolon can be omitted. GDB (at least 185119370Spstthrough version 4.9) doesn't support any kind of index type other than a 185219370Spstrange anyway; I'm not sure about dbx. 185319370Spst 185419370SpstIt is well established, and widely used, that the type of the index, 185519370Spstunlike most types found in the stabs, is merely a type definition, not 185619370Spsttype information (@pxref{String Field}) (that is, it need not start with 185719370Spst@samp{@var{type-number}=} if it is defining a new type). According to a 185819370Spstcomment in GDB, this is also true of the type of the array elements; it 185919370Spstgives @samp{ar1;1;10;ar1;1;10;4} as a legitimate way to express a two 186019370Spstdimensional array. According to AIX documentation, the element type 186119370Spstmust be type information. GDB accepts either. 186219370Spst 186319370SpstThe type of the index is often a range type, expressed as the type 186419370Spstdescriptor @samp{r} and some parameters. It defines the size of the 186519370Spstarray. In the example below, the range @samp{r1;0;2;} defines an index 186619370Spsttype which is a subrange of type 1 (integer), with a lower bound of 0 186719370Spstand an upper bound of 2. This defines the valid range of subscripts of 186819370Spsta three-element C array. 186919370Spst 187019370SpstFor example, the definition: 187119370Spst 187219370Spst@example 187319370Spstchar char_vec[3] = @{'a','b','c'@}; 187419370Spst@end example 187519370Spst 187619370Spst@noindent 187719370Spstproduces the output: 187819370Spst 187919370Spst@example 188019370Spst.stabs "char_vec:G19=ar1;0;2;2",32,0,0,0 188119370Spst .global _char_vec 188219370Spst .align 4 188319370Spst_char_vec: 188419370Spst .byte 97 188519370Spst .byte 98 188619370Spst .byte 99 188719370Spst@end example 188819370Spst 188919370SpstIf an array is @dfn{packed}, the elements are spaced more 189019370Spstclosely than normal, saving memory at the expense of speed. For 189119370Spstexample, an array of 3-byte objects might, if unpacked, have each 189219370Spstelement aligned on a 4-byte boundary, but if packed, have no padding. 189319370SpstOne way to specify that something is packed is with type attributes 189419370Spst(@pxref{String Field}). In the case of arrays, another is to use the 189519370Spst@samp{P} type descriptor instead of @samp{a}. Other than specifying a 189619370Spstpacked array, @samp{P} is identical to @samp{a}. 189719370Spst 189819370Spst@c FIXME-what is it? A pointer? 189919370SpstAn open array is represented by the @samp{A} type descriptor followed by 190019370Spsttype information specifying the type of the array elements. 190119370Spst 190219370Spst@c FIXME: what is the format of this type? A pointer to a vector of pointers? 190319370SpstAn N-dimensional dynamic array is represented by 190419370Spst 190519370Spst@example 190619370SpstD @var{dimensions} ; @var{type-information} 190719370Spst@end example 190819370Spst 190919370Spst@c Does dimensions really have this meaning? The AIX documentation 191019370Spst@c doesn't say. 191119370Spst@var{dimensions} is the number of dimensions; @var{type-information} 191219370Spstspecifies the type of the array elements. 191319370Spst 191419370Spst@c FIXME: what is the format of this type? A pointer to some offsets in 191519370Spst@c another array? 191619370SpstA subarray of an N-dimensional array is represented by 191719370Spst 191819370Spst@example 191919370SpstE @var{dimensions} ; @var{type-information} 192019370Spst@end example 192119370Spst 192219370Spst@c Does dimensions really have this meaning? The AIX documentation 192319370Spst@c doesn't say. 192419370Spst@var{dimensions} is the number of dimensions; @var{type-information} 192519370Spstspecifies the type of the array elements. 192619370Spst 192719370Spst@node Strings 192819370Spst@section Strings 192919370Spst 193019370SpstSome languages, like C or the original Pascal, do not have string types, 193119370Spstthey just have related things like arrays of characters. But most 193219370SpstPascals and various other languages have string types, which are 193319370Spstindicated as follows: 193419370Spst 193519370Spst@table @code 193619370Spst@item n @var{type-information} ; @var{bytes} 193719370Spst@var{bytes} is the maximum length. I'm not sure what 193819370Spst@var{type-information} is; I suspect that it means that this is a string 193919370Spstof @var{type-information} (thus allowing a string of integers, a string 194019370Spstof wide characters, etc., as well as a string of characters). Not sure 194119370Spstwhat the format of this type is. This is an AIX feature. 194219370Spst 194319370Spst@item z @var{type-information} ; @var{bytes} 194419370SpstJust like @samp{n} except that this is a gstring, not an ordinary 194519370Spststring. I don't know the difference. 194619370Spst 194719370Spst@item N 194819370SpstPascal Stringptr. What is this? This is an AIX feature. 194919370Spst@end table 195019370Spst 195119370SpstLanguages, such as CHILL which have a string type which is basically 195219370Spstjust an array of characters use the @samp{S} type attribute 195319370Spst(@pxref{String Field}). 195419370Spst 195519370Spst@node Enumerations 195619370Spst@section Enumerations 195719370Spst 195819370SpstEnumerations are defined with the @samp{e} type descriptor. 195919370Spst 196019370Spst@c FIXME: Where does this information properly go? Perhaps it is 196119370Spst@c redundant with something we already explain. 196219370SpstThe source line below declares an enumeration type at file scope. 196319370SpstThe type definition is located after the @code{N_RBRAC} that marks the end of 196419370Spstthe previous procedure's block scope, and before the @code{N_FUN} that marks 196519370Spstthe beginning of the next procedure's block scope. Therefore it does not 196619370Spstdescribe a block local symbol, but a file local one. 196719370Spst 196819370SpstThe source line: 196919370Spst 197019370Spst@example 197119370Spstenum e_places @{first,second=3,last@}; 197219370Spst@end example 197319370Spst 197419370Spst@noindent 197519370Spstgenerates the following stab: 197619370Spst 197719370Spst@example 197819370Spst.stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0 197919370Spst@end example 198019370Spst 198119370SpstThe symbol descriptor (@samp{T}) says that the stab describes a 198219370Spststructure, enumeration, or union tag. The type descriptor @samp{e}, 198319370Spstfollowing the @samp{22=} of the type definition narrows it down to an 198419370Spstenumeration type. Following the @samp{e} is a list of the elements of 198519370Spstthe enumeration. The format is @samp{@var{name}:@var{value},}. The 198619370Spstlist of elements ends with @samp{;}. The fact that @var{value} is 198719370Spstspecified as an integer can cause problems if the value is large. GCC 198819370Spst2.5.2 tries to output it in octal in that case with a leading zero, 198919370Spstwhich is probably a good thing, although GDB 4.11 supports octal only in 199019370Spstcases where decimal is perfectly good. Negative decimal values are 199119370Spstsupported by both GDB and dbx. 199219370Spst 199319370SpstThere is no standard way to specify the size of an enumeration type; it 199419370Spstis determined by the architecture (normally all enumerations types are 199519370Spst32 bits). Type attributes can be used to specify an enumeration type of 199619370Spstanother size for debuggers which support them; see @ref{String Field}. 199719370Spst 199819370SpstEnumeration types are unusual in that they define symbols for the 199919370Spstenumeration values (@code{first}, @code{second}, and @code{third} in the 200019370Spstabove example), and even though these symbols are visible in the file as 200119370Spsta whole (rather than being in a more local namespace like structure 200219370Spstmember names), they are defined in the type definition for the 200319370Spstenumeration type rather than each having their own symbol. In order to 200419370Spstbe fast, GDB will only get symbols from such types (in its initial scan 200519370Spstof the stabs) if the type is the first thing defined after a @samp{T} or 200619370Spst@samp{t} symbol descriptor (the above example fulfills this 200719370Spstrequirement). If the type does not have a name, the compiler should 200819370Spstemit it in a nameless stab (@pxref{String Field}); GCC does this. 200919370Spst 201019370Spst@node Structures 201119370Spst@section Structures 201219370Spst 201319370SpstThe encoding of structures in stabs can be shown with an example. 201419370Spst 201519370SpstThe following source code declares a structure tag and defines an 201619370Spstinstance of the structure in global scope. Then a @code{typedef} equates the 201798948Sobrienstructure tag with a new type. Separate stabs are generated for the 201819370Spststructure tag, the structure @code{typedef}, and the structure instance. The 201998948Sobrienstabs for the tag and the @code{typedef} are emitted when the definitions are 202019370Spstencountered. Since the structure elements are not initialized, the 202119370Spststab and code for the structure variable itself is located at the end 202219370Spstof the program in the bss section. 202319370Spst 202419370Spst@example 202519370Spststruct s_tag @{ 202619370Spst int s_int; 202719370Spst float s_float; 202819370Spst char s_char_vec[8]; 202919370Spst struct s_tag* s_next; 203019370Spst@} g_an_s; 203119370Spst 203219370Spsttypedef struct s_tag s_typedef; 203319370Spst@end example 203419370Spst 203519370SpstThe structure tag has an @code{N_LSYM} stab type because, like the 203619370Spstenumeration, the symbol has file scope. Like the enumeration, the 203719370Spstsymbol descriptor is @samp{T}, for enumeration, structure, or tag type. 203819370SpstThe type descriptor @samp{s} following the @samp{16=} of the type 203919370Spstdefinition narrows the symbol type to structure. 204019370Spst 204119370SpstFollowing the @samp{s} type descriptor is the number of bytes the 204219370Spststructure occupies, followed by a description of each structure element. 2043130809SmarcelThe structure element descriptions are of the form 2044130809Smarcel@samp{@var{name}:@var{type}, @var{bit offset from the start of the 2045130809Smarcelstruct}, @var{number of bits in the element}}. 204619370Spst 204719370Spst@c FIXME: phony line break. Can probably be fixed by using an example 204819370Spst@c with fewer fields. 204919370Spst@example 205019370Spst# @r{128 is N_LSYM} 205119370Spst.stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32; 205219370Spst s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0 205319370Spst@end example 205419370Spst 205519370SpstIn this example, the first two structure elements are previously defined 205619370Spsttypes. For these, the type following the @samp{@var{name}:} part of the 205719370Spstelement description is a simple type reference. The other two structure 205819370Spstelements are new types. In this case there is a type definition 205919370Spstembedded after the @samp{@var{name}:}. The type definition for the 206098948Sobrienarray element looks just like a type definition for a stand-alone array. 206119370SpstThe @code{s_next} field is a pointer to the same kind of structure that 206219370Spstthe field is an element of. So the definition of structure type 16 206319370Spstcontains a type definition for an element which is a pointer to type 16. 206419370Spst 2065130809SmarcelIf a field is a static member (this is a C@t{++} feature in which a single 206619370Spstvariable appears to be a field of every structure of a given type) it 206719370Spststill starts out with the field name, a colon, and the type, but then 206819370Spstinstead of a comma, bit position, comma, and bit size, there is a colon 206919370Spstfollowed by the name of the variable which each such field refers to. 207019370Spst 2071130809SmarcelIf the structure has methods (a C@t{++} feature), they follow the non-method 207219370Spstfields; see @ref{Cplusplus}. 207319370Spst 207419370Spst@node Typedefs 207519370Spst@section Giving a Type a Name 207619370Spst 207719370Spst@findex N_LSYM, for types 207819370Spst@findex C_DECL, for types 207919370SpstTo give a type a name, use the @samp{t} symbol descriptor. The type 208019370Spstis specified by the type information (@pxref{String Field}) for the stab. 208119370SpstFor example, 208219370Spst 208319370Spst@example 208419370Spst.stabs "s_typedef:t16",128,0,0,0 # @r{128 is N_LSYM} 208519370Spst@end example 208619370Spst 208719370Spstspecifies that @code{s_typedef} refers to type number 16. Such stabs 208846289Sdfrhave symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF). (The Sun 208946289Sdfrdocumentation mentions using @code{N_GSYM} in some cases). 209019370Spst 209119370SpstIf you are specifying the tag name for a structure, union, or 209219370Spstenumeration, use the @samp{T} symbol descriptor instead. I believe C is 209319370Spstthe only language with this feature. 209419370Spst 209519370SpstIf the type is an opaque type (I believe this is a Modula-2 feature), 209619370SpstAIX provides a type descriptor to specify it. The type descriptor is 209719370Spst@samp{o} and is followed by a name. I don't know what the name 209819370Spstmeans---is it always the same as the name of the type, or is this type 209919370Spstdescriptor used with a nameless stab (@pxref{String Field})? There 210019370Spstoptionally follows a comma followed by type information which defines 210119370Spstthe type of this type. If omitted, a semicolon is used in place of the 210219370Spstcomma and the type information, and the type is much like a generic 210319370Spstpointer type---it has a known size but little else about it is 210419370Spstspecified. 210519370Spst 210619370Spst@node Unions 210719370Spst@section Unions 210819370Spst 210919370Spst@example 211019370Spstunion u_tag @{ 211119370Spst int u_int; 211219370Spst float u_float; 211319370Spst char* u_char; 211419370Spst@} an_u; 211519370Spst@end example 211619370Spst 211719370SpstThis code generates a stab for a union tag and a stab for a union 211819370Spstvariable. Both use the @code{N_LSYM} stab type. If a union variable is 211919370Spstscoped locally to the procedure in which it is defined, its stab is 212019370Spstlocated immediately preceding the @code{N_LBRAC} for the procedure's block 212119370Spststart. 212219370Spst 212319370SpstThe stab for the union tag, however, is located preceding the code for 212419370Spstthe procedure in which it is defined. The stab type is @code{N_LSYM}. This 212519370Spstwould seem to imply that the union type is file scope, like the struct 212619370Spsttype @code{s_tag}. This is not true. The contents and position of the stab 212798948Sobrienfor @code{u_type} do not convey any information about its procedure local 212819370Spstscope. 212919370Spst 213019370Spst@c FIXME: phony line break. Can probably be fixed by using an example 213119370Spst@c with fewer fields. 213219370Spst@smallexample 213319370Spst# @r{128 is N_LSYM} 213419370Spst.stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;", 213519370Spst 128,0,0,0 213619370Spst@end smallexample 213719370Spst 213819370SpstThe symbol descriptor @samp{T}, following the @samp{name:} means that 213919370Spstthe stab describes an enumeration, structure, or union tag. The type 214019370Spstdescriptor @samp{u}, following the @samp{23=} of the type definition, 214119370Spstnarrows it down to a union type definition. Following the @samp{u} is 214219370Spstthe number of bytes in the union. After that is a list of union element 2143130809Smarceldescriptions. Their format is @samp{@var{name}:@var{type}, @var{bit 2144130809Smarceloffset into the union}, @var{number of bytes for the element};}. 214519370Spst 214619370SpstThe stab for the union variable is: 214719370Spst 214819370Spst@example 214919370Spst.stabs "an_u:23",128,0,0,-20 # @r{128 is N_LSYM} 215019370Spst@end example 215119370Spst 215219370Spst@samp{-20} specifies where the variable is stored (@pxref{Stack 215319370SpstVariables}). 215419370Spst 215519370Spst@node Function Types 215619370Spst@section Function Types 215719370Spst 215819370SpstVarious types can be defined for function variables. These types are 215919370Spstnot used in defining functions (@pxref{Procedures}); they are used for 216019370Spstthings like pointers to functions. 216119370Spst 216219370SpstThe simple, traditional, type is type descriptor @samp{f} is followed by 216319370Spsttype information for the return type of the function, followed by a 216419370Spstsemicolon. 216519370Spst 216619370SpstThis does not deal with functions for which the number and types of the 216719370Spstparameters are part of the type, as in Modula-2 or ANSI C. AIX provides 216819370Spstextensions to specify these, using the @samp{f}, @samp{F}, @samp{p}, and 216919370Spst@samp{R} type descriptors. 217019370Spst 217119370SpstFirst comes the type descriptor. If it is @samp{f} or @samp{F}, this 217219370Spsttype involves a function rather than a procedure, and the type 217319370Spstinformation for the return type of the function follows, followed by a 217419370Spstcomma. Then comes the number of parameters to the function and a 217519370Spstsemicolon. Then, for each parameter, there is the name of the parameter 217619370Spstfollowed by a colon (this is only present for type descriptors @samp{R} 217719370Spstand @samp{F} which represent Pascal function or procedure parameters), 217819370Spsttype information for the parameter, a comma, 0 if passed by reference or 217919370Spst1 if passed by value, and a semicolon. The type definition ends with a 218019370Spstsemicolon. 218119370Spst 218219370SpstFor example, this variable definition: 218319370Spst 218419370Spst@example 218519370Spstint (*g_pf)(); 218619370Spst@end example 218719370Spst 218819370Spst@noindent 218919370Spstgenerates the following code: 219019370Spst 219119370Spst@example 219219370Spst.stabs "g_pf:G24=*25=f1",32,0,0,0 219319370Spst .common _g_pf,4,"bss" 219419370Spst@end example 219519370Spst 219619370SpstThe variable defines a new type, 24, which is a pointer to another new 219719370Spsttype, 25, which is a function returning @code{int}. 219819370Spst 219919370Spst@node Symbol Tables 220019370Spst@chapter Symbol Information in Symbol Tables 220119370Spst 220219370SpstThis chapter describes the format of symbol table entries 220319370Spstand how stab assembler directives map to them. It also describes the 220419370Spsttransformations that the assembler and linker make on data from stabs. 220519370Spst 220619370Spst@menu 220719370Spst* Symbol Table Format:: 220819370Spst* Transformations On Symbol Tables:: 220919370Spst@end menu 221019370Spst 221119370Spst@node Symbol Table Format 221219370Spst@section Symbol Table Format 221319370Spst 221419370SpstEach time the assembler encounters a stab directive, it puts 221519370Spsteach field of the stab into a corresponding field in a symbol table 221619370Spstentry of its output file. If the stab contains a string field, the 221719370Spstsymbol table entry for that stab points to a string table entry 221819370Spstcontaining the string data from the stab. Assembler labels become 221919370Spstrelocatable addresses. Symbol table entries in a.out have the format: 222019370Spst 222119370Spst@c FIXME: should refer to external, not internal. 222219370Spst@example 222319370Spststruct internal_nlist @{ 222419370Spst unsigned long n_strx; /* index into string table of name */ 222519370Spst unsigned char n_type; /* type of symbol */ 222619370Spst unsigned char n_other; /* misc info (usually empty) */ 222719370Spst unsigned short n_desc; /* description field */ 222819370Spst bfd_vma n_value; /* value of symbol */ 222919370Spst@}; 223019370Spst@end example 223119370Spst 223219370SpstIf the stab has a string, the @code{n_strx} field holds the offset in 223319370Spstbytes of the string within the string table. The string is terminated 223419370Spstby a NUL character. If the stab lacks a string (for example, it was 223519370Spstproduced by a @code{.stabn} or @code{.stabd} directive), the 223619370Spst@code{n_strx} field is zero. 223719370Spst 223819370SpstSymbol table entries with @code{n_type} field values greater than 0x1f 223919370Spstoriginated as stabs generated by the compiler (with one random 224019370Spstexception). The other entries were placed in the symbol table of the 224119370Spstexecutable by the assembler or the linker. 224219370Spst 224319370Spst@node Transformations On Symbol Tables 224419370Spst@section Transformations on Symbol Tables 224519370Spst 224619370SpstThe linker concatenates object files and does fixups of externally 224719370Spstdefined symbols. 224819370Spst 224919370SpstYou can see the transformations made on stab data by the assembler and 225019370Spstlinker by examining the symbol table after each pass of the build. To 225119370Spstdo this, use @samp{nm -ap}, which dumps the symbol table, including 225219370Spstdebugging information, unsorted. For stab entries the columns are: 225319370Spst@var{value}, @var{other}, @var{desc}, @var{type}, @var{string}. For 225419370Spstassembler and linker symbols, the columns are: @var{value}, @var{type}, 225519370Spst@var{string}. 225619370Spst 225719370SpstThe low 5 bits of the stab type tell the linker how to relocate the 225819370Spstvalue of the stab. Thus for stab types like @code{N_RSYM} and 225919370Spst@code{N_LSYM}, where the value is an offset or a register number, the 226019370Spstlow 5 bits are @code{N_ABS}, which tells the linker not to relocate the 226119370Spstvalue. 226219370Spst 226319370SpstWhere the value of a stab contains an assembly language label, 226419370Spstit is transformed by each build step. The assembler turns it into a 226519370Spstrelocatable address and the linker turns it into an absolute address. 226619370Spst 226719370Spst@menu 226819370Spst* Transformations On Static Variables:: 226919370Spst* Transformations On Global Variables:: 227019370Spst* Stab Section Transformations:: For some object file formats, 227119370Spst things are a bit different. 227219370Spst@end menu 227319370Spst 227419370Spst@node Transformations On Static Variables 227519370Spst@subsection Transformations on Static Variables 227619370Spst 227719370SpstThis source line defines a static variable at file scope: 227819370Spst 227919370Spst@example 228019370Spststatic int s_g_repeat 228119370Spst@end example 228219370Spst 228319370Spst@noindent 228419370SpstThe following stab describes the symbol: 228519370Spst 228619370Spst@example 228719370Spst.stabs "s_g_repeat:S1",38,0,0,_s_g_repeat 228819370Spst@end example 228919370Spst 229019370Spst@noindent 229119370SpstThe assembler transforms the stab into this symbol table entry in the 229219370Spst@file{.o} file. The location is expressed as a data segment offset. 229319370Spst 229419370Spst@example 229519370Spst00000084 - 00 0000 STSYM s_g_repeat:S1 229619370Spst@end example 229719370Spst 229819370Spst@noindent 229919370SpstIn the symbol table entry from the executable, the linker has made the 230019370Spstrelocatable address absolute. 230119370Spst 230219370Spst@example 230319370Spst0000e00c - 00 0000 STSYM s_g_repeat:S1 230419370Spst@end example 230519370Spst 230619370Spst@node Transformations On Global Variables 230719370Spst@subsection Transformations on Global Variables 230819370Spst 230919370SpstStabs for global variables do not contain location information. In 231019370Spstthis case, the debugger finds location information in the assembler or 231119370Spstlinker symbol table entry describing the variable. The source line: 231219370Spst 231319370Spst@example 231419370Spstchar g_foo = 'c'; 231519370Spst@end example 231619370Spst 231719370Spst@noindent 231819370Spstgenerates the stab: 231919370Spst 232019370Spst@example 232119370Spst.stabs "g_foo:G2",32,0,0,0 232219370Spst@end example 232319370Spst 232419370SpstThe variable is represented by two symbol table entries in the object 232519370Spstfile (see below). The first one originated as a stab. The second one 232619370Spstis an external symbol. The upper case @samp{D} signifies that the 232719370Spst@code{n_type} field of the symbol table contains 7, @code{N_DATA} with 232819370Spstlocal linkage. The stab's value is zero since the value is not used for 232919370Spst@code{N_GSYM} stabs. The value of the linker symbol is the relocatable 233019370Spstaddress corresponding to the variable. 233119370Spst 233219370Spst@example 233319370Spst00000000 - 00 0000 GSYM g_foo:G2 233419370Spst00000080 D _g_foo 233519370Spst@end example 233619370Spst 233719370Spst@noindent 233819370SpstThese entries as transformed by the linker. The linker symbol table 233919370Spstentry now holds an absolute address: 234019370Spst 234119370Spst@example 234219370Spst00000000 - 00 0000 GSYM g_foo:G2 234319370Spst@dots{} 234419370Spst0000e008 D _g_foo 234519370Spst@end example 234619370Spst 234719370Spst@node Stab Section Transformations 234819370Spst@subsection Transformations of Stabs in separate sections 234919370Spst 235019370SpstFor object file formats using stabs in separate sections (@pxref{Stab 235119370SpstSections}), use @code{objdump --stabs} instead of @code{nm} to show the 235219370Spststabs in an object or executable file. @code{objdump} is a GNU utility; 235319370SpstSun does not provide any equivalent. 235419370Spst 235519370SpstThe following example is for a stab whose value is an address is 235619370Spstrelative to the compilation unit (@pxref{ELF Linker Relocation}). For 235719370Spstexample, if the source line 235819370Spst 235919370Spst@example 236019370Spststatic int ld = 5; 236119370Spst@end example 236219370Spst 236319370Spstappears within a function, then the assembly language output from the 236419370Spstcompiler contains: 236519370Spst 236619370Spst@example 236719370Spst.Ddata.data: 236819370Spst@dots{} 236919370Spst .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data # @r{0x26 is N_STSYM} 237019370Spst@dots{} 237119370Spst.L18: 237219370Spst .align 4 237319370Spst .word 0x5 237419370Spst@end example 237519370Spst 237619370SpstBecause the value is formed by subtracting one symbol from another, the 237719370Spstvalue is absolute, not relocatable, and so the object file contains 237819370Spst 237919370Spst@example 238019370SpstSymnum n_type n_othr n_desc n_value n_strx String 238119370Spst31 STSYM 0 4 00000004 680 ld:V(0,3) 238219370Spst@end example 238319370Spst 238419370Spstwithout any relocations, and the executable file also contains 238519370Spst 238619370Spst@example 238719370SpstSymnum n_type n_othr n_desc n_value n_strx String 238819370Spst31 STSYM 0 4 00000004 680 ld:V(0,3) 238919370Spst@end example 239019370Spst 239119370Spst@node Cplusplus 2392130809Smarcel@chapter GNU C@t{++} Stabs 239319370Spst 239419370Spst@menu 239519370Spst* Class Names:: C++ class names are both tags and typedefs. 239619370Spst* Nested Symbols:: C++ symbol names can be within other types. 239719370Spst* Basic Cplusplus Types:: 239819370Spst* Simple Classes:: 239919370Spst* Class Instance:: 240019370Spst* Methods:: Method definition 240119370Spst* Method Type Descriptor:: The @samp{#} type descriptor 240219370Spst* Member Type Descriptor:: The @samp{@@} type descriptor 240319370Spst* Protections:: 240419370Spst* Method Modifiers:: 240519370Spst* Virtual Methods:: 240698948Sobrien* Inheritance:: 240719370Spst* Virtual Base Classes:: 240819370Spst* Static Members:: 240919370Spst@end menu 241019370Spst 241119370Spst@node Class Names 2412130809Smarcel@section C@t{++} Class Names 241319370Spst 2414130809SmarcelIn C@t{++}, a class name which is declared with @code{class}, @code{struct}, 241519370Spstor @code{union}, is not only a tag, as in C, but also a type name. Thus 241619370Spstthere should be stabs with both @samp{t} and @samp{T} symbol descriptors 241719370Spst(@pxref{Typedefs}). 241819370Spst 241919370SpstTo save space, there is a special abbreviation for this case. If the 242019370Spst@samp{T} symbol descriptor is followed by @samp{t}, then the stab 242119370Spstdefines both a type name and a tag. 242219370Spst 2423130809SmarcelFor example, the C@t{++} code 242419370Spst 242519370Spst@example 242619370Spststruct foo @{int x;@}; 242719370Spst@end example 242819370Spst 242919370Spstcan be represented as either 243019370Spst 243119370Spst@example 243219370Spst.stabs "foo:T19=s4x:1,0,32;;",128,0,0,0 # @r{128 is N_LSYM} 243319370Spst.stabs "foo:t19",128,0,0,0 243419370Spst@end example 243519370Spst 243619370Spstor 243719370Spst 243819370Spst@example 243919370Spst.stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0 244019370Spst@end example 244119370Spst 244219370Spst@node Nested Symbols 244319370Spst@section Defining a Symbol Within Another Type 244419370Spst 2445130809SmarcelIn C@t{++}, a symbol (such as a type name) can be defined within another type. 244619370Spst@c FIXME: Needs example. 244719370Spst 244819370SpstIn stabs, this is sometimes represented by making the name of a symbol 244919370Spstwhich contains @samp{::}. Such a pair of colons does not end the name 245019370Spstof the symbol, the way a single colon would (@pxref{String Field}). I'm 245119370Spstnot sure how consistently used or well thought out this mechanism is. 245219370SpstSo that a pair of colons in this position always has this meaning, 245319370Spst@samp{:} cannot be used as a symbol descriptor. 245419370Spst 245519370SpstFor example, if the string for a stab is @samp{foo::bar::baz:t5=*6}, 245619370Spstthen @code{foo::bar::baz} is the name of the symbol, @samp{t} is the 245719370Spstsymbol descriptor, and @samp{5=*6} is the type information. 245819370Spst 245919370Spst@node Basic Cplusplus Types 2460130809Smarcel@section Basic Types For C@t{++} 246119370Spst 246219370Spst<< the examples that follow are based on a01.C >> 246319370Spst 246419370Spst 2465130809SmarcelC@t{++} adds two more builtin types to the set defined for C. These are 246619370Spstthe unknown type and the vtable record type. The unknown type, type 246719370Spst16, is defined in terms of itself like the void type. 246819370Spst 246919370SpstThe vtable record type, type 17, is defined as a structure type and 247019370Spstthen as a structure tag. The structure has four fields: delta, index, 247119370Spstpfn, and delta2. pfn is the function pointer. 247219370Spst 247319370Spst<< In boilerplate $vtbl_ptr_type, what are the fields delta, 247419370Spstindex, and delta2 used for? >> 247519370Spst 2476130809SmarcelThis basic type is present in all C@t{++} programs even if there are no 247719370Spstvirtual methods defined. 247819370Spst 247919370Spst@display 248019370Spst.stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8) 248119370Spst elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16); 248219370Spst elem_name(index):type_ref(short int),bit_offset(16),field_bits(16); 248319370Spst elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void), 248419370Spst bit_offset(32),field_bits(32); 248519370Spst elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;" 248619370Spst N_LSYM, NIL, NIL 248719370Spst@end display 248819370Spst 248919370Spst@smallexample 249019370Spst.stabs "$vtbl_ptr_type:t17=s8 249119370Spst delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;" 249219370Spst ,128,0,0,0 249319370Spst@end smallexample 249419370Spst 249519370Spst@display 249619370Spst.stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL 249719370Spst@end display 249819370Spst 249919370Spst@example 250019370Spst.stabs "$vtbl_ptr_type:T17",128,0,0,0 250119370Spst@end example 250219370Spst 250319370Spst@node Simple Classes 250419370Spst@section Simple Class Definition 250519370Spst 2506130809SmarcelThe stabs describing C@t{++} language features are an extension of the 2507130809Smarcelstabs describing C. Stabs representing C@t{++} class types elaborate 250819370Spstextensively on the stab format used to describe structure types in C. 250919370SpstStabs representing class type variables look just like stabs 251019370Spstrepresenting C language variables. 251119370Spst 251219370SpstConsider the following very simple class definition. 251319370Spst 251419370Spst@example 251519370Spstclass baseA @{ 251619370Spstpublic: 251719370Spst int Adat; 251819370Spst int Ameth(int in, char other); 251919370Spst@}; 252019370Spst@end example 252119370Spst 252219370SpstThe class @code{baseA} is represented by two stabs. The first stab describes 252319370Spstthe class as a structure type. The second stab describes a structure 252419370Spsttag of the class type. Both stabs are of stab type @code{N_LSYM}. Since the 252519370Spststab is not located between an @code{N_FUN} and an @code{N_LBRAC} stab this indicates 252619370Spstthat the class is defined at file scope. If it were, then the @code{N_LSYM} 252719370Spstwould signify a local variable. 252819370Spst 2529130809SmarcelA stab describing a C@t{++} class type is similar in format to a stab 253019370Spstdescribing a C struct, with each class member shown as a field in the 253119370Spststructure. The part of the struct format describing fields is 2532130809Smarcelexpanded to include extra information relevant to C@t{++} class members. 253319370SpstIn addition, if the class has multiple base classes or virtual 253419370Spstfunctions the struct format outside of the field parts is also 253519370Spstaugmented. 253619370Spst 2537130809SmarcelIn this simple example the field part of the C@t{++} class stab 253819370Spstrepresenting member data looks just like the field part of a C struct 253919370Spststab. The section on protections describes how its format is 254019370Spstsometimes extended for member data. 254119370Spst 2542130809SmarcelThe field part of a C@t{++} class stab representing a member function 254319370Spstdiffers substantially from the field part of a C struct stab. It 254419370Spststill begins with @samp{name:} but then goes on to define a new type number 254519370Spstfor the member function, describe its return type, its argument types, 254619370Spstits protection level, any qualifiers applied to the method definition, 254719370Spstand whether the method is virtual or not. If the method is virtual 254819370Spstthen the method description goes on to give the vtable index of the 254919370Spstmethod, and the type number of the first base class defining the 255019370Spstmethod. 255119370Spst 255219370SpstWhen the field name is a method name it is followed by two colons rather 255319370Spstthan one. This is followed by a new type definition for the method. 255419370SpstThis is a number followed by an equal sign and the type of the method. 255519370SpstNormally this will be a type declared using the @samp{#} type 255619370Spstdescriptor; see @ref{Method Type Descriptor}; static member functions 255719370Spstare declared using the @samp{f} type descriptor instead; see 255819370Spst@ref{Function Types}. 255919370Spst 256019370SpstThe format of an overloaded operator method name differs from that of 256119370Spstother methods. It is @samp{op$::@var{operator-name}.} where 256219370Spst@var{operator-name} is the operator name such as @samp{+} or @samp{+=}. 256319370SpstThe name ends with a period, and any characters except the period can 256419370Spstoccur in the @var{operator-name} string. 256519370Spst 256619370SpstThe next part of the method description represents the arguments to the 256798948Sobrienmethod, preceded by a colon and ending with a semi-colon. The types of 256819370Spstthe arguments are expressed in the same way argument types are expressed 2569130809Smarcelin C@t{++} name mangling. In this example an @code{int} and a @code{char} 257019370Spstmap to @samp{ic}. 257119370Spst 257219370SpstThis is followed by a number, a letter, and an asterisk or period, 257319370Spstfollowed by another semicolon. The number indicates the protections 257419370Spstthat apply to the member function. Here the 2 means public. The 257519370Spstletter encodes any qualifier applied to the method definition. In 257619370Spstthis case, @samp{A} means that it is a normal function definition. The dot 257719370Spstshows that the method is not virtual. The sections that follow 257819370Spstelaborate further on these fields and describe the additional 257919370Spstinformation present for virtual methods. 258019370Spst 258119370Spst 258219370Spst@display 258319370Spst.stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4) 258419370Spst field_name(Adat):type(int),bit_offset(0),field_bits(32); 258519370Spst 258619370Spst method_name(Ameth)::type_def(21)=type_desc(method)return_type(int); 258719370Spst :arg_types(int char); 258819370Spst protection(public)qualifier(normal)virtual(no);;" 258919370Spst N_LSYM,NIL,NIL,NIL 259019370Spst@end display 259119370Spst 259219370Spst@smallexample 259319370Spst.stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0 259419370Spst 259519370Spst.stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL 259619370Spst 259719370Spst.stabs "baseA:T20",128,0,0,0 259819370Spst@end smallexample 259919370Spst 260019370Spst@node Class Instance 260119370Spst@section Class Instance 260219370Spst 2603130809SmarcelAs shown above, describing even a simple C@t{++} class definition is 260419370Spstaccomplished by massively extending the stab format used in C to 260519370Spstdescribe structure types. However, once the class is defined, C stabs 260619370Spstwith no modifications can be used to describe class instances. The 260719370Spstfollowing source: 260819370Spst 260919370Spst@example 261019370Spstmain () @{ 261119370Spst baseA AbaseA; 261219370Spst@} 261319370Spst@end example 261419370Spst 261519370Spst@noindent 261619370Spstyields the following stab describing the class instance. It looks no 261719370Spstdifferent from a standard C stab describing a local variable. 261819370Spst 261919370Spst@display 262019370Spst.stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset 262119370Spst@end display 262219370Spst 262319370Spst@example 262419370Spst.stabs "AbaseA:20",128,0,0,-20 262519370Spst@end example 262619370Spst 262719370Spst@node Methods 262819370Spst@section Method Definition 262919370Spst 2630130809SmarcelThe class definition shown above declares Ameth. The C@t{++} source below 263119370Spstdefines Ameth: 263219370Spst 263319370Spst@example 263419370Spstint 263519370SpstbaseA::Ameth(int in, char other) 263619370Spst@{ 263719370Spst return in; 263819370Spst@}; 263919370Spst@end example 264019370Spst 264119370Spst 264219370SpstThis method definition yields three stabs following the code of the 264319370Spstmethod. One stab describes the method itself and following two describe 264419370Spstits parameters. Although there is only one formal argument all methods 264519370Spsthave an implicit argument which is the @code{this} pointer. The @code{this} 264619370Spstpointer is a pointer to the object on which the method was called. Note 264719370Spstthat the method name is mangled to encode the class name and argument 264819370Spsttypes. Name mangling is described in the @sc{arm} (@cite{The Annotated 264919370SpstC++ Reference Manual}, by Ellis and Stroustrup, @sc{isbn} 265019370Spst0-201-51459-1); @file{gpcompare.texi} in Cygnus GCC distributions 265119370Spstdescribes the differences between GNU mangling and @sc{arm} 265219370Spstmangling. 265319370Spst@c FIXME: Use @xref, especially if this is generally installed in the 265419370Spst@c info tree. 265519370Spst@c FIXME: This information should be in a net release, either of GCC or 265619370Spst@c GDB. But gpcompare.texi doesn't seem to be in the FSF GCC. 265719370Spst 265819370Spst@example 265998948Sobrien.stabs "name:symbol_descriptor(global function)return_type(int)", 266019370Spst N_FUN, NIL, NIL, code_addr_of_method_start 266119370Spst 266219370Spst.stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic 266319370Spst@end example 266419370Spst 266519370SpstHere is the stab for the @code{this} pointer implicit argument. The 266619370Spstname of the @code{this} pointer is always @code{this}. Type 19, the 266719370Spst@code{this} pointer is defined as a pointer to type 20, @code{baseA}, 266898948Sobrienbut a stab defining @code{baseA} has not yet been emitted. Since the 266998948Sobriencompiler knows it will be emitted shortly, here it just outputs a cross 267019370Spstreference to the undefined symbol, by prefixing the symbol name with 267119370Spst@samp{xs}. 267219370Spst 267319370Spst@example 267419370Spst.stabs "name:sym_desc(register param)type_def(19)= 267519370Spst type_desc(ptr to)type_ref(baseA)= 267619370Spst type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number 267719370Spst 267819370Spst.stabs "this:P19=*20=xsbaseA:",64,0,0,8 267919370Spst@end example 268019370Spst 268119370SpstThe stab for the explicit integer argument looks just like a parameter 268219370Spstto a C function. The last field of the stab is the offset from the 268319370Spstargument pointer, which in most systems is the same as the frame 268419370Spstpointer. 268519370Spst 268619370Spst@example 268719370Spst.stabs "name:sym_desc(value parameter)type_ref(int)", 268819370Spst N_PSYM,NIL,NIL,offset_from_arg_ptr 268919370Spst 269019370Spst.stabs "in:p1",160,0,0,72 269119370Spst@end example 269219370Spst 269319370Spst<< The examples that follow are based on A1.C >> 269419370Spst 269519370Spst@node Method Type Descriptor 269619370Spst@section The @samp{#} Type Descriptor 269719370Spst 269846289SdfrThis is used to describe a class method. This is a function which takes 269946289Sdfran extra argument as its first argument, for the @code{this} pointer. 270019370Spst 270146289SdfrIf the @samp{#} is immediately followed by another @samp{#}, the second 270246289Sdfrone will be followed by the return type and a semicolon. The class and 270346289Sdfrargument types are not specified, and must be determined by demangling 270446289Sdfrthe name of the method if it is available. 270546289Sdfr 270646289SdfrOtherwise, the single @samp{#} is followed by the class type, a comma, 270746289Sdfrthe return type, a comma, and zero or more parameter types separated by 270846289Sdfrcommas. The list of arguments is terminated by a semicolon. In the 270946289Sdfrdebugging output generated by gcc, a final argument type of @code{void} 271046289Sdfrindicates a method which does not take a variable number of arguments. 271146289SdfrIf the final argument type of @code{void} does not appear, the method 271246289Sdfrwas declared with an ellipsis. 271346289Sdfr 271419370SpstNote that although such a type will normally be used to describe fields 271519370Spstin structures, unions, or classes, for at least some versions of the 271619370Spstcompiler it can also be used in other contexts. 271719370Spst 271819370Spst@node Member Type Descriptor 271919370Spst@section The @samp{@@} Type Descriptor 272019370Spst 2721130809SmarcelThe @samp{@@} type descriptor is used together with the @samp{*} type 2722130809Smarceldescriptor for a pointer-to-non-static-member-data type. It is followed 2723130809Smarcelby type information for the class (or union), a comma, and type 2724130809Smarcelinformation for the member data. 272519370Spst 2726130809SmarcelThe following C@t{++} source: 2727130809Smarcel 2728130809Smarcel@smallexample 2729130809Smarceltypedef int A::*int_in_a; 2730130809Smarcel@end smallexample 2731130809Smarcel 2732130809Smarcelgenerates the following stab: 2733130809Smarcel 2734130809Smarcel@smallexample 2735130809Smarcel.stabs "int_in_a:t20=*21=@@19,1",128,0,0,0 2736130809Smarcel@end smallexample 2737130809Smarcel 273819370SpstNote that there is a conflict between this and type attributes 273919370Spst(@pxref{String Field}); both use type descriptor @samp{@@}. 2740130809SmarcelFortunately, the @samp{@@} type descriptor used in this C@t{++} sense always 274119370Spstwill be followed by a digit, @samp{(}, or @samp{-}, and type attributes 274219370Spstnever start with those things. 274319370Spst 274419370Spst@node Protections 274519370Spst@section Protections 274619370Spst 274719370SpstIn the simple class definition shown above all member data and 274898948Sobrienfunctions were publicly accessible. The example that follows 274998948Sobriencontrasts public, protected and privately accessible fields and shows 2750130809Smarcelhow these protections are encoded in C@t{++} stabs. 275119370Spst 275219370SpstIf the character following the @samp{@var{field-name}:} part of the 275319370Spststring is @samp{/}, then the next character is the visibility. @samp{0} 275419370Spstmeans private, @samp{1} means protected, and @samp{2} means public. 275519370SpstDebuggers should ignore visibility characters they do not recognize, and 275619370Spstassume a reasonable default (such as public) (GDB 4.11 does not, but 275719370Spstthis should be fixed in the next GDB release). If no visibility is 275819370Spstspecified the field is public. The visibility @samp{9} means that the 275919370Spstfield has been optimized out and is public (there is no way to specify 276019370Spstan optimized out field with a private or protected visibility). 276119370SpstVisibility @samp{9} is not supported by GDB 4.11; this should be fixed 276219370Spstin the next GDB release. 276319370Spst 2764130809SmarcelThe following C@t{++} source: 276519370Spst 276619370Spst@example 276719370Spstclass vis @{ 276819370Spstprivate: 276919370Spst int priv; 277019370Spstprotected: 277119370Spst char prot; 277219370Spstpublic: 277319370Spst float pub; 277419370Spst@}; 277519370Spst@end example 277619370Spst 277719370Spst@noindent 277819370Spstgenerates the following stab: 277919370Spst 278019370Spst@example 278119370Spst# @r{128 is N_LSYM} 278219370Spst.stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0 278319370Spst@end example 278419370Spst 278519370Spst@samp{vis:T19=s12} indicates that type number 19 is a 12 byte structure 278619370Spstnamed @code{vis} The @code{priv} field has public visibility 278719370Spst(@samp{/0}), type int (@samp{1}), and offset and size @samp{,0,32;}. 278819370SpstThe @code{prot} field has protected visibility (@samp{/1}), type char 278919370Spst(@samp{2}) and offset and size @samp{,32,8;}. The @code{pub} field has 279019370Spsttype float (@samp{12}), and offset and size @samp{,64,32;}. 279119370Spst 279298948SobrienProtections for member functions are signified by one digit embedded in 279319370Spstthe field part of the stab describing the method. The digit is 0 if 2794130809Smarcelprivate, 1 if protected and 2 if public. Consider the C@t{++} class 279519370Spstdefinition below: 279619370Spst 279719370Spst@example 279819370Spstclass all_methods @{ 279919370Spstprivate: 280019370Spst int priv_meth(int in)@{return in;@}; 280119370Spstprotected: 280219370Spst char protMeth(char in)@{return in;@}; 280319370Spstpublic: 280419370Spst float pubMeth(float in)@{return in;@}; 280519370Spst@}; 280619370Spst@end example 280719370Spst 280819370SpstIt generates the following stab. The digit in question is to the left 280919370Spstof an @samp{A} in each case. Notice also that in this case two symbol 281019370Spstdescriptors apply to the class name struct tag and struct type. 281119370Spst 281219370Spst@display 281319370Spst.stabs "class_name:sym_desc(struct tag&type)type_def(21)= 281419370Spst sym_desc(struct)struct_bytes(1) 281519370Spst meth_name::type_def(22)=sym_desc(method)returning(int); 281619370Spst :args(int);protection(private)modifier(normal)virtual(no); 281719370Spst meth_name::type_def(23)=sym_desc(method)returning(char); 281898948Sobrien :args(char);protection(protected)modifier(normal)virtual(no); 281919370Spst meth_name::type_def(24)=sym_desc(method)returning(float); 282019370Spst :args(float);protection(public)modifier(normal)virtual(no);;", 282119370Spst N_LSYM,NIL,NIL,NIL 282219370Spst@end display 282319370Spst 282419370Spst@smallexample 282519370Spst.stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.; 282619370Spst pubMeth::24=##12;:f;2A.;;",128,0,0,0 282719370Spst@end smallexample 282819370Spst 282919370Spst@node Method Modifiers 283019370Spst@section Method Modifiers (@code{const}, @code{volatile}, @code{const volatile}) 283119370Spst 283219370Spst<< based on a6.C >> 283319370Spst 283419370SpstIn the class example described above all the methods have the normal 283519370Spstmodifier. This method modifier information is located just after the 283619370Spstprotection information for the method. This field has four possible 283719370Spstcharacter values. Normal methods use @samp{A}, const methods use 283819370Spst@samp{B}, volatile methods use @samp{C}, and const volatile methods use 283919370Spst@samp{D}. Consider the class definition below: 284019370Spst 284119370Spst@example 284219370Spstclass A @{ 284319370Spstpublic: 284419370Spst int ConstMeth (int arg) const @{ return arg; @}; 284519370Spst char VolatileMeth (char arg) volatile @{ return arg; @}; 284619370Spst float ConstVolMeth (float arg) const volatile @{return arg; @}; 284719370Spst@}; 284819370Spst@end example 284919370Spst 285019370SpstThis class is described by the following stab: 285119370Spst 285219370Spst@display 285319370Spst.stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1) 285419370Spst meth_name(ConstMeth)::type_def(21)sym_desc(method) 285519370Spst returning(int);:arg(int);protection(public)modifier(const)virtual(no); 285619370Spst meth_name(VolatileMeth)::type_def(22)=sym_desc(method) 285719370Spst returning(char);:arg(char);protection(public)modifier(volatile)virt(no) 285819370Spst meth_name(ConstVolMeth)::type_def(23)=sym_desc(method) 285998948Sobrien returning(float);:arg(float);protection(public)modifier(const volatile) 286019370Spst virtual(no);;", @dots{} 286119370Spst@end display 286219370Spst 286319370Spst@example 286419370Spst.stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.; 286519370Spst ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0 286619370Spst@end example 286719370Spst 286819370Spst@node Virtual Methods 286919370Spst@section Virtual Methods 287019370Spst 287119370Spst<< The following examples are based on a4.C >> 287219370Spst 287319370SpstThe presence of virtual methods in a class definition adds additional 287419370Spstdata to the class description. The extra data is appended to the 287519370Spstdescription of the virtual method and to the end of the class 287619370Spstdescription. Consider the class definition below: 287719370Spst 287819370Spst@example 287919370Spstclass A @{ 288019370Spstpublic: 288119370Spst int Adat; 288219370Spst virtual int A_virt (int arg) @{ return arg; @}; 288319370Spst@}; 288419370Spst@end example 288519370Spst 288619370SpstThis results in the stab below describing class A. It defines a new 288719370Spsttype (20) which is an 8 byte structure. The first field of the class 288819370Spststruct is @samp{Adat}, an integer, starting at structure offset 0 and 288919370Spstoccupying 32 bits. 289019370Spst 289119370SpstThe second field in the class struct is not explicitly defined by the 2892130809SmarcelC@t{++} class definition but is implied by the fact that the class 289319370Spstcontains a virtual method. This field is the vtable pointer. The 289419370Spstname of the vtable pointer field starts with @samp{$vf} and continues with a 289519370Spsttype reference to the class it is part of. In this example the type 289619370Spstreference for class A is 20 so the name of its vtable pointer field is 289719370Spst@samp{$vf20}, followed by the usual colon. 289819370Spst 289919370SpstNext there is a type definition for the vtable pointer type (21). 290019370SpstThis is in turn defined as a pointer to another new type (22). 290119370Spst 290219370SpstType 22 is the vtable itself, which is defined as an array, indexed by 290319370Spsta range of integers between 0 and 1, and whose elements are of type 2904130809Smarcel17. Type 17 was the vtable record type defined by the boilerplate C@t{++} 290519370Spsttype definitions, as shown earlier. 290619370Spst 290719370SpstThe bit offset of the vtable pointer field is 32. The number of bits 290819370Spstin the field are not specified when the field is a vtable pointer. 290919370Spst 291019370SpstNext is the method definition for the virtual member function @code{A_virt}. 291119370SpstIts description starts out using the same format as the non-virtual 291219370Spstmember functions described above, except instead of a dot after the 291319370Spst@samp{A} there is an asterisk, indicating that the function is virtual. 291419370SpstSince is is virtual some addition information is appended to the end 291519370Spstof the method description. 291619370Spst 291719370SpstThe first number represents the vtable index of the method. This is a 291819370Spst32 bit unsigned number with the high bit set, followed by a 291919370Spstsemi-colon. 292019370Spst 292119370SpstThe second number is a type reference to the first base class in the 292298948Sobrieninheritance hierarchy defining the virtual member function. In this 292319370Spstcase the class stab describes a base class so the virtual function is 292419370Spstnot overriding any other definition of the method. Therefore the 292519370Spstreference is to the type number of the class that the stab is 292619370Spstdescribing (20). 292719370Spst 292819370SpstThis is followed by three semi-colons. One marks the end of the 292919370Spstcurrent sub-section, one marks the end of the method field, and the 293019370Spstthird marks the end of the struct definition. 293119370Spst 293219370SpstFor classes containing virtual functions the very last section of the 293319370Spststring part of the stab holds a type reference to the first base 293498948Sobrienclass. This is preceded by @samp{~%} and followed by a final semi-colon. 293519370Spst 293619370Spst@display 293719370Spst.stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8) 293819370Spst field_name(Adat):type_ref(int),bit_offset(0),field_bits(32); 293919370Spst field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)= 294019370Spst sym_desc(array)index_type_ref(range of int from 0 to 1); 294119370Spst elem_type_ref(vtbl elem type), 294219370Spst bit_offset(32); 294319370Spst meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int); 294419370Spst :arg_type(int),protection(public)normal(yes)virtual(yes) 294519370Spst vtable_index(1);class_first_defining(A);;;~%first_base(A);", 294619370Spst N_LSYM,NIL,NIL,NIL 294719370Spst@end display 294819370Spst 294919370Spst@c FIXME: bogus line break. 295019370Spst@example 295119370Spst.stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; 295219370Spst A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 295319370Spst@end example 295419370Spst 295598948Sobrien@node Inheritance 295698948Sobrien@section Inheritance 295719370Spst 2958130809SmarcelStabs describing C@t{++} derived classes include additional sections that 295998948Sobriendescribe the inheritance hierarchy of the class. A derived class stab 296019370Spstalso encodes the number of base classes. For each base class it tells 296198948Sobrienif the base class is virtual or not, and if the inheritance is private 296219370Spstor public. It also gives the offset into the object of the portion of 296319370Spstthe object corresponding to each base class. 296419370Spst 296598948SobrienThis additional information is embedded in the class stab following the 296619370Spstnumber of bytes in the struct. First the number of base classes 296719370Spstappears bracketed by an exclamation point and a comma. 296819370Spst 296919370SpstThen for each base type there repeats a series: a virtual character, a 297098948Sobrienvisibility character, a number, a comma, another number, and a 297119370Spstsemi-colon. 297219370Spst 297319370SpstThe virtual character is @samp{1} if the base class is virtual and 297419370Spst@samp{0} if not. The visibility character is @samp{2} if the derivation 297519370Spstis public, @samp{1} if it is protected, and @samp{0} if it is private. 297619370SpstDebuggers should ignore virtual or visibility characters they do not 297719370Spstrecognize, and assume a reasonable default (such as public and 297819370Spstnon-virtual) (GDB 4.11 does not, but this should be fixed in the next 297919370SpstGDB release). 298019370Spst 298119370SpstThe number following the virtual and visibility characters is the offset 298219370Spstfrom the start of the object to the part of the object pertaining to the 298319370Spstbase class. 298419370Spst 298519370SpstAfter the comma, the second number is a type_descriptor for the base 298619370Spsttype. Finally a semi-colon ends the series, which repeats for each 298719370Spstbase class. 298819370Spst 298919370SpstThe source below defines three base classes @code{A}, @code{B}, and 299019370Spst@code{C} and the derived class @code{D}. 299119370Spst 299219370Spst 299319370Spst@example 299419370Spstclass A @{ 299519370Spstpublic: 299619370Spst int Adat; 299719370Spst virtual int A_virt (int arg) @{ return arg; @}; 299819370Spst@}; 299919370Spst 300019370Spstclass B @{ 300119370Spstpublic: 300219370Spst int B_dat; 300319370Spst virtual int B_virt (int arg) @{return arg; @}; 300419370Spst@}; 300519370Spst 300619370Spstclass C @{ 300719370Spstpublic: 300819370Spst int Cdat; 300919370Spst virtual int C_virt (int arg) @{return arg; @}; 301019370Spst@}; 301119370Spst 301219370Spstclass D : A, virtual B, public C @{ 301319370Spstpublic: 301419370Spst int Ddat; 301519370Spst virtual int A_virt (int arg ) @{ return arg+1; @}; 301619370Spst virtual int B_virt (int arg) @{ return arg+2; @}; 301719370Spst virtual int C_virt (int arg) @{ return arg+3; @}; 301819370Spst virtual int D_virt (int arg) @{ return arg; @}; 301919370Spst@}; 302019370Spst@end example 302119370Spst 302219370SpstClass stabs similar to the ones described earlier are generated for 302319370Spsteach base class. 302419370Spst 302519370Spst@c FIXME!!! the linebreaks in the following example probably make the 302619370Spst@c examples literally unusable, but I don't know any other way to get 302719370Spst@c them on the page. 302819370Spst@c One solution would be to put some of the type definitions into 302919370Spst@c separate stabs, even if that's not exactly what the compiler actually 303019370Spst@c emits. 303119370Spst@smallexample 303219370Spst.stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; 303319370Spst A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 303419370Spst 303519370Spst.stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1; 303619370Spst :i;2A*-2147483647;25;;;~%25;",128,0,0,0 303719370Spst 303819370Spst.stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1; 303919370Spst :i;2A*-2147483647;28;;;~%28;",128,0,0,0 304019370Spst@end smallexample 304119370Spst 304219370SpstIn the stab describing derived class @code{D} below, the information about 304319370Spstthe derivation of this class is encoded as follows. 304419370Spst 304519370Spst@display 304619370Spst.stabs "derived_class_name:symbol_descriptors(struct tag&type)= 304719370Spst type_descriptor(struct)struct_bytes(32)!num_bases(3), 304898948Sobrien base_virtual(no)inheritance_public(no)base_offset(0), 304919370Spst base_class_type_ref(A); 305098948Sobrien base_virtual(yes)inheritance_public(no)base_offset(NIL), 305119370Spst base_class_type_ref(B); 305298948Sobrien base_virtual(no)inheritance_public(yes)base_offset(64), 305319370Spst base_class_type_ref(C); @dots{} 305419370Spst@end display 305519370Spst 305619370Spst@c FIXME! fake linebreaks. 305719370Spst@smallexample 305819370Spst.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat: 305919370Spst 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt: 306019370Spst :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647; 306119370Spst 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 306219370Spst@end smallexample 306319370Spst 306419370Spst@node Virtual Base Classes 306519370Spst@section Virtual Base Classes 306619370Spst 306798948SobrienA derived class object consists of a concatenation in memory of the data 306819370Spstareas defined by each base class, starting with the leftmost and ending 306919370Spstwith the rightmost in the list of base classes. The exception to this 307098948Sobrienrule is for virtual inheritance. In the example above, class @code{D} 307119370Spstinherits virtually from base class @code{B}. This means that an 307219370Spstinstance of a @code{D} object will not contain its own @code{B} part but 307319370Spstmerely a pointer to a @code{B} part, known as a virtual base pointer. 307419370Spst 307519370SpstIn a derived class stab, the base offset part of the derivation 307619370Spstinformation, described above, shows how the base class parts are 307719370Spstordered. The base offset for a virtual base class is always given as 0. 307819370SpstNotice that the base offset for @code{B} is given as 0 even though 307919370Spst@code{B} is not the first base class. The first base class @code{A} 308019370Spststarts at offset 0. 308119370Spst 308219370SpstThe field information part of the stab for class @code{D} describes the field 308319370Spstwhich is the pointer to the virtual base class @code{B}. The vbase pointer 308419370Spstname is @samp{$vb} followed by a type reference to the virtual base class. 308519370SpstSince the type id for @code{B} in this example is 25, the vbase pointer name 308619370Spstis @samp{$vb25}. 308719370Spst 308819370Spst@c FIXME!! fake linebreaks below 308919370Spst@smallexample 309019370Spst.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1, 309119370Spst 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i; 309219370Spst 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt: 309319370Spst :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 309419370Spst@end smallexample 309519370Spst 309619370SpstFollowing the name and a semicolon is a type reference describing the 309719370Spsttype of the virtual base class pointer, in this case 24. Type 24 was 309819370Spstdefined earlier as the type of the @code{B} class @code{this} pointer. The 309919370Spst@code{this} pointer for a class is a pointer to the class type. 310019370Spst 310119370Spst@example 310219370Spst.stabs "this:P24=*25=xsB:",64,0,0,8 310319370Spst@end example 310419370Spst 310519370SpstFinally the field offset part of the vbase pointer field description 310619370Spstshows that the vbase pointer is the first field in the @code{D} object, 310719370Spstbefore any data fields defined by the class. The layout of a @code{D} 310819370Spstclass object is a follows, @code{Adat} at 0, the vtable pointer for 310919370Spst@code{A} at 32, @code{Cdat} at 64, the vtable pointer for C at 96, the 311019370Spstvirtual base pointer for @code{B} at 128, and @code{Ddat} at 160. 311119370Spst 311219370Spst 311319370Spst@node Static Members 311419370Spst@section Static Members 311519370Spst 311619370SpstThe data area for a class is a concatenation of the space used by the 311719370Spstdata members of the class. If the class has virtual methods, a vtable 311819370Spstpointer follows the class data. The field offset part of each field 311919370Spstdescription in the class stab shows this ordering. 312019370Spst 312119370Spst<< How is this reflected in stabs? See Cygnus bug #677 for some info. >> 312219370Spst 312319370Spst@node Stab Types 312419370Spst@appendix Table of Stab Types 312519370Spst 312619370SpstThe following are all the possible values for the stab type field, for 312719370Spsta.out files, in numeric order. This does not apply to XCOFF, but 312819370Spstit does apply to stabs in sections (@pxref{Stab Sections}). Stabs in 312919370SpstECOFF use these values but add 0x8f300 to distinguish them from non-stab 313019370Spstsymbols. 313119370Spst 313219370SpstThe symbolic names are defined in the file @file{include/aout/stabs.def}. 313319370Spst 313419370Spst@menu 313519370Spst* Non-Stab Symbol Types:: Types from 0 to 0x1f 313619370Spst* Stab Symbol Types:: Types from 0x20 to 0xff 313719370Spst@end menu 313819370Spst 313919370Spst@node Non-Stab Symbol Types 314019370Spst@appendixsec Non-Stab Symbol Types 314119370Spst 314219370SpstThe following types are used by the linker and assembler, not by stab 314319370Spstdirectives. Since this document does not attempt to describe aspects of 314419370Spstobject file format other than the debugging format, no details are 314519370Spstgiven. 314619370Spst 314719370Spst@c Try to get most of these to fit on a single line. 314819370Spst@iftex 314919370Spst@tableindent=1.5in 315019370Spst@end iftex 315119370Spst 315219370Spst@table @code 315319370Spst@item 0x0 N_UNDF 315419370SpstUndefined symbol 315519370Spst 315619370Spst@item 0x2 N_ABS 315719370SpstFile scope absolute symbol 315819370Spst 315919370Spst@item 0x3 N_ABS | N_EXT 316019370SpstExternal absolute symbol 316119370Spst 316219370Spst@item 0x4 N_TEXT 316319370SpstFile scope text symbol 316419370Spst 316519370Spst@item 0x5 N_TEXT | N_EXT 316619370SpstExternal text symbol 316719370Spst 316819370Spst@item 0x6 N_DATA 316919370SpstFile scope data symbol 317019370Spst 317119370Spst@item 0x7 N_DATA | N_EXT 317219370SpstExternal data symbol 317319370Spst 317419370Spst@item 0x8 N_BSS 317519370SpstFile scope BSS symbol 317619370Spst 317719370Spst@item 0x9 N_BSS | N_EXT 317819370SpstExternal BSS symbol 317919370Spst 318019370Spst@item 0x0c N_FN_SEQ 318119370SpstSame as @code{N_FN}, for Sequent compilers 318219370Spst 318319370Spst@item 0x0a N_INDR 318419370SpstSymbol is indirected to another symbol 318519370Spst 318619370Spst@item 0x12 N_COMM 318719370SpstCommon---visible after shared library dynamic link 318819370Spst 318919370Spst@item 0x14 N_SETA 319019370Spst@itemx 0x15 N_SETA | N_EXT 319119370SpstAbsolute set element 319219370Spst 319319370Spst@item 0x16 N_SETT 319419370Spst@itemx 0x17 N_SETT | N_EXT 319519370SpstText segment set element 319619370Spst 319719370Spst@item 0x18 N_SETD 319819370Spst@itemx 0x19 N_SETD | N_EXT 319919370SpstData segment set element 320019370Spst 320119370Spst@item 0x1a N_SETB 320219370Spst@itemx 0x1b N_SETB | N_EXT 320319370SpstBSS segment set element 320419370Spst 320519370Spst@item 0x1c N_SETV 320619370Spst@itemx 0x1d N_SETV | N_EXT 320719370SpstPointer to set vector 320819370Spst 320919370Spst@item 0x1e N_WARNING 321019370SpstPrint a warning message during linking 321119370Spst 321219370Spst@item 0x1f N_FN 321319370SpstFile name of a @file{.o} file 321419370Spst@end table 321519370Spst 321619370Spst@node Stab Symbol Types 321719370Spst@appendixsec Stab Symbol Types 321819370Spst 321919370SpstThe following symbol types indicate that this is a stab. This is the 322019370Spstfull list of stab numbers, including stab types that are used in 322119370Spstlanguages other than C. 322219370Spst 322319370Spst@table @code 322419370Spst@item 0x20 N_GSYM 322519370SpstGlobal symbol; see @ref{Global Variables}. 322619370Spst 322719370Spst@item 0x22 N_FNAME 322819370SpstFunction name (for BSD Fortran); see @ref{Procedures}. 322919370Spst 323019370Spst@item 0x24 N_FUN 323119370SpstFunction name (@pxref{Procedures}) or text segment variable 323219370Spst(@pxref{Statics}). 323319370Spst 323419370Spst@item 0x26 N_STSYM 323519370SpstData segment file-scope variable; see @ref{Statics}. 323619370Spst 323719370Spst@item 0x28 N_LCSYM 323819370SpstBSS segment file-scope variable; see @ref{Statics}. 323919370Spst 324019370Spst@item 0x2a N_MAIN 324119370SpstName of main routine; see @ref{Main Program}. 324219370Spst 324319370Spst@item 0x2c N_ROSYM 324419370SpstVariable in @code{.rodata} section; see @ref{Statics}. 324519370Spst 324619370Spst@item 0x30 N_PC 324719370SpstGlobal symbol (for Pascal); see @ref{N_PC}. 324819370Spst 324919370Spst@item 0x32 N_NSYMS 325019370SpstNumber of symbols (according to Ultrix V4.0); see @ref{N_NSYMS}. 325119370Spst 325219370Spst@item 0x34 N_NOMAP 325319370SpstNo DST map; see @ref{N_NOMAP}. 325419370Spst 325519370Spst@c FIXME: describe this solaris feature in the body of the text (see 325619370Spst@c comments in include/aout/stab.def). 325719370Spst@item 0x38 N_OBJ 325819370SpstObject file (Solaris2). 325919370Spst 326019370Spst@c See include/aout/stab.def for (a little) more info. 326119370Spst@item 0x3c N_OPT 326219370SpstDebugger options (Solaris2). 326319370Spst 326419370Spst@item 0x40 N_RSYM 326519370SpstRegister variable; see @ref{Register Variables}. 326619370Spst 326719370Spst@item 0x42 N_M2C 326819370SpstModula-2 compilation unit; see @ref{N_M2C}. 326919370Spst 327019370Spst@item 0x44 N_SLINE 327119370SpstLine number in text segment; see @ref{Line Numbers}. 327219370Spst 327319370Spst@item 0x46 N_DSLINE 327419370SpstLine number in data segment; see @ref{Line Numbers}. 327519370Spst 327619370Spst@item 0x48 N_BSLINE 327719370SpstLine number in bss segment; see @ref{Line Numbers}. 327819370Spst 327919370Spst@item 0x48 N_BROWS 328019370SpstSun source code browser, path to @file{.cb} file; see @ref{N_BROWS}. 328119370Spst 328219370Spst@item 0x4a N_DEFD 328319370SpstGNU Modula2 definition module dependency; see @ref{N_DEFD}. 328419370Spst 328519370Spst@item 0x4c N_FLINE 328619370SpstFunction start/body/end line numbers (Solaris2). 328719370Spst 328819370Spst@item 0x50 N_EHDECL 3289130809SmarcelGNU C@t{++} exception variable; see @ref{N_EHDECL}. 329019370Spst 329119370Spst@item 0x50 N_MOD2 329219370SpstModula2 info "for imc" (according to Ultrix V4.0); see @ref{N_MOD2}. 329319370Spst 329419370Spst@item 0x54 N_CATCH 3295130809SmarcelGNU C@t{++} @code{catch} clause; see @ref{N_CATCH}. 329619370Spst 329719370Spst@item 0x60 N_SSYM 329819370SpstStructure of union element; see @ref{N_SSYM}. 329919370Spst 330019370Spst@item 0x62 N_ENDM 330119370SpstLast stab for module (Solaris2). 330219370Spst 330319370Spst@item 0x64 N_SO 330419370SpstPath and name of source file; see @ref{Source Files}. 330519370Spst 330619370Spst@item 0x80 N_LSYM 330719370SpstStack variable (@pxref{Stack Variables}) or type (@pxref{Typedefs}). 330819370Spst 330919370Spst@item 0x82 N_BINCL 331019370SpstBeginning of an include file (Sun only); see @ref{Include Files}. 331119370Spst 331219370Spst@item 0x84 N_SOL 331319370SpstName of include file; see @ref{Include Files}. 331419370Spst 331519370Spst@item 0xa0 N_PSYM 331619370SpstParameter variable; see @ref{Parameters}. 331719370Spst 331819370Spst@item 0xa2 N_EINCL 331919370SpstEnd of an include file; see @ref{Include Files}. 332019370Spst 332119370Spst@item 0xa4 N_ENTRY 332219370SpstAlternate entry point; see @ref{Alternate Entry Points}. 332319370Spst 332419370Spst@item 0xc0 N_LBRAC 332519370SpstBeginning of a lexical block; see @ref{Block Structure}. 332619370Spst 332719370Spst@item 0xc2 N_EXCL 332819370SpstPlace holder for a deleted include file; see @ref{Include Files}. 332919370Spst 333019370Spst@item 0xc4 N_SCOPE 333119370SpstModula2 scope information (Sun linker); see @ref{N_SCOPE}. 333219370Spst 333319370Spst@item 0xe0 N_RBRAC 333419370SpstEnd of a lexical block; see @ref{Block Structure}. 333519370Spst 333619370Spst@item 0xe2 N_BCOMM 333719370SpstBegin named common block; see @ref{Common Blocks}. 333819370Spst 333919370Spst@item 0xe4 N_ECOMM 334019370SpstEnd named common block; see @ref{Common Blocks}. 334119370Spst 334219370Spst@item 0xe8 N_ECOML 334319370SpstMember of a common block; see @ref{Common Blocks}. 334419370Spst 334519370Spst@c FIXME: How does this really work? Move it to main body of document. 334619370Spst@item 0xea N_WITH 334719370SpstPascal @code{with} statement: type,,0,0,offset (Solaris2). 334819370Spst 334919370Spst@item 0xf0 N_NBTEXT 335019370SpstGould non-base registers; see @ref{Gould}. 335119370Spst 335219370Spst@item 0xf2 N_NBDATA 335319370SpstGould non-base registers; see @ref{Gould}. 335419370Spst 335519370Spst@item 0xf4 N_NBBSS 335619370SpstGould non-base registers; see @ref{Gould}. 335719370Spst 335819370Spst@item 0xf6 N_NBSTS 335919370SpstGould non-base registers; see @ref{Gould}. 336019370Spst 336119370Spst@item 0xf8 N_NBLCS 336219370SpstGould non-base registers; see @ref{Gould}. 336319370Spst@end table 336419370Spst 336519370Spst@c Restore the default table indent 336619370Spst@iftex 336719370Spst@tableindent=.8in 336819370Spst@end iftex 336919370Spst 337019370Spst@node Symbol Descriptors 337119370Spst@appendix Table of Symbol Descriptors 337219370Spst 337319370SpstThe symbol descriptor is the character which follows the colon in many 337419370Spststabs, and which tells what kind of stab it is. @xref{String Field}, 337519370Spstfor more information about their use. 337619370Spst 337719370Spst@c Please keep this alphabetical 337819370Spst@table @code 337919370Spst@c In TeX, this looks great, digit is in italics. But makeinfo insists 338019370Spst@c on putting it in `', not realizing that @var should override @code. 338119370Spst@c I don't know of any way to make makeinfo do the right thing. Seems 338219370Spst@c like a makeinfo bug to me. 338319370Spst@item @var{digit} 338419370Spst@itemx ( 338519370Spst@itemx - 338619370SpstVariable on the stack; see @ref{Stack Variables}. 338719370Spst 338819370Spst@item : 3389130809SmarcelC@t{++} nested symbol; see @xref{Nested Symbols}. 339019370Spst 339119370Spst@item a 339219370SpstParameter passed by reference in register; see @ref{Reference Parameters}. 339319370Spst 339419370Spst@item b 339519370SpstBased variable; see @ref{Based Variables}. 339619370Spst 339719370Spst@item c 339819370SpstConstant; see @ref{Constants}. 339919370Spst 340019370Spst@item C 340119370SpstConformant array bound (Pascal, maybe other languages); @ref{Conformant 3402130809SmarcelArrays}. Name of a caught exception (GNU C@t{++}). These can be 340319370Spstdistinguished because the latter uses @code{N_CATCH} and the former uses 340419370Spstanother symbol type. 340519370Spst 340619370Spst@item d 340719370SpstFloating point register variable; see @ref{Register Variables}. 340819370Spst 340919370Spst@item D 341019370SpstParameter in floating point register; see @ref{Register Parameters}. 341119370Spst 341219370Spst@item f 341319370SpstFile scope function; see @ref{Procedures}. 341419370Spst 341519370Spst@item F 341619370SpstGlobal function; see @ref{Procedures}. 341719370Spst 341819370Spst@item G 341919370SpstGlobal variable; see @ref{Global Variables}. 342019370Spst 342119370Spst@item i 342219370Spst@xref{Register Parameters}. 342319370Spst 342419370Spst@item I 342519370SpstInternal (nested) procedure; see @ref{Nested Procedures}. 342619370Spst 342719370Spst@item J 342819370SpstInternal (nested) function; see @ref{Nested Procedures}. 342919370Spst 343019370Spst@item L 343119370SpstLabel name (documented by AIX, no further information known). 343219370Spst 343319370Spst@item m 343419370SpstModule; see @ref{Procedures}. 343519370Spst 343619370Spst@item p 343719370SpstArgument list parameter; see @ref{Parameters}. 343819370Spst 343919370Spst@item pP 344019370Spst@xref{Parameters}. 344119370Spst 344219370Spst@item pF 344319370SpstFortran Function parameter; see @ref{Parameters}. 344419370Spst 344519370Spst@item P 344619370SpstUnfortunately, three separate meanings have been independently invented 344719370Spstfor this symbol descriptor. At least the GNU and Sun uses can be 344819370Spstdistinguished by the symbol type. Global Procedure (AIX) (symbol type 344919370Spstused unknown); see @ref{Procedures}. Register parameter (GNU) (symbol 345019370Spsttype @code{N_PSYM}); see @ref{Parameters}. Prototype of function 345119370Spstreferenced by this file (Sun @code{acc}) (symbol type @code{N_FUN}). 345219370Spst 345319370Spst@item Q 345419370SpstStatic Procedure; see @ref{Procedures}. 345519370Spst 345619370Spst@item R 345719370SpstRegister parameter; see @ref{Register Parameters}. 345819370Spst 345919370Spst@item r 346019370SpstRegister variable; see @ref{Register Variables}. 346119370Spst 346219370Spst@item S 346319370SpstFile scope variable; see @ref{Statics}. 346419370Spst 346519370Spst@item s 346619370SpstLocal variable (OS9000). 346719370Spst 346819370Spst@item t 346919370SpstType name; see @ref{Typedefs}. 347019370Spst 347119370Spst@item T 347219370SpstEnumeration, structure, or union tag; see @ref{Typedefs}. 347319370Spst 347419370Spst@item v 347519370SpstParameter passed by reference; see @ref{Reference Parameters}. 347619370Spst 347719370Spst@item V 347819370SpstProcedure scope static variable; see @ref{Statics}. 347919370Spst 348019370Spst@item x 348119370SpstConformant array; see @ref{Conformant Arrays}. 348219370Spst 348319370Spst@item X 348419370SpstFunction return variable; see @ref{Parameters}. 348519370Spst@end table 348619370Spst 348719370Spst@node Type Descriptors 348819370Spst@appendix Table of Type Descriptors 348919370Spst 349019370SpstThe type descriptor is the character which follows the type number and 349119370Spstan equals sign. It specifies what kind of type is being defined. 349219370Spst@xref{String Field}, for more information about their use. 349319370Spst 349419370Spst@table @code 349519370Spst@item @var{digit} 349619370Spst@itemx ( 349719370SpstType reference; see @ref{String Field}. 349819370Spst 349919370Spst@item - 350019370SpstReference to builtin type; see @ref{Negative Type Numbers}. 350119370Spst 350219370Spst@item # 3503130809SmarcelMethod (C@t{++}); see @ref{Method Type Descriptor}. 350419370Spst 350519370Spst@item * 350619370SpstPointer; see @ref{Miscellaneous Types}. 350719370Spst 350819370Spst@item & 3509130809SmarcelReference (C@t{++}). 351019370Spst 351119370Spst@item @@ 351219370SpstType Attributes (AIX); see @ref{String Field}. Member (class and variable) 3513130809Smarceltype (GNU C@t{++}); see @ref{Member Type Descriptor}. 351419370Spst 351519370Spst@item a 351619370SpstArray; see @ref{Arrays}. 351719370Spst 351819370Spst@item A 351919370SpstOpen array; see @ref{Arrays}. 352019370Spst 352119370Spst@item b 352219370SpstPascal space type (AIX); see @ref{Miscellaneous Types}. Builtin integer 352319370Spsttype (Sun); see @ref{Builtin Type Descriptors}. Const and volatile 352498948Sobrienqualified type (OS9000). 352519370Spst 352619370Spst@item B 352719370SpstVolatile-qualified type; see @ref{Miscellaneous Types}. 352819370Spst 352919370Spst@item c 353019370SpstComplex builtin type (AIX); see @ref{Builtin Type Descriptors}. 353119370SpstConst-qualified type (OS9000). 353219370Spst 353319370Spst@item C 353419370SpstCOBOL Picture type. See AIX documentation for details. 353519370Spst 353619370Spst@item d 353719370SpstFile type; see @ref{Miscellaneous Types}. 353819370Spst 353919370Spst@item D 354019370SpstN-dimensional dynamic array; see @ref{Arrays}. 354119370Spst 354219370Spst@item e 354319370SpstEnumeration type; see @ref{Enumerations}. 354419370Spst 354519370Spst@item E 354619370SpstN-dimensional subarray; see @ref{Arrays}. 354719370Spst 354819370Spst@item f 354919370SpstFunction type; see @ref{Function Types}. 355019370Spst 355119370Spst@item F 355219370SpstPascal function parameter; see @ref{Function Types} 355319370Spst 355419370Spst@item g 355519370SpstBuiltin floating point type; see @ref{Builtin Type Descriptors}. 355619370Spst 355719370Spst@item G 355819370SpstCOBOL Group. See AIX documentation for details. 355919370Spst 356019370Spst@item i 356119370SpstImported type (AIX); see @ref{Cross-References}. Volatile-qualified 356219370Spsttype (OS9000). 356319370Spst 356419370Spst@item k 356519370SpstConst-qualified type; see @ref{Miscellaneous Types}. 356619370Spst 356719370Spst@item K 356819370SpstCOBOL File Descriptor. See AIX documentation for details. 356919370Spst 357019370Spst@item M 357119370SpstMultiple instance type; see @ref{Miscellaneous Types}. 357219370Spst 357319370Spst@item n 357419370SpstString type; see @ref{Strings}. 357519370Spst 357619370Spst@item N 357719370SpstStringptr; see @ref{Strings}. 357819370Spst 357919370Spst@item o 358019370SpstOpaque type; see @ref{Typedefs}. 358119370Spst 358219370Spst@item p 358319370SpstProcedure; see @ref{Function Types}. 358419370Spst 358519370Spst@item P 358619370SpstPacked array; see @ref{Arrays}. 358719370Spst 358819370Spst@item r 358919370SpstRange type; see @ref{Subranges}. 359019370Spst 359119370Spst@item R 359219370SpstBuiltin floating type; see @ref{Builtin Type Descriptors} (Sun). Pascal 359319370Spstsubroutine parameter; see @ref{Function Types} (AIX). Detecting this 359419370Spstconflict is possible with careful parsing (hint: a Pascal subroutine 359519370Spstparameter type will always contain a comma, and a builtin type 359619370Spstdescriptor never will). 359719370Spst 359819370Spst@item s 359919370SpstStructure type; see @ref{Structures}. 360019370Spst 360119370Spst@item S 360219370SpstSet type; see @ref{Miscellaneous Types}. 360319370Spst 360419370Spst@item u 360519370SpstUnion; see @ref{Unions}. 360619370Spst 360719370Spst@item v 360819370SpstVariant record. This is a Pascal and Modula-2 feature which is like a 360919370Spstunion within a struct in C. See AIX documentation for details. 361019370Spst 361119370Spst@item w 361219370SpstWide character; see @ref{Builtin Type Descriptors}. 361319370Spst 361419370Spst@item x 361519370SpstCross-reference; see @ref{Cross-References}. 361619370Spst 361719370Spst@item Y 3618130809SmarcelUsed by IBM's xlC C@t{++} compiler (for structures, I think). 361919370Spst 362019370Spst@item z 362119370Spstgstring; see @ref{Strings}. 362219370Spst@end table 362319370Spst 362419370Spst@node Expanded Reference 362519370Spst@appendix Expanded Reference by Stab Type 362619370Spst 362719370Spst@c FIXME: This appendix should go away; see N_PSYM or N_SO for an example. 362819370Spst 362919370SpstFor a full list of stab types, and cross-references to where they are 363019370Spstdescribed, see @ref{Stab Types}. This appendix just covers certain 363119370Spststabs which are not yet described in the main body of this document; 363219370Spsteventually the information will all be in one place. 363319370Spst 363419370SpstFormat of an entry: 363519370Spst 363619370SpstThe first line is the symbol type (see @file{include/aout/stab.def}). 363719370Spst 363819370SpstThe second line describes the language constructs the symbol type 363919370Spstrepresents. 364019370Spst 364119370SpstThe third line is the stab format with the significant stab fields 364219370Spstnamed and the rest NIL. 364319370Spst 364419370SpstSubsequent lines expand upon the meaning and possible values for each 364519370Spstsignificant stab field. 364619370Spst 364719370SpstFinally, any further information. 364819370Spst 364919370Spst@menu 365019370Spst* N_PC:: Pascal global symbol 365119370Spst* N_NSYMS:: Number of symbols 365219370Spst* N_NOMAP:: No DST map 365319370Spst* N_M2C:: Modula-2 compilation unit 365419370Spst* N_BROWS:: Path to .cb file for Sun source code browser 365519370Spst* N_DEFD:: GNU Modula2 definition module dependency 365619370Spst* N_EHDECL:: GNU C++ exception variable 365719370Spst* N_MOD2:: Modula2 information "for imc" 365819370Spst* N_CATCH:: GNU C++ "catch" clause 365919370Spst* N_SSYM:: Structure or union element 366019370Spst* N_SCOPE:: Modula2 scope information (Sun only) 366119370Spst* Gould:: non-base register symbols used on Gould systems 366219370Spst* N_LENG:: Length of preceding entry 366319370Spst@end menu 366419370Spst 366519370Spst@node N_PC 366619370Spst@section N_PC 366719370Spst 366819370Spst@deffn @code{.stabs} N_PC 366919370Spst@findex N_PC 367019370SpstGlobal symbol (for Pascal). 367119370Spst 367219370Spst@example 367319370Spst"name" -> "symbol_name" <<?>> 367419370Spstvalue -> supposedly the line number (stab.def is skeptical) 367519370Spst@end example 367619370Spst 367719370Spst@display 367819370Spst@file{stabdump.c} says: 367919370Spst 368019370Spstglobal pascal symbol: name,,0,subtype,line 368119370Spst<< subtype? >> 368219370Spst@end display 368319370Spst@end deffn 368419370Spst 368519370Spst@node N_NSYMS 368619370Spst@section N_NSYMS 368719370Spst 368819370Spst@deffn @code{.stabn} N_NSYMS 368919370Spst@findex N_NSYMS 369019370SpstNumber of symbols (according to Ultrix V4.0). 369119370Spst 369219370Spst@display 369319370Spst 0, files,,funcs,lines (stab.def) 369419370Spst@end display 369519370Spst@end deffn 369619370Spst 369719370Spst@node N_NOMAP 369819370Spst@section N_NOMAP 369919370Spst 370019370Spst@deffn @code{.stabs} N_NOMAP 370119370Spst@findex N_NOMAP 370219370SpstNo DST map for symbol (according to Ultrix V4.0). I think this means a 370319370Spstvariable has been optimized out. 370419370Spst 370519370Spst@display 370619370Spst name, ,0,type,ignored (stab.def) 370719370Spst@end display 370819370Spst@end deffn 370919370Spst 371019370Spst@node N_M2C 371119370Spst@section N_M2C 371219370Spst 371319370Spst@deffn @code{.stabs} N_M2C 371419370Spst@findex N_M2C 371519370SpstModula-2 compilation unit. 371619370Spst 371719370Spst@example 371819370Spst"string" -> "unit_name,unit_time_stamp[,code_time_stamp]" 371919370Spstdesc -> unit_number 372019370Spstvalue -> 0 (main unit) 372119370Spst 1 (any other unit) 372219370Spst@end example 372319370Spst 372419370SpstSee @cite{Dbx and Dbxtool Interfaces}, 2nd edition, by Sun, 1988, for 372519370Spstmore information. 372619370Spst 372719370Spst@end deffn 372819370Spst 372919370Spst@node N_BROWS 373019370Spst@section N_BROWS 373119370Spst 373219370Spst@deffn @code{.stabs} N_BROWS 373319370Spst@findex N_BROWS 373419370SpstSun source code browser, path to @file{.cb} file 373519370Spst 373619370Spst<<?>> 373719370Spst"path to associated @file{.cb} file" 373819370Spst 373919370SpstNote: N_BROWS has the same value as N_BSLINE. 374019370Spst@end deffn 374119370Spst 374219370Spst@node N_DEFD 374319370Spst@section N_DEFD 374419370Spst 374519370Spst@deffn @code{.stabn} N_DEFD 374619370Spst@findex N_DEFD 374719370SpstGNU Modula2 definition module dependency. 374819370Spst 374919370SpstGNU Modula-2 definition module dependency. The value is the 375019370Spstmodification time of the definition file. The other field is non-zero 375119370Spstif it is imported with the GNU M2 keyword @code{%INITIALIZE}. Perhaps 375219370Spst@code{N_M2C} can be used if there are enough empty fields? 375319370Spst@end deffn 375419370Spst 375519370Spst@node N_EHDECL 375619370Spst@section N_EHDECL 375719370Spst 375819370Spst@deffn @code{.stabs} N_EHDECL 375919370Spst@findex N_EHDECL 3760130809SmarcelGNU C@t{++} exception variable <<?>>. 376119370Spst 376219370Spst"@var{string} is variable name" 376319370Spst 376419370SpstNote: conflicts with @code{N_MOD2}. 376519370Spst@end deffn 376619370Spst 376719370Spst@node N_MOD2 376819370Spst@section N_MOD2 376919370Spst 377019370Spst@deffn @code{.stab?} N_MOD2 377119370Spst@findex N_MOD2 377219370SpstModula2 info "for imc" (according to Ultrix V4.0) 377319370Spst 377419370SpstNote: conflicts with @code{N_EHDECL} <<?>> 377519370Spst@end deffn 377619370Spst 377719370Spst@node N_CATCH 377819370Spst@section N_CATCH 377919370Spst 378019370Spst@deffn @code{.stabn} N_CATCH 378119370Spst@findex N_CATCH 3782130809SmarcelGNU C@t{++} @code{catch} clause 378319370Spst 3784130809SmarcelGNU C@t{++} @code{catch} clause. The value is its address. The desc field 378519370Spstis nonzero if this entry is immediately followed by a @code{CAUGHT} stab 378619370Spstsaying what exception was caught. Multiple @code{CAUGHT} stabs means 378719370Spstthat multiple exceptions can be caught here. If desc is 0, it means all 378819370Spstexceptions are caught here. 378919370Spst@end deffn 379019370Spst 379119370Spst@node N_SSYM 379219370Spst@section N_SSYM 379319370Spst 379419370Spst@deffn @code{.stabn} N_SSYM 379519370Spst@findex N_SSYM 379619370SpstStructure or union element. 379719370Spst 379819370SpstThe value is the offset in the structure. 379919370Spst 380019370Spst<<?looking at structs and unions in C I didn't see these>> 380119370Spst@end deffn 380219370Spst 380319370Spst@node N_SCOPE 380419370Spst@section N_SCOPE 380519370Spst 380619370Spst@deffn @code{.stab?} N_SCOPE 380719370Spst@findex N_SCOPE 380819370SpstModula2 scope information (Sun linker) 380919370Spst<<?>> 381019370Spst@end deffn 381119370Spst 381219370Spst@node Gould 381319370Spst@section Non-base registers on Gould systems 381419370Spst 381519370Spst@deffn @code{.stab?} N_NBTEXT 381619370Spst@deffnx @code{.stab?} N_NBDATA 381719370Spst@deffnx @code{.stab?} N_NBBSS 381819370Spst@deffnx @code{.stab?} N_NBSTS 381919370Spst@deffnx @code{.stab?} N_NBLCS 382019370Spst@findex N_NBTEXT 382119370Spst@findex N_NBDATA 382219370Spst@findex N_NBBSS 382319370Spst@findex N_NBSTS 382419370Spst@findex N_NBLCS 382519370SpstThese are used on Gould systems for non-base registers syms. 382619370Spst 382719370SpstHowever, the following values are not the values used by Gould; they are 382819370Spstthe values which GNU has been documenting for these values for a long 382919370Spsttime, without actually checking what Gould uses. I include these values 383019370Spstonly because perhaps some someone actually did something with the GNU 383119370Spstinformation (I hope not, why GNU knowingly assigned wrong values to 383219370Spstthese in the header file is a complete mystery to me). 383319370Spst 383419370Spst@example 383519370Spst240 0xf0 N_NBTEXT ?? 383619370Spst242 0xf2 N_NBDATA ?? 383719370Spst244 0xf4 N_NBBSS ?? 383819370Spst246 0xf6 N_NBSTS ?? 383919370Spst248 0xf8 N_NBLCS ?? 384019370Spst@end example 384119370Spst@end deffn 384219370Spst 384319370Spst@node N_LENG 384419370Spst@section N_LENG 384519370Spst 384619370Spst@deffn @code{.stabn} N_LENG 384719370Spst@findex N_LENG 384819370SpstSecond symbol entry containing a length-value for the preceding entry. 384919370SpstThe value is the length. 385019370Spst@end deffn 385119370Spst 385219370Spst@node Questions 385319370Spst@appendix Questions and Anomalies 385419370Spst 385519370Spst@itemize @bullet 385619370Spst@item 385719370Spst@c I think this is changed in GCC 2.4.5 to put the line number there. 385819370SpstFor GNU C stabs defining local and global variables (@code{N_LSYM} and 385919370Spst@code{N_GSYM}), the desc field is supposed to contain the source 386019370Spstline number on which the variable is defined. In reality the desc 386119370Spstfield is always 0. (This behavior is defined in @file{dbxout.c} and 386219370Spstputting a line number in desc is controlled by @samp{#ifdef 386319370SpstWINNING_GDB}, which defaults to false). GDB supposedly uses this 386419370Spstinformation if you say @samp{list @var{var}}. In reality, @var{var} can 386519370Spstbe a variable defined in the program and GDB says @samp{function 386619370Spst@var{var} not defined}. 386719370Spst 386819370Spst@item 386919370SpstIn GNU C stabs, there seems to be no way to differentiate tag types: 387019370Spststructures, unions, and enums (symbol descriptor @samp{T}) and typedefs 387119370Spst(symbol descriptor @samp{t}) defined at file scope from types defined locally 387219370Spstto a procedure or other more local scope. They all use the @code{N_LSYM} 387398948Sobrienstab type. Types defined at procedure scope are emitted after the 387419370Spst@code{N_RBRAC} of the preceding function and before the code of the 387519370Spstprocedure in which they are defined. This is exactly the same as 387619370Spsttypes defined in the source file between the two procedure bodies. 387798948SobrienGDB over-compensates by placing all types in block #1, the block for 387819370Spstsymbols of file scope. This is true for default, @samp{-ansi} and 387919370Spst@samp{-traditional} compiler options. (Bugs gcc/1063, gdb/1066.) 388019370Spst 388119370Spst@item 388219370SpstWhat ends the procedure scope? Is it the proc block's @code{N_RBRAC} or the 388319370Spstnext @code{N_FUN}? (I believe its the first.) 388419370Spst@end itemize 388519370Spst 388619370Spst@node Stab Sections 388719370Spst@appendix Using Stabs in Their Own Sections 388819370Spst 388919370SpstMany object file formats allow tools to create object files with custom 389019370Spstsections containing any arbitrary data. For any such object file 389119370Spstformat, stabs can be embedded in special sections. This is how stabs 389219370Spstare used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs 389319370Spstare used with COFF. 389419370Spst 389519370Spst@menu 389619370Spst* Stab Section Basics:: How to embed stabs in sections 389719370Spst* ELF Linker Relocation:: Sun ELF hacks 389819370Spst@end menu 389919370Spst 390019370Spst@node Stab Section Basics 390119370Spst@appendixsec How to Embed Stabs in Sections 390219370Spst 390319370SpstThe assembler creates two custom sections, a section named @code{.stab} 390419370Spstwhich contains an array of fixed length structures, one struct per stab, 390519370Spstand a section named @code{.stabstr} containing all the variable length 390619370Spststrings that are referenced by stabs in the @code{.stab} section. The 390719370Spstbyte order of the stabs binary data depends on the object file format. 390819370SpstFor ELF, it matches the byte order of the ELF file itself, as determined 390919370Spstfrom the @code{EI_DATA} field in the @code{e_ident} member of the ELF 391019370Spstheader. For SOM, it is always big-endian (is this true??? FIXME). For 391119370SpstCOFF, it matches the byte order of the COFF headers. The meaning of the 391219370Spstfields is the same as for a.out (@pxref{Symbol Table Format}), except 391319370Spstthat the @code{n_strx} field is relative to the strings for the current 391419370Spstcompilation unit (which can be found using the synthetic N_UNDF stab 391519370Spstdescribed below), rather than the entire string table. 391619370Spst 391719370SpstThe first stab in the @code{.stab} section for each compilation unit is 391819370Spstsynthetic, generated entirely by the assembler, with no corresponding 391919370Spst@code{.stab} directive as input to the assembler. This stab contains 392019370Spstthe following fields: 392119370Spst 392219370Spst@table @code 392319370Spst@item n_strx 392419370SpstOffset in the @code{.stabstr} section to the source filename. 392519370Spst 392619370Spst@item n_type 392719370Spst@code{N_UNDF}. 392819370Spst 392919370Spst@item n_other 393019370SpstUnused field, always zero. 393119370SpstThis may eventually be used to hold overflows from the count in 393219370Spstthe @code{n_desc} field. 393319370Spst 393419370Spst@item n_desc 393519370SpstCount of upcoming symbols, i.e., the number of remaining stabs for this 393619370Spstsource file. 393719370Spst 393819370Spst@item n_value 393919370SpstSize of the string table fragment associated with this source file, in 394019370Spstbytes. 394119370Spst@end table 394219370Spst 394319370SpstThe @code{.stabstr} section always starts with a null byte (so that string 394419370Spstoffsets of zero reference a null string), followed by random length strings, 394519370Spsteach of which is null byte terminated. 394619370Spst 394719370SpstThe ELF section header for the @code{.stab} section has its 394819370Spst@code{sh_link} member set to the section number of the @code{.stabstr} 394919370Spstsection, and the @code{.stabstr} section has its ELF section 395019370Spstheader @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a 395119370Spststring table. SOM and COFF have no way of linking the sections together 395219370Spstor marking them as string tables. 395319370Spst 395446289SdfrFor COFF, the @code{.stab} and @code{.stabstr} sections may be simply 395519370Spstconcatenated by the linker. GDB then uses the @code{n_desc} fields to 395619370Spstfigure out the extent of the original sections. Similarly, the 395719370Spst@code{n_value} fields of the header symbols are added together in order 395819370Spstto get the actual position of the strings in a desired @code{.stabstr} 395946289Sdfrsection. Although this design obviates any need for the linker to 396046289Sdfrrelocate or otherwise manipulate @code{.stab} and @code{.stabstr} 396146289Sdfrsections, it also requires some care to ensure that the offsets are 396246289Sdfrcalculated correctly. For instance, if the linker were to pad in 396346289Sdfrbetween the @code{.stabstr} sections before concatenating, then the 396446289Sdfroffsets to strings in the middle of the executable's @code{.stabstr} 396546289Sdfrsection would be wrong. 396619370Spst 396746289SdfrThe GNU linker is able to optimize stabs information by merging 396846289Sdfrduplicate strings and removing duplicate header file information 396946289Sdfr(@pxref{Include Files}). When some versions of the GNU linker optimize 397046289Sdfrstabs in sections, they remove the leading @code{N_UNDF} symbol and 397146289Sdfrarranges for all the @code{n_strx} fields to be relative to the start of 397246289Sdfrthe @code{.stabstr} section. 397346289Sdfr 397419370Spst@node ELF Linker Relocation 397519370Spst@appendixsec Having the Linker Relocate Stabs in ELF 397619370Spst 397719370SpstThis section describes some Sun hacks for Stabs in ELF; it does not 397819370Spstapply to COFF or SOM. 397919370Spst 398019370SpstTo keep linking fast, you don't want the linker to have to relocate very 398119370Spstmany stabs. Making sure this is done for @code{N_SLINE}, 398219370Spst@code{N_RBRAC}, and @code{N_LBRAC} stabs is the most important thing 398319370Spst(see the descriptions of those stabs for more information). But Sun's 398419370Spststabs in ELF has taken this further, to make all addresses in the 398519370Spst@code{n_value} field (functions and static variables) relative to the 398619370Spstsource file. For the @code{N_SO} symbol itself, Sun simply omits the 398719370Spstaddress. To find the address of each section corresponding to a given 398819370Spstsource file, the compiler puts out symbols giving the address of each 398919370Spstsection for a given source file. Since these are ELF (not stab) 399019370Spstsymbols, the linker relocates them correctly without having to touch the 399119370Spststabs section. They are named @code{Bbss.bss} for the bss section, 399219370Spst@code{Ddata.data} for the data section, and @code{Drodata.rodata} for 399319370Spstthe rodata section. For the text section, there is no such symbol (but 399419370Spstthere should be, see below). For an example of how these symbols work, 399519370Spst@xref{Stab Section Transformations}. GCC does not provide these symbols; 399619370Spstit instead relies on the stabs getting relocated. Thus addresses which 399719370Spstwould normally be relative to @code{Bbss.bss}, etc., are already 399819370Spstrelocated. The Sun linker provided with Solaris 2.2 and earlier 399919370Spstrelocates stabs using normal ELF relocation information, as it would do 400019370Spstfor any section. Sun has been threatening to kludge their linker to not 400119370Spstdo this (to speed up linking), even though the correct way to avoid 400219370Spsthaving the linker do these relocations is to have the compiler no longer 400319370Spstoutput relocatable values. Last I heard they had been talked out of the 400419370Spstlinker kludge. See Sun point patch 101052-01 and Sun bug 1142109. With 400519370Spstthe Sun compiler this affects @samp{S} symbol descriptor stabs 400619370Spst(@pxref{Statics}) and functions (@pxref{Procedures}). In the latter 400719370Spstcase, to adopt the clean solution (making the value of the stab relative 400819370Spstto the start of the compilation unit), it would be necessary to invent a 400919370Spst@code{Ttext.text} symbol, analogous to the @code{Bbss.bss}, etc., 401019370Spstsymbols. I recommend this rather than using a zero value and getting 401119370Spstthe address from the ELF symbols. 401219370Spst 401319370SpstFinding the correct @code{Bbss.bss}, etc., symbol is difficult, because 401419370Spstthe linker simply concatenates the @code{.stab} sections from each 401519370Spst@file{.o} file without including any information about which part of a 401619370Spst@code{.stab} section comes from which @file{.o} file. The way GDB does 401719370Spstthis is to look for an ELF @code{STT_FILE} symbol which has the same 401819370Spstname as the last component of the file name from the @code{N_SO} symbol 401919370Spstin the stabs (for example, if the file name is @file{../../gdb/main.c}, 402019370Spstit looks for an ELF @code{STT_FILE} symbol named @code{main.c}). This 402119370Spstloses if different files have the same name (they could be in different 402219370Spstdirectories, a library could have been copied from one system to 402319370Spstanother, etc.). It would be much cleaner to have the @code{Bbss.bss} 402419370Spstsymbols in the stabs themselves. Having the linker relocate them there 402519370Spstis no more work than having the linker relocate ELF symbols, and it 402619370Spstsolves the problem of having to associate the ELF and stab symbols. 402719370SpstHowever, no one has yet designed or implemented such a scheme. 402819370Spst 4029130809Smarcel@raisesections 4030130809Smarcel@include fdl.texi 4031130809Smarcel@lowersections 4032130809Smarcel 403319370Spst@node Symbol Types Index 403419370Spst@unnumbered Symbol Types Index 403519370Spst 403619370Spst@printindex fn 403719370Spst 403898948Sobrien@c TeX can handle the contents at the start but makeinfo 3.12 can not 403998948Sobrien@ifinfo 404019370Spst@contents 404198948Sobrien@end ifinfo 404298948Sobrien@ifhtml 404398948Sobrien@contents 404498948Sobrien@end ifhtml 404598948Sobrien 404619370Spst@bye 4047