diff options
Diffstat (limited to 'gdb/doc/stabs.texinfo')
| -rw-r--r-- | gdb/doc/stabs.texinfo | 4019 |
1 files changed, 4019 insertions, 0 deletions
diff --git a/gdb/doc/stabs.texinfo b/gdb/doc/stabs.texinfo new file mode 100644 index 0000000..a4f0bc9 --- /dev/null +++ b/gdb/doc/stabs.texinfo @@ -0,0 +1,4019 @@ +\input texinfo +@setfilename stabs.info + +@c @finalout + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Stabs: (stabs). The "stabs" debugging information format. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +This document describes the stabs debugging symbol tables. + +Copyright 1992, 93, 94, 95, 97, 1998 Free Software Foundation, Inc. +Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon, +and David MacKenzie. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy or distribute modified versions of this +manual under the terms of the GPL (for which purpose this text may be +regarded as a program in the language TeX). +@end ifinfo + +@setchapternewpage odd +@settitle STABS +@titlepage +@title The ``stabs'' debug format +@author Julia Menapace, Jim Kingdon, David MacKenzie +@author Cygnus Support +@page +@tex +\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ +\xdef\manvers{\$Revision$} % For use in headers, footers too +{\parskip=0pt +\hfill Cygnus Support\par +\hfill \manvers\par +\hfill \TeX{}info \texinfoversion\par +} +@end tex + +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 93, 94, 95, 97, 1998 Free Software Foundation, Inc. +Contributed by Cygnus Support. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@end titlepage + +@ifinfo +@node Top +@top The "stabs" representation of debugging information + +This document describes the stabs debugging format. + +@menu +* Overview:: Overview of stabs +* Program Structure:: Encoding of the structure of the program +* Constants:: Constants +* Variables:: +* Types:: Type definitions +* Symbol Tables:: Symbol information in symbol tables +* Cplusplus:: Stabs specific to C++ +* Stab Types:: Symbol types in a.out files +* Symbol Descriptors:: Table of symbol descriptors +* Type Descriptors:: Table of type descriptors +* Expanded Reference:: Reference information by stab type +* Questions:: Questions and anomolies +* Stab Sections:: In some object file formats, stabs are + in sections. +* Symbol Types Index:: Index of symbolic stab symbol type names. +@end menu +@end ifinfo + + +@node Overview +@chapter Overview of Stabs + +@dfn{Stabs} refers to a format for information that describes a program +to a debugger. This format was apparently invented by +Peter Kessler at +the University of California at Berkeley, for the @code{pdx} Pascal +debugger; the format has spread widely since then. + +This document is one of the few published sources of documentation on +stabs. It is believed to be comprehensive for stabs used by C. The +lists of symbol descriptors (@pxref{Symbol Descriptors}) and type +descriptors (@pxref{Type Descriptors}) are believed to be completely +comprehensive. Stabs for COBOL-specific features and for variant +records (used by Pascal and Modula-2) are poorly documented here. + +@c FIXME: Need to document all OS9000 stuff in GDB; see all references +@c to os9k_stabs in stabsread.c. + +Other sources of information on stabs are @cite{Dbx and Dbxtool +Interfaces}, 2nd edition, by Sun, 1988, and @cite{AIX Version 3.2 Files +Reference}, Fourth Edition, September 1992, "dbx Stabstring Grammar" in +the a.out section, page 2-31. This document is believed to incorporate +the information from those two sources except where it explicitly directs +you to them for more information. + +@menu +* Flow:: Overview of debugging information flow +* Stabs Format:: Overview of stab format +* String Field:: The string field +* C Example:: A simple example in C source +* Assembly Code:: The simple example at the assembly level +@end menu + +@node Flow +@section Overview of Debugging Information Flow + +The GNU C compiler compiles C source in a @file{.c} file into assembly +language in a @file{.s} file, which the assembler translates into +a @file{.o} file, which the linker combines with other @file{.o} files and +libraries to produce an executable file. + +With the @samp{-g} option, GCC puts in the @file{.s} file additional +debugging information, which is slightly transformed by the assembler +and linker, and carried through into the final executable. This +debugging information describes features of the source file like line +numbers, the types and scopes of variables, and function names, +parameters, and scopes. + +For some object file formats, the debugging information is encapsulated +in assembler directives known collectively as @dfn{stab} (symbol table) +directives, which are interspersed with the generated code. Stabs are +the native format for debugging information in the a.out and XCOFF +object file formats. The GNU tools can also emit stabs in the COFF and +ECOFF object file formats. + +The assembler adds the information from stabs to the symbol information +it places by default in the symbol table and the string table of the +@file{.o} file it is building. The linker consolidates the @file{.o} +files into one executable file, with one symbol table and one string +table. Debuggers use the symbol and string tables in the executable as +a source of debugging information about the program. + +@node Stabs Format +@section Overview of Stab Format + +There are three overall formats for stab assembler directives, +differentiated by the first word of the stab. The name of the directive +describes which combination of four possible data fields follows. It is +either @code{.stabs} (string), @code{.stabn} (number), or @code{.stabd} +(dot). IBM's XCOFF assembler uses @code{.stabx} (and some other +directives such as @code{.file} and @code{.bi}) instead of +@code{.stabs}, @code{.stabn} or @code{.stabd}. + +The overall format of each class of stab is: + +@example +.stabs "@var{string}",@var{type},@var{other},@var{desc},@var{value} +.stabn @var{type},@var{other},@var{desc},@var{value} +.stabd @var{type},@var{other},@var{desc} +.stabx "@var{string}",@var{value},@var{type},@var{sdb-type} +@end example + +@c what is the correct term for "current file location"? My AIX +@c assembler manual calls it "the value of the current location counter". +For @code{.stabn} and @code{.stabd}, there is no @var{string} (the +@code{n_strx} field is zero; see @ref{Symbol Tables}). For +@code{.stabd}, the @var{value} field is implicit and has the value of +the current file location. For @code{.stabx}, the @var{sdb-type} field +is unused for stabs and can always be set to zero. The @var{other} +field is almost always unused and can be set to zero. + +The number in the @var{type} field gives some basic information about +which type of stab this is (or whether it @emph{is} a stab, as opposed +to an ordinary symbol). Each valid type number defines a different stab +type; further, the stab type defines the exact interpretation of, and +possible values for, any remaining @var{string}, @var{desc}, or +@var{value} fields present in the stab. @xref{Stab Types}, for a list +in numeric order of the valid @var{type} field values for stab directives. + +@node String Field +@section The String Field + +For most stabs the string field holds the meat of the +debugging information. The flexible nature of this field +is what makes stabs extensible. For some stab types the string field +contains only a name. For other stab types the contents can be a great +deal more complex. + +The overall format of the string field for most stab types is: + +@example +"@var{name}:@var{symbol-descriptor} @var{type-information}" +@end example + +@var{name} is the name of the symbol represented by the stab; it can +contain a pair of colons (@pxref{Nested Symbols}). @var{name} can be +omitted, which means the stab represents an unnamed object. For +example, @samp{:t10=*2} defines type 10 as a pointer to type 2, but does +not give the type a name. Omitting the @var{name} field is supported by +AIX dbx and GDB after about version 4.8, but not other debuggers. GCC +sometimes uses a single space as the name instead of omitting the name +altogether; apparently that is supported by most debuggers. + +The @var{symbol-descriptor} following the @samp{:} is an alphabetic +character that tells more specifically what kind of symbol the stab +represents. If the @var{symbol-descriptor} is omitted, but type +information follows, then the stab represents a local variable. For a +list of symbol descriptors, see @ref{Symbol Descriptors}. The @samp{c} +symbol descriptor is an exception in that it is not followed by type +information. @xref{Constants}. + +@var{type-information} is either a @var{type-number}, or +@samp{@var{type-number}=}. A @var{type-number} alone is a type +reference, referring directly to a type that has already been defined. + +The @samp{@var{type-number}=} form is a type definition, where the +number represents a new type which is about to be defined. The type +definition may refer to other types by number, and those type numbers +may be followed by @samp{=} and nested definitions. Also, the Lucid +compiler will repeat @samp{@var{type-number}=} more than once if it +wants to define several type numbers at once. + +In a type definition, if the character that follows the equals sign is +non-numeric then it is a @var{type-descriptor}, and tells what kind of +type is about to be defined. Any other values following the +@var{type-descriptor} vary, depending on the @var{type-descriptor}. +@xref{Type Descriptors}, for a list of @var{type-descriptor} values. If +a number follows the @samp{=} then the number is a @var{type-reference}. +For a full description of types, @ref{Types}. + +A @var{type-number} is often a single number. The GNU and Sun tools +additionally permit a @var{type-number} to be a pair +(@var{file-number},@var{filetype-number}) (the parentheses appear in the +string, and serve to distinguish the two cases). The @var{file-number} +is a number starting with 1 which is incremented for each seperate +source file in the compilation (e.g., in C, each header file gets a +different number). The @var{filetype-number} is a number starting with +1 which is incremented for each new type defined in the file. +(Separating the file number and the type number permits the +@code{N_BINCL} optimization to succeed more often; see @ref{Include +Files}). + +There is an AIX extension for type attributes. Following the @samp{=} +are any number of type attributes. Each one starts with @samp{@@} and +ends with @samp{;}. Debuggers, including AIX's dbx and GDB 4.10, skip +any type attributes they do not recognize. GDB 4.9 and other versions +of dbx may not do this. Because of a conflict with C++ +(@pxref{Cplusplus}), new attributes should not be defined which begin +with a digit, @samp{(}, or @samp{-}; GDB may be unable to distinguish +those from the C++ type descriptor @samp{@@}. The attributes are: + +@table @code +@item a@var{boundary} +@var{boundary} is an integer specifying the alignment. I assume it +applies to all variables of this type. + +@item p@var{integer} +Pointer class (for checking). Not sure what this means, or how +@var{integer} is interpreted. + +@item P +Indicate this is a packed type, meaning that structure fields or array +elements are placed more closely in memory, to save memory at the +expense of speed. + +@item s@var{size} +Size in bits of a variable of this type. This is fully supported by GDB +4.11 and later. + +@item S +Indicate that this type is a string instead of an array of characters, +or a bitstring instead of a set. It doesn't change the layout of the +data being represented, but does enable the debugger to know which type +it is. +@end table + +All of this can make the string field quite long. All versions of GDB, +and some versions of dbx, can handle arbitrarily long strings. But many +versions of dbx (or assemblers or linkers, I'm not sure which) +cretinously limit the strings to about 80 characters, so compilers which +must work with such systems need to split the @code{.stabs} directive +into several @code{.stabs} directives. Each stab duplicates every field +except the string field. The string field of every stab except the last +is marked as continued with a backslash at the end (in the assembly code +this may be written as a double backslash, depending on the assembler). +Removing the backslashes and concatenating the string fields of each +stab produces the original, long string. Just to be incompatible (or so +they don't have to worry about what the assembler does with +backslashes), AIX can use @samp{?} instead of backslash. + +@node C Example +@section A Simple Example in C Source + +To get the flavor of how stabs describe source information for a C +program, let's look at the simple program: + +@example +main() +@{ + printf("Hello world"); +@} +@end example + +When compiled with @samp{-g}, the program above yields the following +@file{.s} file. Line numbers have been added to make it easier to refer +to parts of the @file{.s} file in the description of the stabs that +follows. + +@node Assembly Code +@section The Simple Example at the Assembly Level + +This simple ``hello world'' example demonstrates several of the stab +types used to describe C language source files. + +@example +1 gcc2_compiled.: +2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 +3 .stabs "hello.c",100,0,0,Ltext0 +4 .text +5 Ltext0: +6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 +7 .stabs "char:t2=r2;0;127;",128,0,0,0 +8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0 +9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 +10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0 +11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0 +12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0 +13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0 +14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0 +15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0 +16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0 +17 .stabs "float:t12=r1;4;0;",128,0,0,0 +18 .stabs "double:t13=r1;8;0;",128,0,0,0 +19 .stabs "long double:t14=r1;8;0;",128,0,0,0 +20 .stabs "void:t15=15",128,0,0,0 +21 .align 4 +22 LC0: +23 .ascii "Hello, world!\12\0" +24 .align 4 +25 .global _main +26 .proc 1 +27 _main: +28 .stabn 68,0,4,LM1 +29 LM1: +30 !#PROLOGUE# 0 +31 save %sp,-136,%sp +32 !#PROLOGUE# 1 +33 call ___main,0 +34 nop +35 .stabn 68,0,5,LM2 +36 LM2: +37 LBB2: +38 sethi %hi(LC0),%o1 +39 or %o1,%lo(LC0),%o0 +40 call _printf,0 +41 nop +42 .stabn 68,0,6,LM3 +43 LM3: +44 LBE2: +45 .stabn 68,0,6,LM4 +46 LM4: +47 L1: +48 ret +49 restore +50 .stabs "main:F1",36,0,0,_main +51 .stabn 192,0,0,LBB2 +52 .stabn 224,0,0,LBE2 +@end example + +@node Program Structure +@chapter Encoding the Structure of the Program + +The elements of the program structure that stabs encode include the name +of the main function, the names of the source and include files, the +line numbers, procedure names and types, and the beginnings and ends of +blocks of code. + +@menu +* Main Program:: Indicate what the main program is +* Source Files:: The path and name of the source file +* Include Files:: Names of include files +* Line Numbers:: +* Procedures:: +* Nested Procedures:: +* Block Structure:: +* Alternate Entry Points:: Entering procedures except at the beginning. +@end menu + +@node Main Program +@section Main Program + +@findex N_MAIN +Most languages allow the main program to have any name. The +@code{N_MAIN} stab type tells the debugger the name that is used in this +program. Only the string field is significant; it is the name of +a function which is the main program. Most C compilers do not use this +stab (they expect the debugger to assume that the name is @code{main}), +but some C compilers emit an @code{N_MAIN} stab for the @code{main} +function. I'm not sure how XCOFF handles this. + +@node Source Files +@section Paths and Names of the Source Files + +@findex N_SO +Before any other stabs occur, there must be a stab specifying the source +file. This information is contained in a symbol of stab type +@code{N_SO}; the string field contains the name of the file. The +value of the symbol is the start address of the portion of the +text section corresponding to that file. + +With the Sun Solaris2 compiler, the desc field contains a +source-language code. +@c Do the debuggers use it? What are the codes? -djm + +Some compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also +include the directory in which the source was compiled, in a second +@code{N_SO} symbol preceding the one containing the file name. This +symbol can be distinguished by the fact that it ends in a slash. Code +from the @code{cfront} C++ compiler can have additional @code{N_SO} symbols for +nonexistent source files after the @code{N_SO} for the real source file; +these are believed to contain no useful information. + +For example: + +@example +.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 # @r{100 is N_SO} +.stabs "hello.c",100,0,0,Ltext0 + .text +Ltext0: +@end example + +@findex C_FILE +Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler +directive which assembles to a @code{C_FILE} symbol; explaining this in +detail is outside the scope of this document. + +@c FIXME: Exactly when should the empty N_SO be used? Why? +If it is useful to indicate the end of a source file, this is done with +an @code{N_SO} symbol with an empty string for the name. The value is +the address of the end of the text section for the file. For some +systems, there is no indication of the end of a source file, and you +just need to figure it ended when you see an @code{N_SO} for a different +source file, or a symbol ending in @code{.o} (which at least some +linkers insert to mark the start of a new @code{.o} file). + +@node Include Files +@section Names of Include Files + +There are several schemes for dealing with include files: the +traditional @code{N_SOL} approach, Sun's @code{N_BINCL} approach, and the +XCOFF @code{C_BINCL} approach (which despite the similar name has little in +common with @code{N_BINCL}). + +@findex N_SOL +An @code{N_SOL} symbol specifies which include file subsequent symbols +refer to. The string field is the name of the file and the value is the +text address corresponding to the end of the previous include file and +the start of this one. To specify the main source file again, use an +@code{N_SOL} symbol with the name of the main source file. + +@findex N_BINCL +@findex N_EINCL +@findex N_EXCL +The @code{N_BINCL} approach works as follows. An @code{N_BINCL} symbol +specifies the start of an include file. In an object file, only the +string is significant; the linker puts data into some of the other +fields. The end of the include file is marked by an @code{N_EINCL} +symbol (which has no string field). In an object file, there is no +significant data in the @code{N_EINCL} symbol. @code{N_BINCL} and +@code{N_EINCL} can be nested. + +If the linker detects that two source files have identical stabs between +an @code{N_BINCL} and @code{N_EINCL} pair (as will generally be the case +for a header file), then it only puts out the stabs once. Each +additional occurance is replaced by an @code{N_EXCL} symbol. I believe +the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only +ones which supports this feature. + +A linker which supports this feature will set the value of a +@code{N_BINCL} symbol to the total of all the characters in the stabs +strings included in the header file, omitting any file numbers. The +value of an @code{N_EXCL} symbol is the same as the value of the +@code{N_BINCL} symbol it replaces. This information can be used to +match up @code{N_EXCL} and @code{N_BINCL} symbols which have the same +filename. The @code{N_EINCL} value, and the values of the other and +description fields for all three, appear to always be zero. + +@findex C_BINCL +@findex C_EINCL +For the start of an include file in XCOFF, use the @file{.bi} assembler +directive, which generates a @code{C_BINCL} symbol. A @file{.ei} +directive, which generates a @code{C_EINCL} symbol, denotes the end of +the include file. Both directives are followed by the name of the +source file in quotes, which becomes the string for the symbol. +The value of each symbol, produced automatically by the assembler +and linker, is the offset into the executable of the beginning +(inclusive, as you'd expect) or end (inclusive, as you would not expect) +of the portion of the COFF line table that corresponds to this include +file. @code{C_BINCL} and @code{C_EINCL} do not nest. + +@node Line Numbers +@section Line Numbers + +@findex N_SLINE +An @code{N_SLINE} symbol represents the start of a source line. The +desc field contains the line number and the value contains the code +address for the start of that source line. On most machines the address +is absolute; for stabs in sections (@pxref{Stab Sections}), it is +relative to the function in which the @code{N_SLINE} symbol occurs. + +@findex N_DSLINE +@findex N_BSLINE +GNU documents @code{N_DSLINE} and @code{N_BSLINE} symbols for line +numbers in the data or bss segments, respectively. They are identical +to @code{N_SLINE} but are relocated differently by the linker. They +were intended to be used to describe the source location of a variable +declaration, but I believe that GCC2 actually puts the line number in +the desc field of the stab for the variable itself. GDB has been +ignoring these symbols (unless they contain a string field) since +at least GDB 3.5. + +For single source lines that generate discontiguous code, such as flow +of control statements, there may be more than one line number entry for +the same source line. In this case there is a line number entry at the +start of each code range, each with the same line number. + +XCOFF does not use stabs for line numbers. Instead, it uses COFF line +numbers (which are outside the scope of this document). Standard COFF +line numbers cannot deal with include files, but in XCOFF this is fixed +with the @code{C_BINCL} method of marking include files (@pxref{Include +Files}). + +@node Procedures +@section Procedures + +@findex N_FUN, for functions +@findex N_FNAME +@findex N_STSYM, for functions (Sun acc) +@findex N_GSYM, for functions (Sun acc) +All of the following stabs normally use the @code{N_FUN} symbol type. +However, Sun's @code{acc} compiler on SunOS4 uses @code{N_GSYM} and +@code{N_STSYM}, which means that the value of the stab for the function +is useless and the debugger must get the address of the function from +the non-stab symbols instead. On systems where non-stab symbols have +leading underscores, the stabs will lack underscores and the debugger +needs to know about the leading underscore to match up the stab and the +non-stab symbol. BSD Fortran is said to use @code{N_FNAME} with the +same restriction; the value of the symbol is not useful (I'm not sure it +really does use this, because GDB doesn't handle this and no one has +complained). + +@findex C_FUN +A function is represented by an @samp{F} symbol descriptor for a global +(extern) function, and @samp{f} for a static (local) function. For +a.out, the value of the symbol is the address of the start of the +function; it is already relocated. For stabs in ELF, the SunPRO +compiler version 2.0.1 and GCC put out an address which gets relocated +by the linker. In a future release SunPRO is planning to put out zero, +in which case the address can be found from the ELF (non-stab) symbol. +Because looking things up in the ELF symbols would probably be slow, I'm +not sure how to find which symbol of that name is the right one, and +this doesn't provide any way to deal with nested functions, it would +probably be better to make the value of the stab an address relative to +the start of the file, or just absolute. See @ref{ELF Linker +Relocation} for more information on linker relocation of stabs in ELF +files. For XCOFF, the stab uses the @code{C_FUN} storage class and the +value of the stab is meaningless; the address of the function can be +found from the csect symbol (XTY_LD/XMC_PR). + +The type information of the stab represents the return type of the +function; thus @samp{foo:f5} means that foo is a function returning type +5. There is no need to try to get the line number of the start of the +function from the stab for the function; it is in the next +@code{N_SLINE} symbol. + +@c FIXME: verify whether the "I suspect" below is true or not. +Some compilers (such as Sun's Solaris compiler) support an extension for +specifying the types of the arguments. I suspect this extension is not +used for old (non-prototyped) function definitions in C. If the +extension is in use, the type information of the stab for the function +is followed by type information for each argument, with each argument +preceded by @samp{;}. An argument type of 0 means that additional +arguments are being passed, whose types and number may vary (@samp{...} +in ANSI C). GDB has tolerated this extension (parsed the syntax, if not +necessarily used the information) since at least version 4.8; I don't +know whether all versions of dbx tolerate it. The argument types given +here are not redundant with the symbols for the formal parameters +(@pxref{Parameters}); they are the types of the arguments as they are +passed, before any conversions might take place. For example, if a C +function which is declared without a prototype takes a @code{float} +argument, the value is passed as a @code{double} but then converted to a +@code{float}. Debuggers need to use the types given in the arguments +when printing values, but when calling the function they need to use the +types given in the symbol defining the function. + +If the return type and types of arguments of a function which is defined +in another source file are specified (i.e., a function prototype in ANSI +C), traditionally compilers emit no stab; the only way for the debugger +to find the information is if the source file where the function is +defined was also compiled with debugging symbols. As an extension the +Solaris compiler uses symbol descriptor @samp{P} followed by the return +type of the function, followed by the arguments, each preceded by +@samp{;}, as in a stab with symbol descriptor @samp{f} or @samp{F}. +This use of symbol descriptor @samp{P} can be distinguished from its use +for register parameters (@pxref{Register Parameters}) by the fact that it has +symbol type @code{N_FUN}. + +The AIX documentation also defines symbol descriptor @samp{J} as an +internal function. I assume this means a function nested within another +function. It also says symbol descriptor @samp{m} is a module in +Modula-2 or extended Pascal. + +Procedures (functions which do not return values) are represented as +functions returning the @code{void} type in C. I don't see why this couldn't +be used for all languages (inventing a @code{void} type for this purpose if +necessary), but the AIX documentation defines @samp{I}, @samp{P}, and +@samp{Q} for internal, global, and static procedures, respectively. +These symbol descriptors are unusual in that they are not followed by +type information. + +The following example shows a stab for a function @code{main} which +returns type number @code{1}. The @code{_main} specified for the value +is a reference to an assembler label which is used to fill in the start +address of the function. + +@example +.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} +@end example + +The stab representing a procedure is located immediately following the +code of the procedure. This stab is in turn directly followed by a +group of other stabs describing elements of the procedure. These other +stabs describe the procedure's parameters, its block local variables, and +its block structure. + +If functions can appear in different sections, then the debugger may not +be able to find the end of a function. Recent versions of GCC will mark +the end of a function with an @code{N_FUN} symbol with an empty string +for the name. The value is the address of the end of the current +function. Without such a symbol, there is no indication of the address +of the end of a function, and you must assume that it ended at the +starting address of the next function or at the end of the text section +for the program. + +@node Nested Procedures +@section Nested Procedures + +For any of the symbol descriptors representing procedures, after the +symbol descriptor and the type information is optionally a scope +specifier. This consists of a comma, the name of the procedure, another +comma, and the name of the enclosing procedure. The first name is local +to the scope specified, and seems to be redundant with the name of the +symbol (before the @samp{:}). This feature is used by GCC, and +presumably Pascal, Modula-2, etc., compilers, for nested functions. + +If procedures are nested more than one level deep, only the immediately +containing scope is specified. For example, this code: + +@example +int +foo (int x) +@{ + int bar (int y) + @{ + int baz (int z) + @{ + return x + y + z; + @} + return baz (x + 2 * y); + @} + return x + bar (3 * x); +@} +@end example + +@noindent +produces the stabs: + +@example +.stabs "baz:f1,baz,bar",36,0,0,_baz.15 # @r{36 is N_FUN} +.stabs "bar:f1,bar,foo",36,0,0,_bar.12 +.stabs "foo:F1",36,0,0,_foo +@end example + +@node Block Structure +@section Block Structure + +@findex N_LBRAC +@findex N_RBRAC +@c For GCC 2.5.8 or so stabs-in-coff, these are absolute instead of +@c function relative (as documented below). But GDB has never been able +@c to deal with that (it had wanted them to be relative to the file, but +@c I just fixed that (between GDB 4.12 and 4.13)), so it is function +@c relative just like ELF and SOM and the below documentation. +The program's block structure is represented by the @code{N_LBRAC} (left +brace) and the @code{N_RBRAC} (right brace) stab types. The variables +defined inside a block precede the @code{N_LBRAC} symbol for most +compilers, including GCC. Other compilers, such as the Convex, Acorn +RISC machine, and Sun @code{acc} compilers, put the variables after the +@code{N_LBRAC} symbol. The values of the @code{N_LBRAC} and +@code{N_RBRAC} symbols are the start and end addresses of the code of +the block, respectively. For most machines, they are relative to the +starting address of this source file. For the Gould NP1, they are +absolute. For stabs in sections (@pxref{Stab Sections}), they are +relative to the function in which they occur. + +The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block +scope of a procedure are located after the @code{N_FUN} stab that +represents the procedure itself. + +Sun documents the desc field of @code{N_LBRAC} and +@code{N_RBRAC} symbols as containing the nesting level of the block. +However, dbx seems to not care, and GCC always sets desc to +zero. + +@findex .bb +@findex .be +@findex C_BLOCK +For XCOFF, block scope is indicated with @code{C_BLOCK} symbols. If the +name of the symbol is @samp{.bb}, then it is the beginning of the block; +if the name of the symbol is @samp{.be}; it is the end of the block. + +@node Alternate Entry Points +@section Alternate Entry Points + +@findex N_ENTRY +@findex C_ENTRY +Some languages, like Fortran, have the ability to enter procedures at +some place other than the beginning. One can declare an alternate entry +point. The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN +compiler doesn't use it. According to AIX documentation, only the name +of a @code{C_ENTRY} stab is significant; the address of the alternate +entry point comes from the corresponding external symbol. A previous +revision of this document said that the value of an @code{N_ENTRY} stab +was the address of the alternate entry point, but I don't know the +source for that information. + +@node Constants +@chapter Constants + +The @samp{c} symbol descriptor indicates that this stab represents a +constant. This symbol descriptor is an exception to the general rule +that symbol descriptors are followed by type information. Instead, it +is followed by @samp{=} and one of the following: + +@table @code +@item b @var{value} +Boolean constant. @var{value} is a numeric value; I assume it is 0 for +false or 1 for true. + +@item c @var{value} +Character constant. @var{value} is the numeric value of the constant. + +@item e @var{type-information} , @var{value} +Constant whose value can be represented as integral. +@var{type-information} is the type of the constant, as it would appear +after a symbol descriptor (@pxref{String Field}). @var{value} is the +numeric value of the constant. GDB 4.9 does not actually get the right +value if @var{value} does not fit in a host @code{int}, but it does not +do anything violent, and future debuggers could be extended to accept +integers of any size (whether unsigned or not). This constant type is +usually documented as being only for enumeration constants, but GDB has +never imposed that restriction; I don't know about other debuggers. + +@item i @var{value} +Integer constant. @var{value} is the numeric value. The type is some +sort of generic integer type (for GDB, a host @code{int}); to specify +the type explicitly, use @samp{e} instead. + +@item r @var{value} +Real constant. @var{value} is the real value, which can be @samp{INF} +(optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet +NaN (not-a-number), or @samp{SNAN} for a signalling NaN. If it is a +normal number the format is that accepted by the C library function +@code{atof}. + +@item s @var{string} +String constant. @var{string} is a string enclosed in either @samp{'} +(in which case @samp{'} characters within the string are represented as +@samp{\'} or @samp{"} (in which case @samp{"} characters within the +string are represented as @samp{\"}). + +@item S @var{type-information} , @var{elements} , @var{bits} , @var{pattern} +Set constant. @var{type-information} is the type of the constant, as it +would appear after a symbol descriptor (@pxref{String Field}). +@var{elements} is the number of elements in the set (does this means +how many bits of @var{pattern} are actually used, which would be +redundant with the type, or perhaps the number of bits set in +@var{pattern}? I don't get it), @var{bits} is the number of bits in the +constant (meaning it specifies the length of @var{pattern}, I think), +and @var{pattern} is a hexadecimal representation of the set. AIX +documentation refers to a limit of 32 bytes, but I see no reason why +this limit should exist. This form could probably be used for arbitrary +constants, not just sets; the only catch is that @var{pattern} should be +understood to be target, not host, byte order and format. +@end table + +The boolean, character, string, and set constants are not supported by +GDB 4.9, but it ignores them. GDB 4.8 and earlier gave an error +message and refused to read symbols from the file containing the +constants. + +The above information is followed by @samp{;}. + +@node Variables +@chapter Variables + +Different types of stabs describe the various ways that variables can be +allocated: on the stack, globally, in registers, in common blocks, +statically, or as arguments to a function. + +@menu +* Stack Variables:: Variables allocated on the stack. +* Global Variables:: Variables used by more than one source file. +* Register Variables:: Variables in registers. +* Common Blocks:: Variables statically allocated together. +* Statics:: Variables local to one source file. +* Based Variables:: Fortran pointer based variables. +* Parameters:: Variables for arguments to functions. +@end menu + +@node Stack Variables +@section Automatic Variables Allocated on the Stack + +If a variable's scope is local to a function and its lifetime is only as +long as that function executes (C calls such variables +@dfn{automatic}), it can be allocated in a register (@pxref{Register +Variables}) or on the stack. + +@findex N_LSYM, for stack variables +@findex C_LSYM +Each variable allocated on the stack has a stab with the symbol +descriptor omitted. Since type information should begin with a digit, +@samp{-}, or @samp{(}, only those characters precluded from being used +for symbol descriptors. However, the Acorn RISC machine (ARM) is said +to get this wrong: it puts out a mere type definition here, without the +preceding @samp{@var{type-number}=}. This is a bad idea; there is no +guarantee that type descriptors are distinct from symbol descriptors. +Stabs for stack variables use the @code{N_LSYM} stab type, or +@code{C_LSYM} for XCOFF. + +The value of the stab is the offset of the variable within the +local variables. On most machines this is an offset from the frame +pointer and is negative. The location of the stab specifies which block +it is defined in; see @ref{Block Structure}. + +For example, the following C code: + +@example +int +main () +@{ + int x; +@} +@end example + +produces the following stabs: + +@example +.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} +.stabs "x:1",128,0,0,-12 # @r{128 is N_LSYM} +.stabn 192,0,0,LBB2 # @r{192 is N_LBRAC} +.stabn 224,0,0,LBE2 # @r{224 is N_RBRAC} +@end example + +@xref{Procedures} for more information on the @code{N_FUN} stab, and +@ref{Block Structure} for more information on the @code{N_LBRAC} and +@code{N_RBRAC} stabs. + +@node Global Variables +@section Global Variables + +@findex N_GSYM +@findex C_GSYM +@c FIXME: verify for sure that it really is C_GSYM on XCOFF +A variable whose scope is not specific to just one source file is +represented by the @samp{G} symbol descriptor. These stabs use the +@code{N_GSYM} stab type (C_GSYM for XCOFF). The type information for +the stab (@pxref{String Field}) gives the type of the variable. + +For example, the following source code: + +@example +char g_foo = 'c'; +@end example + +@noindent +yields the following assembly code: + +@example +.stabs "g_foo:G2",32,0,0,0 # @r{32 is N_GSYM} + .global _g_foo + .data +_g_foo: + .byte 99 +@end example + +The address of the variable represented by the @code{N_GSYM} is not +contained in the @code{N_GSYM} stab. The debugger gets this information +from the external symbol for the global variable. In the example above, +the @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to +produce an external symbol. + +Some compilers, like GCC, output @code{N_GSYM} stabs only once, where +the variable is defined. Other compilers, like SunOS4 /bin/cc, output a +@code{N_GSYM} stab for each compilation unit which references the +variable. + +@node Register Variables +@section Register Variables + +@findex N_RSYM +@findex C_RSYM +@c According to an old version of this manual, AIX uses C_RPSYM instead +@c of C_RSYM. I am skeptical; this should be verified. +Register variables have their own stab type, @code{N_RSYM} +(@code{C_RSYM} for XCOFF), and their own symbol descriptor, @samp{r}. +The stab's value is the number of the register where the variable data +will be stored. +@c .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc) + +AIX defines a separate symbol descriptor @samp{d} for floating point +registers. This seems unnecessary; why not just just give floating +point registers different register numbers? I have not verified whether +the compiler actually uses @samp{d}. + +If the register is explicitly allocated to a global variable, but not +initialized, as in: + +@example +register int g_bar asm ("%g5"); +@end example + +@noindent +then the stab may be emitted at the end of the object file, with +the other bss symbols. + +@node Common Blocks +@section Common Blocks + +A common block is a statically allocated section of memory which can be +referred to by several source files. It may contain several variables. +I believe Fortran is the only language with this feature. + +@findex N_BCOMM +@findex N_ECOMM +@findex C_BCOMM +@findex C_ECOMM +A @code{N_BCOMM} stab begins a common block and an @code{N_ECOMM} stab +ends it. The only field that is significant in these two stabs is the +string, which names a normal (non-debugging) symbol that gives the +address of the common block. According to IBM documentation, only the +@code{N_BCOMM} has the name of the common block (even though their +compiler actually puts it both places). + +@findex N_ECOML +@findex C_ECOML +The stabs for the members of the common block are between the +@code{N_BCOMM} and the @code{N_ECOMM}; the value of each stab is the +offset within the common block of that variable. IBM uses the +@code{C_ECOML} stab type, and there is a corresponding @code{N_ECOML} +stab type, but Sun's Fortran compiler uses @code{N_GSYM} instead. The +variables within a common block use the @samp{V} symbol descriptor (I +believe this is true of all Fortran variables). Other stabs (at least +type declarations using @code{C_DECL}) can also be between the +@code{N_BCOMM} and the @code{N_ECOMM}. + +@node Statics +@section Static Variables + +Initialized static variables are represented by the @samp{S} and +@samp{V} symbol descriptors. @samp{S} means file scope static, and +@samp{V} means procedure scope static. One exception: in XCOFF, IBM's +xlc compiler always uses @samp{V}, and whether it is file scope or not +is distinguished by whether the stab is located within a function. + +@c This is probably not worth mentioning; it is only true on the sparc +@c for `double' variables which although declared const are actually in +@c the data segment (the text segment can't guarantee 8 byte alignment). +@c (although GCC +@c 2.4.5 has a bug in that it uses @code{N_FUN}, so neither dbx nor GDB can +@c find the variables) +@findex N_STSYM +@findex N_LCSYM +@findex N_FUN, for variables +@findex N_ROSYM +In a.out files, @code{N_STSYM} means the data section, @code{N_FUN} +means the text section, and @code{N_LCSYM} means the bss section. For +those systems with a read-only data section separate from the text +section (Solaris), @code{N_ROSYM} means the read-only data section. + +For example, the source lines: + +@example +static const int var_const = 5; +static int var_init = 2; +static int var_noinit; +@end example + +@noindent +yield the following stabs: + +@example +.stabs "var_const:S1",36,0,0,_var_const # @r{36 is N_FUN} +@dots{} +.stabs "var_init:S1",38,0,0,_var_init # @r{38 is N_STSYM} +@dots{} +.stabs "var_noinit:S1",40,0,0,_var_noinit # @r{40 is N_LCSYM} +@end example + +@findex C_STSYM +@findex C_BSTAT +@findex C_ESTAT +In XCOFF files, the stab type need not indicate the section; +@code{C_STSYM} can be used for all statics. Also, each static variable +is enclosed in a static block. A @code{C_BSTAT} (emitted with a +@samp{.bs} assembler directive) symbol begins the static block; its +value is the symbol number of the csect symbol whose value is the +address of the static block, its section is the section of the variables +in that static block, and its name is @samp{.bs}. A @code{C_ESTAT} +(emitted with a @samp{.es} assembler directive) symbol ends the static +block; its name is @samp{.es} and its value and section are ignored. + +In ECOFF files, the storage class is used to specify the section, so the +stab type need not indicate the section. + +In ELF files, for the SunPRO compiler version 2.0.1, symbol descriptor +@samp{S} means that the address is absolute (the linker relocates it) +and symbol descriptor @samp{V} means that the address is relative to the +start of the relevant section for that compilation unit. SunPRO has +plans to have the linker stop relocating stabs; I suspect that their the +debugger gets the address from the corresponding ELF (not stab) symbol. +I'm not sure how to find which symbol of that name is the right one. +The clean way to do all this would be to have a the value of a symbol +descriptor @samp{S} symbol be an offset relative to the start of the +file, just like everything else, but that introduces obvious +compatibility problems. For more information on linker stab relocation, +@xref{ELF Linker Relocation}. + +@node Based Variables +@section Fortran Based Variables + +Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature +which allows allocating arrays with @code{malloc}, but which avoids +blurring the line between arrays and pointers the way that C does. In +stabs such a variable uses the @samp{b} symbol descriptor. + +For example, the Fortran declarations + +@example +real foo, foo10(10), foo10_5(10,5) +pointer (foop, foo) +pointer (foo10p, foo10) +pointer (foo105p, foo10_5) +@end example + +produce the stabs + +@example +foo:b6 +foo10:bar3;1;10;6 +foo10_5:bar3;1;5;ar3;1;10;6 +@end example + +In this example, @code{real} is type 6 and type 3 is an integral type +which is the type of the subscripts of the array (probably +@code{integer}). + +The @samp{b} symbol descriptor is like @samp{V} in that it denotes a +statically allocated symbol whose scope is local to a function; see +@xref{Statics}. The value of the symbol, instead of being the address +of the variable itself, is the address of a pointer to that variable. +So in the above example, the value of the @code{foo} stab is the address +of a pointer to a real, the value of the @code{foo10} stab is the +address of a pointer to a 10-element array of reals, and the value of +the @code{foo10_5} stab is the address of a pointer to a 5-element array +of 10-element arrays of reals. + +@node Parameters +@section Parameters + +Formal parameters to a function are represented by a stab (or sometimes +two; see below) for each parameter. The stabs are in the order in which +the debugger should print the parameters (i.e., the order in which the +parameters are declared in the source file). The exact form of the stab +depends on how the parameter is being passed. + +@findex N_PSYM +@findex C_PSYM +Parameters passed on the stack use the symbol descriptor @samp{p} and +the @code{N_PSYM} symbol type (or @code{C_PSYM} for XCOFF). The value +of the symbol is an offset used to locate the parameter on the stack; +its exact meaning is machine-dependent, but on most machines it is an +offset from the frame pointer. + +As a simple example, the code: + +@example +main (argc, argv) + int argc; + char **argv; +@end example + +produces the stabs: + +@example +.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} +.stabs "argc:p1",160,0,0,68 # @r{160 is N_PSYM} +.stabs "argv:p20=*21=*2",160,0,0,72 +@end example + +The type definition of @code{argv} is interesting because it contains +several type definitions. Type 21 is pointer to type 2 (char) and +@code{argv} (type 20) is pointer to type 21. + +@c FIXME: figure out what these mean and describe them coherently. +The following symbol descriptors are also said to go with @code{N_PSYM}. +The value of the symbol is said to be an offset from the argument +pointer (I'm not sure whether this is true or not). + +@example +pP (<<??>>) +pF Fortran function parameter +X (function result variable) +@end example + +@menu +* Register Parameters:: +* Local Variable Parameters:: +* Reference Parameters:: +* Conformant Arrays:: +@end menu + +@node Register Parameters +@subsection Passing Parameters in Registers + +If the parameter is passed in a register, then traditionally there are +two symbols for each argument: + +@example +.stabs "arg:p1" . . . ; N_PSYM +.stabs "arg:r1" . . . ; N_RSYM +@end example + +Debuggers use the second one to find the value, and the first one to +know that it is an argument. + +@findex C_RPSYM +@findex N_RSYM, for parameters +Because that approach is kind of ugly, some compilers use symbol +descriptor @samp{P} or @samp{R} to indicate an argument which is in a +register. Symbol type @code{C_RPSYM} is used in XCOFF and @code{N_RSYM} +is used otherwise. The symbol's value is the register number. @samp{P} +and @samp{R} mean the same thing; the difference is that @samp{P} is a +GNU invention and @samp{R} is an IBM (XCOFF) invention. As of version +4.9, GDB should handle either one. + +There is at least one case where GCC uses a @samp{p} and @samp{r} pair +rather than @samp{P}; this is where the argument is passed in the +argument list and then loaded into a register. + +According to the AIX documentation, symbol descriptor @samp{D} is for a +parameter passed in a floating point register. This seems +unnecessary---why not just use @samp{R} with a register number which +indicates that it's a floating point register? I haven't verified +whether the system actually does what the documentation indicates. + +@c FIXME: On the hppa this is for any type > 8 bytes, I think, and not +@c for small structures (investigate). +On the sparc and hppa, for a @samp{P} symbol whose type is a structure +or union, the register contains the address of the structure. On the +sparc, this is also true of a @samp{p} and @samp{r} pair (using Sun +@code{cc}) or a @samp{p} symbol. However, if a (small) structure is +really in a register, @samp{r} is used. And, to top it all off, on the +hppa it might be a structure which was passed on the stack and loaded +into a register and for which there is a @samp{p} and @samp{r} pair! I +believe that symbol descriptor @samp{i} is supposed to deal with this +case (it is said to mean "value parameter by reference, indirect +access"; I don't know the source for this information), but I don't know +details or what compilers or debuggers use it, if any (not GDB or GCC). +It is not clear to me whether this case needs to be dealt with +differently than parameters passed by reference (@pxref{Reference Parameters}). + +@node Local Variable Parameters +@subsection Storing Parameters as Local Variables + +There is a case similar to an argument in a register, which is an +argument that is actually stored as a local variable. Sometimes this +happens when the argument was passed in a register and then the compiler +stores it as a local variable. If possible, the compiler should claim +that it's in a register, but this isn't always done. + +If a parameter is passed as one type and converted to a smaller type by +the prologue (for example, the parameter is declared as a @code{float}, +but the calling conventions specify that it is passed as a +@code{double}), then GCC2 (sometimes) uses a pair of symbols. The first +symbol uses symbol descriptor @samp{p} and the type which is passed. +The second symbol has the type and location which the parameter actually +has after the prologue. For example, suppose the following C code +appears with no prototypes involved: + +@example +void +subr (f) + float f; +@{ +@end example + +if @code{f} is passed as a double at stack offset 8, and the prologue +converts it to a float in register number 0, then the stabs look like: + +@example +.stabs "f:p13",160,0,3,8 # @r{160 is @code{N_PSYM}, here 13 is @code{double}} +.stabs "f:r12",64,0,3,0 # @r{64 is @code{N_RSYM}, here 12 is @code{float}} +@end example + +In both stabs 3 is the line number where @code{f} is declared +(@pxref{Line Numbers}). + +@findex N_LSYM, for parameter +GCC, at least on the 960, has another solution to the same problem. It +uses a single @samp{p} symbol descriptor for an argument which is stored +as a local variable but uses @code{N_LSYM} instead of @code{N_PSYM}. In +this case, the value of the symbol is an offset relative to the local +variables for that function, not relative to the arguments; on some +machines those are the same thing, but not on all. + +@c This is mostly just background info; the part that logically belongs +@c here is the last sentence. +On the VAX or on other machines in which the calling convention includes +the number of words of arguments actually passed, the debugger (GDB at +least) uses the parameter symbols to keep track of whether it needs to +print nameless arguments in addition to the formal parameters which it +has printed because each one has a stab. For example, in + +@example +extern int fprintf (FILE *stream, char *format, @dots{}); +@dots{} +fprintf (stdout, "%d\n", x); +@end example + +there are stabs for @code{stream} and @code{format}. On most machines, +the debugger can only print those two arguments (because it has no way +of knowing that additional arguments were passed), but on the VAX or +other machines with a calling convention which indicates the number of +words of arguments, the debugger can print all three arguments. To do +so, the parameter symbol (symbol descriptor @samp{p}) (not necessarily +@samp{r} or symbol descriptor omitted symbols) needs to contain the +actual type as passed (for example, @code{double} not @code{float} if it +is passed as a double and converted to a float). + +@node Reference Parameters +@subsection Passing Parameters by Reference + +If the parameter is passed by reference (e.g., Pascal @code{VAR} +parameters), then the symbol descriptor is @samp{v} if it is in the +argument list, or @samp{a} if it in a register. Other than the fact +that these contain the address of the parameter rather than the +parameter itself, they are identical to @samp{p} and @samp{R}, +respectively. I believe @samp{a} is an AIX invention; @samp{v} is +supported by all stabs-using systems as far as I know. + +@node Conformant Arrays +@subsection Passing Conformant Array Parameters + +@c Is this paragraph correct? It is based on piecing together patchy +@c information and some guesswork +Conformant arrays are a feature of Modula-2, and perhaps other +languages, in which the size of an array parameter is not known to the +called function until run-time. Such parameters have two stabs: a +@samp{x} for the array itself, and a @samp{C}, which represents the size +of the array. The value of the @samp{x} stab is the offset in the +argument list where the address of the array is stored (it this right? +it is a guess); the value of the @samp{C} stab is the offset in the +argument list where the size of the array (in elements? in bytes?) is +stored. + +@node Types +@chapter Defining Types + +The examples so far have described types as references to previously +defined types, or defined in terms of subranges of or pointers to +previously defined types. This chapter describes the other type +descriptors that may follow the @samp{=} in a type definition. + +@menu +* Builtin Types:: Integers, floating point, void, etc. +* Miscellaneous Types:: Pointers, sets, files, etc. +* Cross-References:: Referring to a type not yet defined. +* Subranges:: A type with a specific range. +* Arrays:: An aggregate type of same-typed elements. +* Strings:: Like an array but also has a length. +* Enumerations:: Like an integer but the values have names. +* Structures:: An aggregate type of different-typed elements. +* Typedefs:: Giving a type a name. +* Unions:: Different types sharing storage. +* Function Types:: +@end menu + +@node Builtin Types +@section Builtin Types + +Certain types are built in (@code{int}, @code{short}, @code{void}, +@code{float}, etc.); the debugger recognizes these types and knows how +to handle them. Thus, don't be surprised if some of the following ways +of specifying builtin types do not specify everything that a debugger +would need to know about the type---in some cases they merely specify +enough information to distinguish the type from other types. + +The traditional way to define builtin types is convolunted, so new ways +have been invented to describe them. Sun's @code{acc} uses special +builtin type descriptors (@samp{b} and @samp{R}), and IBM uses negative +type numbers. GDB accepts all three ways, as of version 4.8; dbx just +accepts the traditional builtin types and perhaps one of the other two +formats. The following sections describe each of these formats. + +@menu +* Traditional Builtin Types:: Put on your seatbelts and prepare for kludgery +* Builtin Type Descriptors:: Builtin types with special type descriptors +* Negative Type Numbers:: Builtin types using negative type numbers +@end menu + +@node Traditional Builtin Types +@subsection Traditional Builtin Types + +This is the traditional, convoluted method for defining builtin types. +There are several classes of such type definitions: integer, floating +point, and @code{void}. + +@menu +* Traditional Integer Types:: +* Traditional Other Types:: +@end menu + +@node Traditional Integer Types +@subsubsection Traditional Integer Types + +Often types are defined as subranges of themselves. If the bounding values +fit within an @code{int}, then they are given normally. For example: + +@example +.stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 # @r{128 is N_LSYM} +.stabs "char:t2=r2;0;127;",128,0,0,0 +@end example + +Builtin types can also be described as subranges of @code{int}: + +@example +.stabs "unsigned short:t6=r1;0;65535;",128,0,0,0 +@end example + +If the lower bound of a subrange is 0 and the upper bound is -1, +the type is an unsigned integral type whose bounds are too +big to describe in an @code{int}. Traditionally this is only used for +@code{unsigned int} and @code{unsigned long}: + +@example +.stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 +@end example + +For larger types, GCC 2.4.5 puts out bounds in octal, with one or more +leading zeroes. In this case a negative bound consists of a number +which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in +the number (except the sign bit), and a positive bound is one which is a +1 bit for each bit in the number (except possibly the sign bit). All +known versions of dbx and GDB version 4 accept this (at least in the +sense of not refusing to process the file), but GDB 3.5 refuses to read +the whole file containing such symbols. So GCC 2.3.3 did not output the +proper size for these types. As an example of octal bounds, the string +fields of the stabs for 64 bit integer types look like: + +@c .stabs directives, etc., omitted to make it fit on the page. +@example +long int:t3=r1;001000000000000000000000;000777777777777777777777; +long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777; +@end example + +If the lower bound of a subrange is 0 and the upper bound is negative, +the type is an unsigned integral type whose size in bytes is the +absolute value of the upper bound. I believe this is a Convex +convention for @code{unsigned long long}. + +If the lower bound of a subrange is negative and the upper bound is 0, +the type is a signed integral type whose size in bytes is +the absolute value of the lower bound. I believe this is a Convex +convention for @code{long long}. To distinguish this from a legitimate +subrange, the type should be a subrange of itself. I'm not sure whether +this is the case for Convex. + +@node Traditional Other Types +@subsubsection Traditional Other Types + +If the upper bound of a subrange is 0 and the lower bound is positive, +the type is a floating point type, and the lower bound of the subrange +indicates the number of bytes in the type: + +@example +.stabs "float:t12=r1;4;0;",128,0,0,0 +.stabs "double:t13=r1;8;0;",128,0,0,0 +@end example + +However, GCC writes @code{long double} the same way it writes +@code{double}, so there is no way to distinguish. + +@example +.stabs "long double:t14=r1;8;0;",128,0,0,0 +@end example + +Complex types are defined the same way as floating-point types; there is +no way to distinguish a single-precision complex from a double-precision +floating-point type. + +The C @code{void} type is defined as itself: + +@example +.stabs "void:t15=15",128,0,0,0 +@end example + +I'm not sure how a boolean type is represented. + +@node Builtin Type Descriptors +@subsection Defining Builtin Types Using Builtin Type Descriptors + +This is the method used by Sun's @code{acc} for defining builtin types. +These are the type descriptors to define builtin types: + +@table @code +@c FIXME: clean up description of width and offset, once we figure out +@c what they mean +@item b @var{signed} @var{char-flag} @var{width} ; @var{offset} ; @var{nbits} ; +Define an integral type. @var{signed} is @samp{u} for unsigned or +@samp{s} for signed. @var{char-flag} is @samp{c} which indicates this +is a character type, or is omitted. I assume this is to distinguish an +integral type from a character type of the same size, for example it +might make sense to set it for the C type @code{wchar_t} so the debugger +can print such variables differently (Solaris does not do this). Sun +sets it on the C types @code{signed char} and @code{unsigned char} which +arguably is wrong. @var{width} and @var{offset} appear to be for small +objects stored in larger ones, for example a @code{short} in an +@code{int} register. @var{width} is normally the number of bytes in the +type. @var{offset} seems to always be zero. @var{nbits} is the number +of bits in the type. + +Note that type descriptor @samp{b} used for builtin types conflicts with +its use for Pascal space types (@pxref{Miscellaneous Types}); they can +be distinguished because the character following the type descriptor +will be a digit, @samp{(}, or @samp{-} for a Pascal space type, or +@samp{u} or @samp{s} for a builtin type. + +@item w +Documented by AIX to define a wide character type, but their compiler +actually uses negative type numbers (@pxref{Negative Type Numbers}). + +@item R @var{fp-type} ; @var{bytes} ; +Define a floating point type. @var{fp-type} has one of the following values: + +@table @code +@item 1 (NF_SINGLE) +IEEE 32-bit (single precision) floating point format. + +@item 2 (NF_DOUBLE) +IEEE 64-bit (double precision) floating point format. + +@item 3 (NF_COMPLEX) +@item 4 (NF_COMPLEX16) +@item 5 (NF_COMPLEX32) +@c "GDB source" really means @file{include/aout/stab_gnu.h}, but trying +@c to put that here got an overfull hbox. +These are for complex numbers. A comment in the GDB source describes +them as Fortran @code{complex}, @code{double complex}, and +@code{complex*16}, respectively, but what does that mean? (i.e., Single +precision? Double precison?). + +@item 6 (NF_LDOUBLE) +Long double. This should probably only be used for Sun format +@code{long double}, and new codes should be used for other floating +point formats (@code{NF_DOUBLE} can be used if a @code{long double} is +really just an IEEE double, of course). +@end table + +@var{bytes} is the number of bytes occupied by the type. This allows a +debugger to perform some operations with the type even if it doesn't +understand @var{fp-type}. + +@item g @var{type-information} ; @var{nbits} +Documented by AIX to define a floating type, but their compiler actually +uses negative type numbers (@pxref{Negative Type Numbers}). + +@item c @var{type-information} ; @var{nbits} +Documented by AIX to define a complex type, but their compiler actually +uses negative type numbers (@pxref{Negative Type Numbers}). +@end table + +The C @code{void} type is defined as a signed integral type 0 bits long: +@example +.stabs "void:t19=bs0;0;0",128,0,0,0 +@end example +The Solaris compiler seems to omit the trailing semicolon in this case. +Getting sloppy in this way is not a swift move because if a type is +embedded in a more complex expression it is necessary to be able to tell +where it ends. + +I'm not sure how a boolean type is represented. + +@node Negative Type Numbers +@subsection Negative Type Numbers + +This is the method used in XCOFF for defining builtin types. +Since the debugger knows about the builtin types anyway, the idea of +negative type numbers is simply to give a special type number which +indicates the builtin type. There is no stab defining these types. + +There are several subtle issues with negative type numbers. + +One is the size of the type. A builtin type (for example the C types +@code{int} or @code{long}) might have different sizes depending on +compiler options, the target architecture, the ABI, etc. This issue +doesn't come up for IBM tools since (so far) they just target the +RS/6000; the sizes indicated below for each size are what the IBM +RS/6000 tools use. To deal with differing sizes, either define separate +negative type numbers for each size (which works but requires changing +the debugger, and, unless you get both AIX dbx and GDB to accept the +change, introduces an incompatibility), or use a type attribute +(@pxref{String Field}) to define a new type with the appropriate size +(which merely requires a debugger which understands type attributes, +like AIX dbx or GDB). For example, + +@example +.stabs "boolean:t10=@@s8;-16",128,0,0,0 +@end example + +defines an 8-bit boolean type, and + +@example +.stabs "boolean:t10=@@s64;-16",128,0,0,0 +@end example + +defines a 64-bit boolean type. + +A similar issue is the format of the type. This comes up most often for +floating-point types, which could have various formats (particularly +extended doubles, which vary quite a bit even among IEEE systems). +Again, it is best to define a new negative type number for each +different format; changing the format based on the target system has +various problems. One such problem is that the Alpha has both VAX and +IEEE floating types. One can easily imagine one library using the VAX +types and another library in the same executable using the IEEE types. +Another example is that the interpretation of whether a boolean is true +or false can be based on the least significant bit, most significant +bit, whether it is zero, etc., and different compilers (or different +options to the same compiler) might provide different kinds of boolean. + +The last major issue is the names of the types. The name of a given +type depends @emph{only} on the negative type number given; these do not +vary depending on the language, the target system, or anything else. +One can always define separate type numbers---in the following list you +will see for example separate @code{int} and @code{integer*4} types +which are identical except for the name. But compatibility can be +maintained by not inventing new negative type numbers and instead just +defining a new type with a new name. For example: + +@example +.stabs "CARDINAL:t10=-8",128,0,0,0 +@end example + +Here is the list of negative type numbers. The phrase @dfn{integral +type} is used to mean twos-complement (I strongly suspect that all +machines which use stabs use twos-complement; most machines use +twos-complement these days). + +@table @code +@item -1 +@code{int}, 32 bit signed integral type. + +@item -2 +@code{char}, 8 bit type holding a character. Both GDB and dbx on AIX +treat this as signed. GCC uses this type whether @code{char} is signed +or not, which seems like a bad idea. The AIX compiler (@code{xlc}) seems to +avoid this type; it uses -5 instead for @code{char}. + +@item -3 +@code{short}, 16 bit signed integral type. + +@item -4 +@code{long}, 32 bit signed integral type. + +@item -5 +@code{unsigned char}, 8 bit unsigned integral type. + +@item -6 +@code{signed char}, 8 bit signed integral type. + +@item -7 +@code{unsigned short}, 16 bit unsigned integral type. + +@item -8 +@code{unsigned int}, 32 bit unsigned integral type. + +@item -9 +@code{unsigned}, 32 bit unsigned integral type. + +@item -10 +@code{unsigned long}, 32 bit unsigned integral type. + +@item -11 +@code{void}, type indicating the lack of a value. + +@item -12 +@code{float}, IEEE single precision. + +@item -13 +@code{double}, IEEE double precision. + +@item -14 +@code{long double}, IEEE double precision. The compiler claims the size +will increase in a future release, and for binary compatibility you have +to avoid using @code{long double}. I hope when they increase it they +use a new negative type number. + +@item -15 +@code{integer}. 32 bit signed integral type. + +@item -16 +@code{boolean}. 32 bit type. GDB and GCC assume that zero is false, +one is true, and other values have unspecified meaning. I hope this +agrees with how the IBM tools use the type. + +@item -17 +@code{short real}. IEEE single precision. + +@item -18 +@code{real}. IEEE double precision. + +@item -19 +@code{stringptr}. @xref{Strings}. + +@item -20 +@code{character}, 8 bit unsigned character type. + +@item -21 +@code{logical*1}, 8 bit type. This Fortran type has a split +personality in that it is used for boolean variables, but can also be +used for unsigned integers. 0 is false, 1 is true, and other values are +non-boolean. + +@item -22 +@code{logical*2}, 16 bit type. This Fortran type has a split +personality in that it is used for boolean variables, but can also be +used for unsigned integers. 0 is false, 1 is true, and other values are +non-boolean. + +@item -23 +@code{logical*4}, 32 bit type. This Fortran type has a split +personality in that it is used for boolean variables, but can also be +used for unsigned integers. 0 is false, 1 is true, and other values are +non-boolean. + +@item -24 +@code{logical}, 32 bit type. This Fortran type has a split +personality in that it is used for boolean variables, but can also be +used for unsigned integers. 0 is false, 1 is true, and other values are +non-boolean. + +@item -25 +@code{complex}. A complex type consisting of two IEEE single-precision +floating point values. + +@item -26 +@code{complex}. A complex type consisting of two IEEE double-precision +floating point values. + +@item -27 +@code{integer*1}, 8 bit signed integral type. + +@item -28 +@code{integer*2}, 16 bit signed integral type. + +@item -29 +@code{integer*4}, 32 bit signed integral type. + +@item -30 +@code{wchar}. Wide character, 16 bits wide, unsigned (what format? +Unicode?). + +@item -31 +@code{long long}, 64 bit signed integral type. + +@item -32 +@code{unsigned long long}, 64 bit unsigned integral type. + +@item -33 +@code{logical*8}, 64 bit unsigned integral type. + +@item -34 +@code{integer*8}, 64 bit signed integral type. +@end table + +@node Miscellaneous Types +@section Miscellaneous Types + +@table @code +@item b @var{type-information} ; @var{bytes} +Pascal space type. This is documented by IBM; what does it mean? + +This use of the @samp{b} type descriptor can be distinguished +from its use for builtin integral types (@pxref{Builtin Type +Descriptors}) because the character following the type descriptor is +always a digit, @samp{(}, or @samp{-}. + +@item B @var{type-information} +A volatile-qualified version of @var{type-information}. This is +a Sun extension. References and stores to a variable with a +volatile-qualified type must not be optimized or cached; they +must occur as the user specifies them. + +@item d @var{type-information} +File of type @var{type-information}. As far as I know this is only used +by Pascal. + +@item k @var{type-information} +A const-qualified version of @var{type-information}. This is a Sun +extension. A variable with a const-qualified type cannot be modified. + +@item M @var{type-information} ; @var{length} +Multiple instance type. The type seems to composed of @var{length} +repetitions of @var{type-information}, for example @code{character*3} is +represented by @samp{M-2;3}, where @samp{-2} is a reference to a +character type (@pxref{Negative Type Numbers}). I'm not sure how this +differs from an array. This appears to be a Fortran feature. +@var{length} is a bound, like those in range types; see @ref{Subranges}. + +@item S @var{type-information} +Pascal set type. @var{type-information} must be a small type such as an +enumeration or a subrange, and the type is a bitmask whose length is +specified by the number of elements in @var{type-information}. + +In CHILL, if it is a bitstring instead of a set, also use the @samp{S} +type attribute (@pxref{String Field}). + +@item * @var{type-information} +Pointer to @var{type-information}. +@end table + +@node Cross-References +@section Cross-References to Other Types + +A type can be used before it is defined; one common way to deal with +that situation is just to use a type reference to a type which has not +yet been defined. + +Another way is with the @samp{x} type descriptor, which is followed by +@samp{s} for a structure tag, @samp{u} for a union tag, or @samp{e} for +a enumerator tag, followed by the name of the tag, followed by @samp{:}. +If the name contains @samp{::} between a @samp{<} and @samp{>} pair (for +C++ templates), such a @samp{::} does not end the name---only a single +@samp{:} ends the name; see @ref{Nested Symbols}. + +For example, the following C declarations: + +@example +struct foo; +struct foo *bar; +@end example + +@noindent +produce: + +@example +.stabs "bar:G16=*17=xsfoo:",32,0,0,0 +@end example + +Not all debuggers support the @samp{x} type descriptor, so on some +machines GCC does not use it. I believe that for the above example it +would just emit a reference to type 17 and never define it, but I +haven't verified that. + +Modula-2 imported types, at least on AIX, use the @samp{i} type +descriptor, which is followed by the name of the module from which the +type is imported, followed by @samp{:}, followed by the name of the +type. There is then optionally a comma followed by type information for +the type. This differs from merely naming the type (@pxref{Typedefs}) in +that it identifies the module; I don't understand whether the name of +the type given here is always just the same as the name we are giving +it, or whether this type descriptor is used with a nameless stab +(@pxref{String Field}), or what. The symbol ends with @samp{;}. + +@node Subranges +@section Subrange Types + +The @samp{r} type descriptor defines a type as a subrange of another +type. It is followed by type information for the type of which it is a +subrange, a semicolon, an integral lower bound, a semicolon, an +integral upper bound, and a semicolon. The AIX documentation does not +specify the trailing semicolon, in an effort to specify array indexes +more cleanly, but a subrange which is not an array index has always +included a trailing semicolon (@pxref{Arrays}). + +Instead of an integer, either bound can be one of the following: + +@table @code +@item A @var{offset} +The bound is passed by reference on the stack at offset @var{offset} +from the argument list. @xref{Parameters}, for more information on such +offsets. + +@item T @var{offset} +The bound is passed by value on the stack at offset @var{offset} from +the argument list. + +@item a @var{register-number} +The bound is pased by reference in register number +@var{register-number}. + +@item t @var{register-number} +The bound is passed by value in register number @var{register-number}. + +@item J +There is no bound. +@end table + +Subranges are also used for builtin types; see @ref{Traditional Builtin Types}. + +@node Arrays +@section Array Types + +Arrays use the @samp{a} type descriptor. Following the type descriptor +is the type of the index and the type of the array elements. If the +index type is a range type, it ends in a semicolon; otherwise +(for example, if it is a type reference), there does not +appear to be any way to tell where the types are separated. In an +effort to clean up this mess, IBM documents the two types as being +separated by a semicolon, and a range type as not ending in a semicolon +(but this is not right for range types which are not array indexes, +@pxref{Subranges}). I think probably the best solution is to specify +that a semicolon ends a range type, and that the index type and element +type of an array are separated by a semicolon, but that if the index +type is a range type, the extra semicolon can be omitted. GDB (at least +through version 4.9) doesn't support any kind of index type other than a +range anyway; I'm not sure about dbx. + +It is well established, and widely used, that the type of the index, +unlike most types found in the stabs, is merely a type definition, not +type information (@pxref{String Field}) (that is, it need not start with +@samp{@var{type-number}=} if it is defining a new type). According to a +comment in GDB, this is also true of the type of the array elements; it +gives @samp{ar1;1;10;ar1;1;10;4} as a legitimate way to express a two +dimensional array. According to AIX documentation, the element type +must be type information. GDB accepts either. + +The type of the index is often a range type, expressed as the type +descriptor @samp{r} and some parameters. It defines the size of the +array. In the example below, the range @samp{r1;0;2;} defines an index +type which is a subrange of type 1 (integer), with a lower bound of 0 +and an upper bound of 2. This defines the valid range of subscripts of +a three-element C array. + +For example, the definition: + +@example +char char_vec[3] = @{'a','b','c'@}; +@end example + +@noindent +produces the output: + +@example +.stabs "char_vec:G19=ar1;0;2;2",32,0,0,0 + .global _char_vec + .align 4 +_char_vec: + .byte 97 + .byte 98 + .byte 99 +@end example + +If an array is @dfn{packed}, the elements are spaced more +closely than normal, saving memory at the expense of speed. For +example, an array of 3-byte objects might, if unpacked, have each +element aligned on a 4-byte boundary, but if packed, have no padding. +One way to specify that something is packed is with type attributes +(@pxref{String Field}). In the case of arrays, another is to use the +@samp{P} type descriptor instead of @samp{a}. Other than specifying a +packed array, @samp{P} is identical to @samp{a}. + +@c FIXME-what is it? A pointer? +An open array is represented by the @samp{A} type descriptor followed by +type information specifying the type of the array elements. + +@c FIXME: what is the format of this type? A pointer to a vector of pointers? +An N-dimensional dynamic array is represented by + +@example +D @var{dimensions} ; @var{type-information} +@end example + +@c Does dimensions really have this meaning? The AIX documentation +@c doesn't say. +@var{dimensions} is the number of dimensions; @var{type-information} +specifies the type of the array elements. + +@c FIXME: what is the format of this type? A pointer to some offsets in +@c another array? +A subarray of an N-dimensional array is represented by + +@example +E @var{dimensions} ; @var{type-information} +@end example + +@c Does dimensions really have this meaning? The AIX documentation +@c doesn't say. +@var{dimensions} is the number of dimensions; @var{type-information} +specifies the type of the array elements. + +@node Strings +@section Strings + +Some languages, like C or the original Pascal, do not have string types, +they just have related things like arrays of characters. But most +Pascals and various other languages have string types, which are +indicated as follows: + +@table @code +@item n @var{type-information} ; @var{bytes} +@var{bytes} is the maximum length. I'm not sure what +@var{type-information} is; I suspect that it means that this is a string +of @var{type-information} (thus allowing a string of integers, a string +of wide characters, etc., as well as a string of characters). Not sure +what the format of this type is. This is an AIX feature. + +@item z @var{type-information} ; @var{bytes} +Just like @samp{n} except that this is a gstring, not an ordinary +string. I don't know the difference. + +@item N +Pascal Stringptr. What is this? This is an AIX feature. +@end table + +Languages, such as CHILL which have a string type which is basically +just an array of characters use the @samp{S} type attribute +(@pxref{String Field}). + +@node Enumerations +@section Enumerations + +Enumerations are defined with the @samp{e} type descriptor. + +@c FIXME: Where does this information properly go? Perhaps it is +@c redundant with something we already explain. +The source line below declares an enumeration type at file scope. +The type definition is located after the @code{N_RBRAC} that marks the end of +the previous procedure's block scope, and before the @code{N_FUN} that marks +the beginning of the next procedure's block scope. Therefore it does not +describe a block local symbol, but a file local one. + +The source line: + +@example +enum e_places @{first,second=3,last@}; +@end example + +@noindent +generates the following stab: + +@example +.stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0 +@end example + +The symbol descriptor (@samp{T}) says that the stab describes a +structure, enumeration, or union tag. The type descriptor @samp{e}, +following the @samp{22=} of the type definition narrows it down to an +enumeration type. Following the @samp{e} is a list of the elements of +the enumeration. The format is @samp{@var{name}:@var{value},}. The +list of elements ends with @samp{;}. The fact that @var{value} is +specified as an integer can cause problems if the value is large. GCC +2.5.2 tries to output it in octal in that case with a leading zero, +which is probably a good thing, although GDB 4.11 supports octal only in +cases where decimal is perfectly good. Negative decimal values are +supported by both GDB and dbx. + +There is no standard way to specify the size of an enumeration type; it +is determined by the architecture (normally all enumerations types are +32 bits). Type attributes can be used to specify an enumeration type of +another size for debuggers which support them; see @ref{String Field}. + +Enumeration types are unusual in that they define symbols for the +enumeration values (@code{first}, @code{second}, and @code{third} in the +above example), and even though these symbols are visible in the file as +a whole (rather than being in a more local namespace like structure +member names), they are defined in the type definition for the +enumeration type rather than each having their own symbol. In order to +be fast, GDB will only get symbols from such types (in its initial scan +of the stabs) if the type is the first thing defined after a @samp{T} or +@samp{t} symbol descriptor (the above example fulfills this +requirement). If the type does not have a name, the compiler should +emit it in a nameless stab (@pxref{String Field}); GCC does this. + +@node Structures +@section Structures + +The encoding of structures in stabs can be shown with an example. + +The following source code declares a structure tag and defines an +instance of the structure in global scope. Then a @code{typedef} equates the +structure tag with a new type. Seperate stabs are generated for the +structure tag, the structure @code{typedef}, and the structure instance. The +stabs for the tag and the @code{typedef} are emited when the definitions are +encountered. Since the structure elements are not initialized, the +stab and code for the structure variable itself is located at the end +of the program in the bss section. + +@example +struct s_tag @{ + int s_int; + float s_float; + char s_char_vec[8]; + struct s_tag* s_next; +@} g_an_s; + +typedef struct s_tag s_typedef; +@end example + +The structure tag has an @code{N_LSYM} stab type because, like the +enumeration, the symbol has file scope. Like the enumeration, the +symbol descriptor is @samp{T}, for enumeration, structure, or tag type. +The type descriptor @samp{s} following the @samp{16=} of the type +definition narrows the symbol type to structure. + +Following the @samp{s} type descriptor is the number of bytes the +structure occupies, followed by a description of each structure element. +The structure element descriptions are of the form @var{name:type, bit +offset from the start of the struct, number of bits in the element}. + +@c FIXME: phony line break. Can probably be fixed by using an example +@c with fewer fields. +@example +# @r{128 is N_LSYM} +.stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32; + s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0 +@end example + +In this example, the first two structure elements are previously defined +types. For these, the type following the @samp{@var{name}:} part of the +element description is a simple type reference. The other two structure +elements are new types. In this case there is a type definition +embedded after the @samp{@var{name}:}. The type definition for the +array element looks just like a type definition for a standalone array. +The @code{s_next} field is a pointer to the same kind of structure that +the field is an element of. So the definition of structure type 16 +contains a type definition for an element which is a pointer to type 16. + +If a field is a static member (this is a C++ feature in which a single +variable appears to be a field of every structure of a given type) it +still starts out with the field name, a colon, and the type, but then +instead of a comma, bit position, comma, and bit size, there is a colon +followed by the name of the variable which each such field refers to. + +If the structure has methods (a C++ feature), they follow the non-method +fields; see @ref{Cplusplus}. + +@node Typedefs +@section Giving a Type a Name + +@findex N_LSYM, for types +@findex C_DECL, for types +To give a type a name, use the @samp{t} symbol descriptor. The type +is specified by the type information (@pxref{String Field}) for the stab. +For example, + +@example +.stabs "s_typedef:t16",128,0,0,0 # @r{128 is N_LSYM} +@end example + +specifies that @code{s_typedef} refers to type number 16. Such stabs +have symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF). (The Sun +documentation mentions using @code{N_GSYM} in some cases). + +If you are specifying the tag name for a structure, union, or +enumeration, use the @samp{T} symbol descriptor instead. I believe C is +the only language with this feature. + +If the type is an opaque type (I believe this is a Modula-2 feature), +AIX provides a type descriptor to specify it. The type descriptor is +@samp{o} and is followed by a name. I don't know what the name +means---is it always the same as the name of the type, or is this type +descriptor used with a nameless stab (@pxref{String Field})? There +optionally follows a comma followed by type information which defines +the type of this type. If omitted, a semicolon is used in place of the +comma and the type information, and the type is much like a generic +pointer type---it has a known size but little else about it is +specified. + +@node Unions +@section Unions + +@example +union u_tag @{ + int u_int; + float u_float; + char* u_char; +@} an_u; +@end example + +This code generates a stab for a union tag and a stab for a union +variable. Both use the @code{N_LSYM} stab type. If a union variable is +scoped locally to the procedure in which it is defined, its stab is +located immediately preceding the @code{N_LBRAC} for the procedure's block +start. + +The stab for the union tag, however, is located preceding the code for +the procedure in which it is defined. The stab type is @code{N_LSYM}. This +would seem to imply that the union type is file scope, like the struct +type @code{s_tag}. This is not true. The contents and position of the stab +for @code{u_type} do not convey any infomation about its procedure local +scope. + +@c FIXME: phony line break. Can probably be fixed by using an example +@c with fewer fields. +@smallexample +# @r{128 is N_LSYM} +.stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;", + 128,0,0,0 +@end smallexample + +The symbol descriptor @samp{T}, following the @samp{name:} means that +the stab describes an enumeration, structure, or union tag. The type +descriptor @samp{u}, following the @samp{23=} of the type definition, +narrows it down to a union type definition. Following the @samp{u} is +the number of bytes in the union. After that is a list of union element +descriptions. Their format is @var{name:type, bit offset into the +union, number of bytes for the element;}. + +The stab for the union variable is: + +@example +.stabs "an_u:23",128,0,0,-20 # @r{128 is N_LSYM} +@end example + +@samp{-20} specifies where the variable is stored (@pxref{Stack +Variables}). + +@node Function Types +@section Function Types + +Various types can be defined for function variables. These types are +not used in defining functions (@pxref{Procedures}); they are used for +things like pointers to functions. + +The simple, traditional, type is type descriptor @samp{f} is followed by +type information for the return type of the function, followed by a +semicolon. + +This does not deal with functions for which the number and types of the +parameters are part of the type, as in Modula-2 or ANSI C. AIX provides +extensions to specify these, using the @samp{f}, @samp{F}, @samp{p}, and +@samp{R} type descriptors. + +First comes the type descriptor. If it is @samp{f} or @samp{F}, this +type involves a function rather than a procedure, and the type +information for the return type of the function follows, followed by a +comma. Then comes the number of parameters to the function and a +semicolon. Then, for each parameter, there is the name of the parameter +followed by a colon (this is only present for type descriptors @samp{R} +and @samp{F} which represent Pascal function or procedure parameters), +type information for the parameter, a comma, 0 if passed by reference or +1 if passed by value, and a semicolon. The type definition ends with a +semicolon. + +For example, this variable definition: + +@example +int (*g_pf)(); +@end example + +@noindent +generates the following code: + +@example +.stabs "g_pf:G24=*25=f1",32,0,0,0 + .common _g_pf,4,"bss" +@end example + +The variable defines a new type, 24, which is a pointer to another new +type, 25, which is a function returning @code{int}. + +@node Symbol Tables +@chapter Symbol Information in Symbol Tables + +This chapter describes the format of symbol table entries +and how stab assembler directives map to them. It also describes the +transformations that the assembler and linker make on data from stabs. + +@menu +* Symbol Table Format:: +* Transformations On Symbol Tables:: +@end menu + +@node Symbol Table Format +@section Symbol Table Format + +Each time the assembler encounters a stab directive, it puts +each field of the stab into a corresponding field in a symbol table +entry of its output file. If the stab contains a string field, the +symbol table entry for that stab points to a string table entry +containing the string data from the stab. Assembler labels become +relocatable addresses. Symbol table entries in a.out have the format: + +@c FIXME: should refer to external, not internal. +@example +struct internal_nlist @{ + unsigned long n_strx; /* index into string table of name */ + unsigned char n_type; /* type of symbol */ + unsigned char n_other; /* misc info (usually empty) */ + unsigned short n_desc; /* description field */ + bfd_vma n_value; /* value of symbol */ +@}; +@end example + +If the stab has a string, the @code{n_strx} field holds the offset in +bytes of the string within the string table. The string is terminated +by a NUL character. If the stab lacks a string (for example, it was +produced by a @code{.stabn} or @code{.stabd} directive), the +@code{n_strx} field is zero. + +Symbol table entries with @code{n_type} field values greater than 0x1f +originated as stabs generated by the compiler (with one random +exception). The other entries were placed in the symbol table of the +executable by the assembler or the linker. + +@node Transformations On Symbol Tables +@section Transformations on Symbol Tables + +The linker concatenates object files and does fixups of externally +defined symbols. + +You can see the transformations made on stab data by the assembler and +linker by examining the symbol table after each pass of the build. To +do this, use @samp{nm -ap}, which dumps the symbol table, including +debugging information, unsorted. For stab entries the columns are: +@var{value}, @var{other}, @var{desc}, @var{type}, @var{string}. For +assembler and linker symbols, the columns are: @var{value}, @var{type}, +@var{string}. + +The low 5 bits of the stab type tell the linker how to relocate the +value of the stab. Thus for stab types like @code{N_RSYM} and +@code{N_LSYM}, where the value is an offset or a register number, the +low 5 bits are @code{N_ABS}, which tells the linker not to relocate the +value. + +Where the value of a stab contains an assembly language label, +it is transformed by each build step. The assembler turns it into a +relocatable address and the linker turns it into an absolute address. + +@menu +* Transformations On Static Variables:: +* Transformations On Global Variables:: +* Stab Section Transformations:: For some object file formats, + things are a bit different. +@end menu + +@node Transformations On Static Variables +@subsection Transformations on Static Variables + +This source line defines a static variable at file scope: + +@example +static int s_g_repeat +@end example + +@noindent +The following stab describes the symbol: + +@example +.stabs "s_g_repeat:S1",38,0,0,_s_g_repeat +@end example + +@noindent +The assembler transforms the stab into this symbol table entry in the +@file{.o} file. The location is expressed as a data segment offset. + +@example +00000084 - 00 0000 STSYM s_g_repeat:S1 +@end example + +@noindent +In the symbol table entry from the executable, the linker has made the +relocatable address absolute. + +@example +0000e00c - 00 0000 STSYM s_g_repeat:S1 +@end example + +@node Transformations On Global Variables +@subsection Transformations on Global Variables + +Stabs for global variables do not contain location information. In +this case, the debugger finds location information in the assembler or +linker symbol table entry describing the variable. The source line: + +@example +char g_foo = 'c'; +@end example + +@noindent +generates the stab: + +@example +.stabs "g_foo:G2",32,0,0,0 +@end example + +The variable is represented by two symbol table entries in the object +file (see below). The first one originated as a stab. The second one +is an external symbol. The upper case @samp{D} signifies that the +@code{n_type} field of the symbol table contains 7, @code{N_DATA} with +local linkage. The stab's value is zero since the value is not used for +@code{N_GSYM} stabs. The value of the linker symbol is the relocatable +address corresponding to the variable. + +@example +00000000 - 00 0000 GSYM g_foo:G2 +00000080 D _g_foo +@end example + +@noindent +These entries as transformed by the linker. The linker symbol table +entry now holds an absolute address: + +@example +00000000 - 00 0000 GSYM g_foo:G2 +@dots{} +0000e008 D _g_foo +@end example + +@node Stab Section Transformations +@subsection Transformations of Stabs in separate sections + +For object file formats using stabs in separate sections (@pxref{Stab +Sections}), use @code{objdump --stabs} instead of @code{nm} to show the +stabs in an object or executable file. @code{objdump} is a GNU utility; +Sun does not provide any equivalent. + +The following example is for a stab whose value is an address is +relative to the compilation unit (@pxref{ELF Linker Relocation}). For +example, if the source line + +@example +static int ld = 5; +@end example + +appears within a function, then the assembly language output from the +compiler contains: + +@example +.Ddata.data: +@dots{} + .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data # @r{0x26 is N_STSYM} +@dots{} +.L18: + .align 4 + .word 0x5 +@end example + +Because the value is formed by subtracting one symbol from another, the +value is absolute, not relocatable, and so the object file contains + +@example +Symnum n_type n_othr n_desc n_value n_strx String +31 STSYM 0 4 00000004 680 ld:V(0,3) +@end example + +without any relocations, and the executable file also contains + +@example +Symnum n_type n_othr n_desc n_value n_strx String +31 STSYM 0 4 00000004 680 ld:V(0,3) +@end example + +@node Cplusplus +@chapter GNU C++ Stabs + +@menu +* Class Names:: C++ class names are both tags and typedefs. +* Nested Symbols:: C++ symbol names can be within other types. +* Basic Cplusplus Types:: +* Simple Classes:: +* Class Instance:: +* Methods:: Method definition +* Method Type Descriptor:: The @samp{#} type descriptor +* Member Type Descriptor:: The @samp{@@} type descriptor +* Protections:: +* Method Modifiers:: +* Virtual Methods:: +* Inheritence:: +* Virtual Base Classes:: +* Static Members:: +@end menu + +@node Class Names +@section C++ Class Names + +In C++, a class name which is declared with @code{class}, @code{struct}, +or @code{union}, is not only a tag, as in C, but also a type name. Thus +there should be stabs with both @samp{t} and @samp{T} symbol descriptors +(@pxref{Typedefs}). + +To save space, there is a special abbreviation for this case. If the +@samp{T} symbol descriptor is followed by @samp{t}, then the stab +defines both a type name and a tag. + +For example, the C++ code + +@example +struct foo @{int x;@}; +@end example + +can be represented as either + +@example +.stabs "foo:T19=s4x:1,0,32;;",128,0,0,0 # @r{128 is N_LSYM} +.stabs "foo:t19",128,0,0,0 +@end example + +or + +@example +.stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0 +@end example + +@node Nested Symbols +@section Defining a Symbol Within Another Type + +In C++, a symbol (such as a type name) can be defined within another type. +@c FIXME: Needs example. + +In stabs, this is sometimes represented by making the name of a symbol +which contains @samp{::}. Such a pair of colons does not end the name +of the symbol, the way a single colon would (@pxref{String Field}). I'm +not sure how consistently used or well thought out this mechanism is. +So that a pair of colons in this position always has this meaning, +@samp{:} cannot be used as a symbol descriptor. + +For example, if the string for a stab is @samp{foo::bar::baz:t5=*6}, +then @code{foo::bar::baz} is the name of the symbol, @samp{t} is the +symbol descriptor, and @samp{5=*6} is the type information. + +@node Basic Cplusplus Types +@section Basic Types For C++ + +<< the examples that follow are based on a01.C >> + + +C++ adds two more builtin types to the set defined for C. These are +the unknown type and the vtable record type. The unknown type, type +16, is defined in terms of itself like the void type. + +The vtable record type, type 17, is defined as a structure type and +then as a structure tag. The structure has four fields: delta, index, +pfn, and delta2. pfn is the function pointer. + +<< In boilerplate $vtbl_ptr_type, what are the fields delta, +index, and delta2 used for? >> + +This basic type is present in all C++ programs even if there are no +virtual methods defined. + +@display +.stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8) + elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16); + elem_name(index):type_ref(short int),bit_offset(16),field_bits(16); + elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void), + bit_offset(32),field_bits(32); + elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;" + N_LSYM, NIL, NIL +@end display + +@smallexample +.stabs "$vtbl_ptr_type:t17=s8 + delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;" + ,128,0,0,0 +@end smallexample + +@display +.stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL +@end display + +@example +.stabs "$vtbl_ptr_type:T17",128,0,0,0 +@end example + +@node Simple Classes +@section Simple Class Definition + +The stabs describing C++ language features are an extension of the +stabs describing C. Stabs representing C++ class types elaborate +extensively on the stab format used to describe structure types in C. +Stabs representing class type variables look just like stabs +representing C language variables. + +Consider the following very simple class definition. + +@example +class baseA @{ +public: + int Adat; + int Ameth(int in, char other); +@}; +@end example + +The class @code{baseA} is represented by two stabs. The first stab describes +the class as a structure type. The second stab describes a structure +tag of the class type. Both stabs are of stab type @code{N_LSYM}. Since the +stab is not located between an @code{N_FUN} and an @code{N_LBRAC} stab this indicates +that the class is defined at file scope. If it were, then the @code{N_LSYM} +would signify a local variable. + +A stab describing a C++ class type is similar in format to a stab +describing a C struct, with each class member shown as a field in the +structure. The part of the struct format describing fields is +expanded to include extra information relevent to C++ class members. +In addition, if the class has multiple base classes or virtual +functions the struct format outside of the field parts is also +augmented. + +In this simple example the field part of the C++ class stab +representing member data looks just like the field part of a C struct +stab. The section on protections describes how its format is +sometimes extended for member data. + +The field part of a C++ class stab representing a member function +differs substantially from the field part of a C struct stab. It +still begins with @samp{name:} but then goes on to define a new type number +for the member function, describe its return type, its argument types, +its protection level, any qualifiers applied to the method definition, +and whether the method is virtual or not. If the method is virtual +then the method description goes on to give the vtable index of the +method, and the type number of the first base class defining the +method. + +When the field name is a method name it is followed by two colons rather +than one. This is followed by a new type definition for the method. +This is a number followed by an equal sign and the type of the method. +Normally this will be a type declared using the @samp{#} type +descriptor; see @ref{Method Type Descriptor}; static member functions +are declared using the @samp{f} type descriptor instead; see +@ref{Function Types}. + +The format of an overloaded operator method name differs from that of +other methods. It is @samp{op$::@var{operator-name}.} where +@var{operator-name} is the operator name such as @samp{+} or @samp{+=}. +The name ends with a period, and any characters except the period can +occur in the @var{operator-name} string. + +The next part of the method description represents the arguments to the +method, preceeded by a colon and ending with a semi-colon. The types of +the arguments are expressed in the same way argument types are expressed +in C++ name mangling. In this example an @code{int} and a @code{char} +map to @samp{ic}. + +This is followed by a number, a letter, and an asterisk or period, +followed by another semicolon. The number indicates the protections +that apply to the member function. Here the 2 means public. The +letter encodes any qualifier applied to the method definition. In +this case, @samp{A} means that it is a normal function definition. The dot +shows that the method is not virtual. The sections that follow +elaborate further on these fields and describe the additional +information present for virtual methods. + + +@display +.stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4) + field_name(Adat):type(int),bit_offset(0),field_bits(32); + + method_name(Ameth)::type_def(21)=type_desc(method)return_type(int); + :arg_types(int char); + protection(public)qualifier(normal)virtual(no);;" + N_LSYM,NIL,NIL,NIL +@end display + +@smallexample +.stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0 + +.stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL + +.stabs "baseA:T20",128,0,0,0 +@end smallexample + +@node Class Instance +@section Class Instance + +As shown above, describing even a simple C++ class definition is +accomplished by massively extending the stab format used in C to +describe structure types. However, once the class is defined, C stabs +with no modifications can be used to describe class instances. The +following source: + +@example +main () @{ + baseA AbaseA; +@} +@end example + +@noindent +yields the following stab describing the class instance. It looks no +different from a standard C stab describing a local variable. + +@display +.stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset +@end display + +@example +.stabs "AbaseA:20",128,0,0,-20 +@end example + +@node Methods +@section Method Definition + +The class definition shown above declares Ameth. The C++ source below +defines Ameth: + +@example +int +baseA::Ameth(int in, char other) +@{ + return in; +@}; +@end example + + +This method definition yields three stabs following the code of the +method. One stab describes the method itself and following two describe +its parameters. Although there is only one formal argument all methods +have an implicit argument which is the @code{this} pointer. The @code{this} +pointer is a pointer to the object on which the method was called. Note +that the method name is mangled to encode the class name and argument +types. Name mangling is described in the @sc{arm} (@cite{The Annotated +C++ Reference Manual}, by Ellis and Stroustrup, @sc{isbn} +0-201-51459-1); @file{gpcompare.texi} in Cygnus GCC distributions +describes the differences between GNU mangling and @sc{arm} +mangling. +@c FIXME: Use @xref, especially if this is generally installed in the +@c info tree. +@c FIXME: This information should be in a net release, either of GCC or +@c GDB. But gpcompare.texi doesn't seem to be in the FSF GCC. + +@example +.stabs "name:symbol_desriptor(global function)return_type(int)", + N_FUN, NIL, NIL, code_addr_of_method_start + +.stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic +@end example + +Here is the stab for the @code{this} pointer implicit argument. The +name of the @code{this} pointer is always @code{this}. Type 19, the +@code{this} pointer is defined as a pointer to type 20, @code{baseA}, +but a stab defining @code{baseA} has not yet been emited. Since the +compiler knows it will be emited shortly, here it just outputs a cross +reference to the undefined symbol, by prefixing the symbol name with +@samp{xs}. + +@example +.stabs "name:sym_desc(register param)type_def(19)= + type_desc(ptr to)type_ref(baseA)= + type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number + +.stabs "this:P19=*20=xsbaseA:",64,0,0,8 +@end example + +The stab for the explicit integer argument looks just like a parameter +to a C function. The last field of the stab is the offset from the +argument pointer, which in most systems is the same as the frame +pointer. + +@example +.stabs "name:sym_desc(value parameter)type_ref(int)", + N_PSYM,NIL,NIL,offset_from_arg_ptr + +.stabs "in:p1",160,0,0,72 +@end example + +<< The examples that follow are based on A1.C >> + +@node Method Type Descriptor +@section The @samp{#} Type Descriptor + +This is used to describe a class method. This is a function which takes +an extra argument as its first argument, for the @code{this} pointer. + +If the @samp{#} is immediately followed by another @samp{#}, the second +one will be followed by the return type and a semicolon. The class and +argument types are not specified, and must be determined by demangling +the name of the method if it is available. + +Otherwise, the single @samp{#} is followed by the class type, a comma, +the return type, a comma, and zero or more parameter types separated by +commas. The list of arguments is terminated by a semicolon. In the +debugging output generated by gcc, a final argument type of @code{void} +indicates a method which does not take a variable number of arguments. +If the final argument type of @code{void} does not appear, the method +was declared with an ellipsis. + +Note that although such a type will normally be used to describe fields +in structures, unions, or classes, for at least some versions of the +compiler it can also be used in other contexts. + +@node Member Type Descriptor +@section The @samp{@@} Type Descriptor + +The @samp{@@} type descriptor is for a member (class and variable) type. +It is followed by type information for the offset basetype, a comma, and +type information for the type of the field being pointed to. (FIXME: +this is acknowledged to be gibberish. Can anyone say what really goes +here?). + +Note that there is a conflict between this and type attributes +(@pxref{String Field}); both use type descriptor @samp{@@}. +Fortunately, the @samp{@@} type descriptor used in this C++ sense always +will be followed by a digit, @samp{(}, or @samp{-}, and type attributes +never start with those things. + +@node Protections +@section Protections + +In the simple class definition shown above all member data and +functions were publicly accessable. The example that follows +contrasts public, protected and privately accessable fields and shows +how these protections are encoded in C++ stabs. + +If the character following the @samp{@var{field-name}:} part of the +string is @samp{/}, then the next character is the visibility. @samp{0} +means private, @samp{1} means protected, and @samp{2} means public. +Debuggers should ignore visibility characters they do not recognize, and +assume a reasonable default (such as public) (GDB 4.11 does not, but +this should be fixed in the next GDB release). If no visibility is +specified the field is public. The visibility @samp{9} means that the +field has been optimized out and is public (there is no way to specify +an optimized out field with a private or protected visibility). +Visibility @samp{9} is not supported by GDB 4.11; this should be fixed +in the next GDB release. + +The following C++ source: + +@example +class vis @{ +private: + int priv; +protected: + char prot; +public: + float pub; +@}; +@end example + +@noindent +generates the following stab: + +@example +# @r{128 is N_LSYM} +.stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0 +@end example + +@samp{vis:T19=s12} indicates that type number 19 is a 12 byte structure +named @code{vis} The @code{priv} field has public visibility +(@samp{/0}), type int (@samp{1}), and offset and size @samp{,0,32;}. +The @code{prot} field has protected visibility (@samp{/1}), type char +(@samp{2}) and offset and size @samp{,32,8;}. The @code{pub} field has +type float (@samp{12}), and offset and size @samp{,64,32;}. + +Protections for member functions are signified by one digit embeded in +the field part of the stab describing the method. The digit is 0 if +private, 1 if protected and 2 if public. Consider the C++ class +definition below: + +@example +class all_methods @{ +private: + int priv_meth(int in)@{return in;@}; +protected: + char protMeth(char in)@{return in;@}; +public: + float pubMeth(float in)@{return in;@}; +@}; +@end example + +It generates the following stab. The digit in question is to the left +of an @samp{A} in each case. Notice also that in this case two symbol +descriptors apply to the class name struct tag and struct type. + +@display +.stabs "class_name:sym_desc(struct tag&type)type_def(21)= + sym_desc(struct)struct_bytes(1) + meth_name::type_def(22)=sym_desc(method)returning(int); + :args(int);protection(private)modifier(normal)virtual(no); + meth_name::type_def(23)=sym_desc(method)returning(char); + :args(char);protection(protected)modifier(normal)virual(no); + meth_name::type_def(24)=sym_desc(method)returning(float); + :args(float);protection(public)modifier(normal)virtual(no);;", + N_LSYM,NIL,NIL,NIL +@end display + +@smallexample +.stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.; + pubMeth::24=##12;:f;2A.;;",128,0,0,0 +@end smallexample + +@node Method Modifiers +@section Method Modifiers (@code{const}, @code{volatile}, @code{const volatile}) + +<< based on a6.C >> + +In the class example described above all the methods have the normal +modifier. This method modifier information is located just after the +protection information for the method. This field has four possible +character values. Normal methods use @samp{A}, const methods use +@samp{B}, volatile methods use @samp{C}, and const volatile methods use +@samp{D}. Consider the class definition below: + +@example +class A @{ +public: + int ConstMeth (int arg) const @{ return arg; @}; + char VolatileMeth (char arg) volatile @{ return arg; @}; + float ConstVolMeth (float arg) const volatile @{return arg; @}; +@}; +@end example + +This class is described by the following stab: + +@display +.stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1) + meth_name(ConstMeth)::type_def(21)sym_desc(method) + returning(int);:arg(int);protection(public)modifier(const)virtual(no); + meth_name(VolatileMeth)::type_def(22)=sym_desc(method) + returning(char);:arg(char);protection(public)modifier(volatile)virt(no) + meth_name(ConstVolMeth)::type_def(23)=sym_desc(method) + returning(float);:arg(float);protection(public)modifer(const volatile) + virtual(no);;", @dots{} +@end display + +@example +.stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.; + ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0 +@end example + +@node Virtual Methods +@section Virtual Methods + +<< The following examples are based on a4.C >> + +The presence of virtual methods in a class definition adds additional +data to the class description. The extra data is appended to the +description of the virtual method and to the end of the class +description. Consider the class definition below: + +@example +class A @{ +public: + int Adat; + virtual int A_virt (int arg) @{ return arg; @}; +@}; +@end example + +This results in the stab below describing class A. It defines a new +type (20) which is an 8 byte structure. The first field of the class +struct is @samp{Adat}, an integer, starting at structure offset 0 and +occupying 32 bits. + +The second field in the class struct is not explicitly defined by the +C++ class definition but is implied by the fact that the class +contains a virtual method. This field is the vtable pointer. The +name of the vtable pointer field starts with @samp{$vf} and continues with a +type reference to the class it is part of. In this example the type +reference for class A is 20 so the name of its vtable pointer field is +@samp{$vf20}, followed by the usual colon. + +Next there is a type definition for the vtable pointer type (21). +This is in turn defined as a pointer to another new type (22). + +Type 22 is the vtable itself, which is defined as an array, indexed by +a range of integers between 0 and 1, and whose elements are of type +17. Type 17 was the vtable record type defined by the boilerplate C++ +type definitions, as shown earlier. + +The bit offset of the vtable pointer field is 32. The number of bits +in the field are not specified when the field is a vtable pointer. + +Next is the method definition for the virtual member function @code{A_virt}. +Its description starts out using the same format as the non-virtual +member functions described above, except instead of a dot after the +@samp{A} there is an asterisk, indicating that the function is virtual. +Since is is virtual some addition information is appended to the end +of the method description. + +The first number represents the vtable index of the method. This is a +32 bit unsigned number with the high bit set, followed by a +semi-colon. + +The second number is a type reference to the first base class in the +inheritence hierarchy defining the virtual member function. In this +case the class stab describes a base class so the virtual function is +not overriding any other definition of the method. Therefore the +reference is to the type number of the class that the stab is +describing (20). + +This is followed by three semi-colons. One marks the end of the +current sub-section, one marks the end of the method field, and the +third marks the end of the struct definition. + +For classes containing virtual functions the very last section of the +string part of the stab holds a type reference to the first base +class. This is preceeded by @samp{~%} and followed by a final semi-colon. + +@display +.stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8) + field_name(Adat):type_ref(int),bit_offset(0),field_bits(32); + field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)= + sym_desc(array)index_type_ref(range of int from 0 to 1); + elem_type_ref(vtbl elem type), + bit_offset(32); + meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int); + :arg_type(int),protection(public)normal(yes)virtual(yes) + vtable_index(1);class_first_defining(A);;;~%first_base(A);", + N_LSYM,NIL,NIL,NIL +@end display + +@c FIXME: bogus line break. +@example +.stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; + A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 +@end example + +@node Inheritence +@section Inheritence + +Stabs describing C++ derived classes include additional sections that +describe the inheritence hierarchy of the class. A derived class stab +also encodes the number of base classes. For each base class it tells +if the base class is virtual or not, and if the inheritence is private +or public. It also gives the offset into the object of the portion of +the object corresponding to each base class. + +This additional information is embeded in the class stab following the +number of bytes in the struct. First the number of base classes +appears bracketed by an exclamation point and a comma. + +Then for each base type there repeats a series: a virtual character, a +visibilty character, a number, a comma, another number, and a +semi-colon. + +The virtual character is @samp{1} if the base class is virtual and +@samp{0} if not. The visibility character is @samp{2} if the derivation +is public, @samp{1} if it is protected, and @samp{0} if it is private. +Debuggers should ignore virtual or visibility characters they do not +recognize, and assume a reasonable default (such as public and +non-virtual) (GDB 4.11 does not, but this should be fixed in the next +GDB release). + +The number following the virtual and visibility characters is the offset +from the start of the object to the part of the object pertaining to the +base class. + +After the comma, the second number is a type_descriptor for the base +type. Finally a semi-colon ends the series, which repeats for each +base class. + +The source below defines three base classes @code{A}, @code{B}, and +@code{C} and the derived class @code{D}. + + +@example +class A @{ +public: + int Adat; + virtual int A_virt (int arg) @{ return arg; @}; +@}; + +class B @{ +public: + int B_dat; + virtual int B_virt (int arg) @{return arg; @}; +@}; + +class C @{ +public: + int Cdat; + virtual int C_virt (int arg) @{return arg; @}; +@}; + +class D : A, virtual B, public C @{ +public: + int Ddat; + virtual int A_virt (int arg ) @{ return arg+1; @}; + virtual int B_virt (int arg) @{ return arg+2; @}; + virtual int C_virt (int arg) @{ return arg+3; @}; + virtual int D_virt (int arg) @{ return arg; @}; +@}; +@end example + +Class stabs similar to the ones described earlier are generated for +each base class. + +@c FIXME!!! the linebreaks in the following example probably make the +@c examples literally unusable, but I don't know any other way to get +@c them on the page. +@c One solution would be to put some of the type definitions into +@c separate stabs, even if that's not exactly what the compiler actually +@c emits. +@smallexample +.stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; + A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 + +.stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1; + :i;2A*-2147483647;25;;;~%25;",128,0,0,0 + +.stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1; + :i;2A*-2147483647;28;;;~%28;",128,0,0,0 +@end smallexample + +In the stab describing derived class @code{D} below, the information about +the derivation of this class is encoded as follows. + +@display +.stabs "derived_class_name:symbol_descriptors(struct tag&type)= + type_descriptor(struct)struct_bytes(32)!num_bases(3), + base_virtual(no)inheritence_public(no)base_offset(0), + base_class_type_ref(A); + base_virtual(yes)inheritence_public(no)base_offset(NIL), + base_class_type_ref(B); + base_virtual(no)inheritence_public(yes)base_offset(64), + base_class_type_ref(C); @dots{} +@end display + +@c FIXME! fake linebreaks. +@smallexample +.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat: + 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt: + :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647; + 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 +@end smallexample + +@node Virtual Base Classes +@section Virtual Base Classes + +A derived class object consists of a concatination in memory of the data +areas defined by each base class, starting with the leftmost and ending +with the rightmost in the list of base classes. The exception to this +rule is for virtual inheritence. In the example above, class @code{D} +inherits virtually from base class @code{B}. This means that an +instance of a @code{D} object will not contain its own @code{B} part but +merely a pointer to a @code{B} part, known as a virtual base pointer. + +In a derived class stab, the base offset part of the derivation +information, described above, shows how the base class parts are +ordered. The base offset for a virtual base class is always given as 0. +Notice that the base offset for @code{B} is given as 0 even though +@code{B} is not the first base class. The first base class @code{A} +starts at offset 0. + +The field information part of the stab for class @code{D} describes the field +which is the pointer to the virtual base class @code{B}. The vbase pointer +name is @samp{$vb} followed by a type reference to the virtual base class. +Since the type id for @code{B} in this example is 25, the vbase pointer name +is @samp{$vb25}. + +@c FIXME!! fake linebreaks below +@smallexample +.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1, + 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i; + 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt: + :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 +@end smallexample + +Following the name and a semicolon is a type reference describing the +type of the virtual base class pointer, in this case 24. Type 24 was +defined earlier as the type of the @code{B} class @code{this} pointer. The +@code{this} pointer for a class is a pointer to the class type. + +@example +.stabs "this:P24=*25=xsB:",64,0,0,8 +@end example + +Finally the field offset part of the vbase pointer field description +shows that the vbase pointer is the first field in the @code{D} object, +before any data fields defined by the class. The layout of a @code{D} +class object is a follows, @code{Adat} at 0, the vtable pointer for +@code{A} at 32, @code{Cdat} at 64, the vtable pointer for C at 96, the +virtual base pointer for @code{B} at 128, and @code{Ddat} at 160. + + +@node Static Members +@section Static Members + +The data area for a class is a concatenation of the space used by the +data members of the class. If the class has virtual methods, a vtable +pointer follows the class data. The field offset part of each field +description in the class stab shows this ordering. + +<< How is this reflected in stabs? See Cygnus bug #677 for some info. >> + +@node Stab Types +@appendix Table of Stab Types + +The following are all the possible values for the stab type field, for +a.out files, in numeric order. This does not apply to XCOFF, but +it does apply to stabs in sections (@pxref{Stab Sections}). Stabs in +ECOFF use these values but add 0x8f300 to distinguish them from non-stab +symbols. + +The symbolic names are defined in the file @file{include/aout/stabs.def}. + +@menu +* Non-Stab Symbol Types:: Types from 0 to 0x1f +* Stab Symbol Types:: Types from 0x20 to 0xff +@end menu + +@node Non-Stab Symbol Types +@appendixsec Non-Stab Symbol Types + +The following types are used by the linker and assembler, not by stab +directives. Since this document does not attempt to describe aspects of +object file format other than the debugging format, no details are +given. + +@c Try to get most of these to fit on a single line. +@iftex +@tableindent=1.5in +@end iftex + +@table @code +@item 0x0 N_UNDF +Undefined symbol + +@item 0x2 N_ABS +File scope absolute symbol + +@item 0x3 N_ABS | N_EXT +External absolute symbol + +@item 0x4 N_TEXT +File scope text symbol + +@item 0x5 N_TEXT | N_EXT +External text symbol + +@item 0x6 N_DATA +File scope data symbol + +@item 0x7 N_DATA | N_EXT +External data symbol + +@item 0x8 N_BSS +File scope BSS symbol + +@item 0x9 N_BSS | N_EXT +External BSS symbol + +@item 0x0c N_FN_SEQ +Same as @code{N_FN}, for Sequent compilers + +@item 0x0a N_INDR +Symbol is indirected to another symbol + +@item 0x12 N_COMM +Common---visible after shared library dynamic link + +@item 0x14 N_SETA +@itemx 0x15 N_SETA | N_EXT +Absolute set element + +@item 0x16 N_SETT +@itemx 0x17 N_SETT | N_EXT +Text segment set element + +@item 0x18 N_SETD +@itemx 0x19 N_SETD | N_EXT +Data segment set element + +@item 0x1a N_SETB +@itemx 0x1b N_SETB | N_EXT +BSS segment set element + +@item 0x1c N_SETV +@itemx 0x1d N_SETV | N_EXT +Pointer to set vector + +@item 0x1e N_WARNING +Print a warning message during linking + +@item 0x1f N_FN +File name of a @file{.o} file +@end table + +@node Stab Symbol Types +@appendixsec Stab Symbol Types + +The following symbol types indicate that this is a stab. This is the +full list of stab numbers, including stab types that are used in +languages other than C. + +@table @code +@item 0x20 N_GSYM +Global symbol; see @ref{Global Variables}. + +@item 0x22 N_FNAME +Function name (for BSD Fortran); see @ref{Procedures}. + +@item 0x24 N_FUN +Function name (@pxref{Procedures}) or text segment variable +(@pxref{Statics}). + +@item 0x26 N_STSYM +Data segment file-scope variable; see @ref{Statics}. + +@item 0x28 N_LCSYM +BSS segment file-scope variable; see @ref{Statics}. + +@item 0x2a N_MAIN +Name of main routine; see @ref{Main Program}. + +@item 0x2c N_ROSYM +Variable in @code{.rodata} section; see @ref{Statics}. + +@item 0x30 N_PC +Global symbol (for Pascal); see @ref{N_PC}. + +@item 0x32 N_NSYMS +Number of symbols (according to Ultrix V4.0); see @ref{N_NSYMS}. + +@item 0x34 N_NOMAP +No DST map; see @ref{N_NOMAP}. + +@c FIXME: describe this solaris feature in the body of the text (see +@c comments in include/aout/stab.def). +@item 0x38 N_OBJ +Object file (Solaris2). + +@c See include/aout/stab.def for (a little) more info. +@item 0x3c N_OPT +Debugger options (Solaris2). + +@item 0x40 N_RSYM +Register variable; see @ref{Register Variables}. + +@item 0x42 N_M2C +Modula-2 compilation unit; see @ref{N_M2C}. + +@item 0x44 N_SLINE +Line number in text segment; see @ref{Line Numbers}. + +@item 0x46 N_DSLINE +Line number in data segment; see @ref{Line Numbers}. + +@item 0x48 N_BSLINE +Line number in bss segment; see @ref{Line Numbers}. + +@item 0x48 N_BROWS +Sun source code browser, path to @file{.cb} file; see @ref{N_BROWS}. + +@item 0x4a N_DEFD +GNU Modula2 definition module dependency; see @ref{N_DEFD}. + +@item 0x4c N_FLINE +Function start/body/end line numbers (Solaris2). + +@item 0x50 N_EHDECL +GNU C++ exception variable; see @ref{N_EHDECL}. + +@item 0x50 N_MOD2 +Modula2 info "for imc" (according to Ultrix V4.0); see @ref{N_MOD2}. + +@item 0x54 N_CATCH +GNU C++ @code{catch} clause; see @ref{N_CATCH}. + +@item 0x60 N_SSYM +Structure of union element; see @ref{N_SSYM}. + +@item 0x62 N_ENDM +Last stab for module (Solaris2). + +@item 0x64 N_SO +Path and name of source file; see @ref{Source Files}. + +@item 0x80 N_LSYM +Stack variable (@pxref{Stack Variables}) or type (@pxref{Typedefs}). + +@item 0x82 N_BINCL +Beginning of an include file (Sun only); see @ref{Include Files}. + +@item 0x84 N_SOL +Name of include file; see @ref{Include Files}. + +@item 0xa0 N_PSYM +Parameter variable; see @ref{Parameters}. + +@item 0xa2 N_EINCL +End of an include file; see @ref{Include Files}. + +@item 0xa4 N_ENTRY +Alternate entry point; see @ref{Alternate Entry Points}. + +@item 0xc0 N_LBRAC +Beginning of a lexical block; see @ref{Block Structure}. + +@item 0xc2 N_EXCL +Place holder for a deleted include file; see @ref{Include Files}. + +@item 0xc4 N_SCOPE +Modula2 scope information (Sun linker); see @ref{N_SCOPE}. + +@item 0xe0 N_RBRAC +End of a lexical block; see @ref{Block Structure}. + +@item 0xe2 N_BCOMM +Begin named common block; see @ref{Common Blocks}. + +@item 0xe4 N_ECOMM +End named common block; see @ref{Common Blocks}. + +@item 0xe8 N_ECOML +Member of a common block; see @ref{Common Blocks}. + +@c FIXME: How does this really work? Move it to main body of document. +@item 0xea N_WITH +Pascal @code{with} statement: type,,0,0,offset (Solaris2). + +@item 0xf0 N_NBTEXT +Gould non-base registers; see @ref{Gould}. + +@item 0xf2 N_NBDATA +Gould non-base registers; see @ref{Gould}. + +@item 0xf4 N_NBBSS +Gould non-base registers; see @ref{Gould}. + +@item 0xf6 N_NBSTS +Gould non-base registers; see @ref{Gould}. + +@item 0xf8 N_NBLCS +Gould non-base registers; see @ref{Gould}. +@end table + +@c Restore the default table indent +@iftex +@tableindent=.8in +@end iftex + +@node Symbol Descriptors +@appendix Table of Symbol Descriptors + +The symbol descriptor is the character which follows the colon in many +stabs, and which tells what kind of stab it is. @xref{String Field}, +for more information about their use. + +@c Please keep this alphabetical +@table @code +@c In TeX, this looks great, digit is in italics. But makeinfo insists +@c on putting it in `', not realizing that @var should override @code. +@c I don't know of any way to make makeinfo do the right thing. Seems +@c like a makeinfo bug to me. +@item @var{digit} +@itemx ( +@itemx - +Variable on the stack; see @ref{Stack Variables}. + +@item : +C++ nested symbol; see @xref{Nested Symbols} + +@item a +Parameter passed by reference in register; see @ref{Reference Parameters}. + +@item b +Based variable; see @ref{Based Variables}. + +@item c +Constant; see @ref{Constants}. + +@item C +Conformant array bound (Pascal, maybe other languages); @ref{Conformant +Arrays}. Name of a caught exception (GNU C++). These can be +distinguished because the latter uses @code{N_CATCH} and the former uses +another symbol type. + +@item d +Floating point register variable; see @ref{Register Variables}. + +@item D +Parameter in floating point register; see @ref{Register Parameters}. + +@item f +File scope function; see @ref{Procedures}. + +@item F +Global function; see @ref{Procedures}. + +@item G +Global variable; see @ref{Global Variables}. + +@item i +@xref{Register Parameters}. + +@item I +Internal (nested) procedure; see @ref{Nested Procedures}. + +@item J +Internal (nested) function; see @ref{Nested Procedures}. + +@item L +Label name (documented by AIX, no further information known). + +@item m +Module; see @ref{Procedures}. + +@item p +Argument list parameter; see @ref{Parameters}. + +@item pP +@xref{Parameters}. + +@item pF +Fortran Function parameter; see @ref{Parameters}. + +@item P +Unfortunately, three separate meanings have been independently invented +for this symbol descriptor. At least the GNU and Sun uses can be +distinguished by the symbol type. Global Procedure (AIX) (symbol type +used unknown); see @ref{Procedures}. Register parameter (GNU) (symbol +type @code{N_PSYM}); see @ref{Parameters}. Prototype of function +referenced by this file (Sun @code{acc}) (symbol type @code{N_FUN}). + +@item Q +Static Procedure; see @ref{Procedures}. + +@item R +Register parameter; see @ref{Register Parameters}. + +@item r +Register variable; see @ref{Register Variables}. + +@item S +File scope variable; see @ref{Statics}. + +@item s +Local variable (OS9000). + +@item t +Type name; see @ref{Typedefs}. + +@item T +Enumeration, structure, or union tag; see @ref{Typedefs}. + +@item v +Parameter passed by reference; see @ref{Reference Parameters}. + +@item V +Procedure scope static variable; see @ref{Statics}. + +@item x +Conformant array; see @ref{Conformant Arrays}. + +@item X +Function return variable; see @ref{Parameters}. +@end table + +@node Type Descriptors +@appendix Table of Type Descriptors + +The type descriptor is the character which follows the type number and +an equals sign. It specifies what kind of type is being defined. +@xref{String Field}, for more information about their use. + +@table @code +@item @var{digit} +@itemx ( +Type reference; see @ref{String Field}. + +@item - +Reference to builtin type; see @ref{Negative Type Numbers}. + +@item # +Method (C++); see @ref{Method Type Descriptor}. + +@item * +Pointer; see @ref{Miscellaneous Types}. + +@item & +Reference (C++). + +@item @@ +Type Attributes (AIX); see @ref{String Field}. Member (class and variable) +type (GNU C++); see @ref{Member Type Descriptor}. + +@item a +Array; see @ref{Arrays}. + +@item A +Open array; see @ref{Arrays}. + +@item b +Pascal space type (AIX); see @ref{Miscellaneous Types}. Builtin integer +type (Sun); see @ref{Builtin Type Descriptors}. Const and volatile +qualfied type (OS9000). + +@item B +Volatile-qualified type; see @ref{Miscellaneous Types}. + +@item c +Complex builtin type (AIX); see @ref{Builtin Type Descriptors}. +Const-qualified type (OS9000). + +@item C +COBOL Picture type. See AIX documentation for details. + +@item d +File type; see @ref{Miscellaneous Types}. + +@item D +N-dimensional dynamic array; see @ref{Arrays}. + +@item e +Enumeration type; see @ref{Enumerations}. + +@item E +N-dimensional subarray; see @ref{Arrays}. + +@item f +Function type; see @ref{Function Types}. + +@item F +Pascal function parameter; see @ref{Function Types} + +@item g +Builtin floating point type; see @ref{Builtin Type Descriptors}. + +@item G +COBOL Group. See AIX documentation for details. + +@item i +Imported type (AIX); see @ref{Cross-References}. Volatile-qualified +type (OS9000). + +@item k +Const-qualified type; see @ref{Miscellaneous Types}. + +@item K +COBOL File Descriptor. See AIX documentation for details. + +@item M +Multiple instance type; see @ref{Miscellaneous Types}. + +@item n +String type; see @ref{Strings}. + +@item N +Stringptr; see @ref{Strings}. + +@item o +Opaque type; see @ref{Typedefs}. + +@item p +Procedure; see @ref{Function Types}. + +@item P +Packed array; see @ref{Arrays}. + +@item r +Range type; see @ref{Subranges}. + +@item R +Builtin floating type; see @ref{Builtin Type Descriptors} (Sun). Pascal +subroutine parameter; see @ref{Function Types} (AIX). Detecting this +conflict is possible with careful parsing (hint: a Pascal subroutine +parameter type will always contain a comma, and a builtin type +descriptor never will). + +@item s +Structure type; see @ref{Structures}. + +@item S +Set type; see @ref{Miscellaneous Types}. + +@item u +Union; see @ref{Unions}. + +@item v +Variant record. This is a Pascal and Modula-2 feature which is like a +union within a struct in C. See AIX documentation for details. + +@item w +Wide character; see @ref{Builtin Type Descriptors}. + +@item x +Cross-reference; see @ref{Cross-References}. + +@item Y +Used by IBM's xlC C++ compiler (for structures, I think). + +@item z +gstring; see @ref{Strings}. +@end table + +@node Expanded Reference +@appendix Expanded Reference by Stab Type + +@c FIXME: This appendix should go away; see N_PSYM or N_SO for an example. + +For a full list of stab types, and cross-references to where they are +described, see @ref{Stab Types}. This appendix just covers certain +stabs which are not yet described in the main body of this document; +eventually the information will all be in one place. + +Format of an entry: + +The first line is the symbol type (see @file{include/aout/stab.def}). + +The second line describes the language constructs the symbol type +represents. + +The third line is the stab format with the significant stab fields +named and the rest NIL. + +Subsequent lines expand upon the meaning and possible values for each +significant stab field. + +Finally, any further information. + +@menu +* N_PC:: Pascal global symbol +* N_NSYMS:: Number of symbols +* N_NOMAP:: No DST map +* N_M2C:: Modula-2 compilation unit +* N_BROWS:: Path to .cb file for Sun source code browser +* N_DEFD:: GNU Modula2 definition module dependency +* N_EHDECL:: GNU C++ exception variable +* N_MOD2:: Modula2 information "for imc" +* N_CATCH:: GNU C++ "catch" clause +* N_SSYM:: Structure or union element +* N_SCOPE:: Modula2 scope information (Sun only) +* Gould:: non-base register symbols used on Gould systems +* N_LENG:: Length of preceding entry +@end menu + +@node N_PC +@section N_PC + +@deffn @code{.stabs} N_PC +@findex N_PC +Global symbol (for Pascal). + +@example +"name" -> "symbol_name" <<?>> +value -> supposedly the line number (stab.def is skeptical) +@end example + +@display +@file{stabdump.c} says: + +global pascal symbol: name,,0,subtype,line +<< subtype? >> +@end display +@end deffn + +@node N_NSYMS +@section N_NSYMS + +@deffn @code{.stabn} N_NSYMS +@findex N_NSYMS +Number of symbols (according to Ultrix V4.0). + +@display + 0, files,,funcs,lines (stab.def) +@end display +@end deffn + +@node N_NOMAP +@section N_NOMAP + +@deffn @code{.stabs} N_NOMAP +@findex N_NOMAP +No DST map for symbol (according to Ultrix V4.0). I think this means a +variable has been optimized out. + +@display + name, ,0,type,ignored (stab.def) +@end display +@end deffn + +@node N_M2C +@section N_M2C + +@deffn @code{.stabs} N_M2C +@findex N_M2C +Modula-2 compilation unit. + +@example +"string" -> "unit_name,unit_time_stamp[,code_time_stamp]" +desc -> unit_number +value -> 0 (main unit) + 1 (any other unit) +@end example + +See @cite{Dbx and Dbxtool Interfaces}, 2nd edition, by Sun, 1988, for +more information. + +@end deffn + +@node N_BROWS +@section N_BROWS + +@deffn @code{.stabs} N_BROWS +@findex N_BROWS +Sun source code browser, path to @file{.cb} file + +<<?>> +"path to associated @file{.cb} file" + +Note: N_BROWS has the same value as N_BSLINE. +@end deffn + +@node N_DEFD +@section N_DEFD + +@deffn @code{.stabn} N_DEFD +@findex N_DEFD +GNU Modula2 definition module dependency. + +GNU Modula-2 definition module dependency. The value is the +modification time of the definition file. The other field is non-zero +if it is imported with the GNU M2 keyword @code{%INITIALIZE}. Perhaps +@code{N_M2C} can be used if there are enough empty fields? +@end deffn + +@node N_EHDECL +@section N_EHDECL + +@deffn @code{.stabs} N_EHDECL +@findex N_EHDECL +GNU C++ exception variable <<?>>. + +"@var{string} is variable name" + +Note: conflicts with @code{N_MOD2}. +@end deffn + +@node N_MOD2 +@section N_MOD2 + +@deffn @code{.stab?} N_MOD2 +@findex N_MOD2 +Modula2 info "for imc" (according to Ultrix V4.0) + +Note: conflicts with @code{N_EHDECL} <<?>> +@end deffn + +@node N_CATCH +@section N_CATCH + +@deffn @code{.stabn} N_CATCH +@findex N_CATCH +GNU C++ @code{catch} clause + +GNU C++ @code{catch} clause. The value is its address. The desc field +is nonzero if this entry is immediately followed by a @code{CAUGHT} stab +saying what exception was caught. Multiple @code{CAUGHT} stabs means +that multiple exceptions can be caught here. If desc is 0, it means all +exceptions are caught here. +@end deffn + +@node N_SSYM +@section N_SSYM + +@deffn @code{.stabn} N_SSYM +@findex N_SSYM +Structure or union element. + +The value is the offset in the structure. + +<<?looking at structs and unions in C I didn't see these>> +@end deffn + +@node N_SCOPE +@section N_SCOPE + +@deffn @code{.stab?} N_SCOPE +@findex N_SCOPE +Modula2 scope information (Sun linker) +<<?>> +@end deffn + +@node Gould +@section Non-base registers on Gould systems + +@deffn @code{.stab?} N_NBTEXT +@deffnx @code{.stab?} N_NBDATA +@deffnx @code{.stab?} N_NBBSS +@deffnx @code{.stab?} N_NBSTS +@deffnx @code{.stab?} N_NBLCS +@findex N_NBTEXT +@findex N_NBDATA +@findex N_NBBSS +@findex N_NBSTS +@findex N_NBLCS +These are used on Gould systems for non-base registers syms. + +However, the following values are not the values used by Gould; they are +the values which GNU has been documenting for these values for a long +time, without actually checking what Gould uses. I include these values +only because perhaps some someone actually did something with the GNU +information (I hope not, why GNU knowingly assigned wrong values to +these in the header file is a complete mystery to me). + +@example +240 0xf0 N_NBTEXT ?? +242 0xf2 N_NBDATA ?? +244 0xf4 N_NBBSS ?? +246 0xf6 N_NBSTS ?? +248 0xf8 N_NBLCS ?? +@end example +@end deffn + +@node N_LENG +@section N_LENG + +@deffn @code{.stabn} N_LENG +@findex N_LENG +Second symbol entry containing a length-value for the preceding entry. +The value is the length. +@end deffn + +@node Questions +@appendix Questions and Anomalies + +@itemize @bullet +@item +@c I think this is changed in GCC 2.4.5 to put the line number there. +For GNU C stabs defining local and global variables (@code{N_LSYM} and +@code{N_GSYM}), the desc field is supposed to contain the source +line number on which the variable is defined. In reality the desc +field is always 0. (This behavior is defined in @file{dbxout.c} and +putting a line number in desc is controlled by @samp{#ifdef +WINNING_GDB}, which defaults to false). GDB supposedly uses this +information if you say @samp{list @var{var}}. In reality, @var{var} can +be a variable defined in the program and GDB says @samp{function +@var{var} not defined}. + +@item +In GNU C stabs, there seems to be no way to differentiate tag types: +structures, unions, and enums (symbol descriptor @samp{T}) and typedefs +(symbol descriptor @samp{t}) defined at file scope from types defined locally +to a procedure or other more local scope. They all use the @code{N_LSYM} +stab type. Types defined at procedure scope are emited after the +@code{N_RBRAC} of the preceding function and before the code of the +procedure in which they are defined. This is exactly the same as +types defined in the source file between the two procedure bodies. +GDB overcompensates by placing all types in block #1, the block for +symbols of file scope. This is true for default, @samp{-ansi} and +@samp{-traditional} compiler options. (Bugs gcc/1063, gdb/1066.) + +@item +What ends the procedure scope? Is it the proc block's @code{N_RBRAC} or the +next @code{N_FUN}? (I believe its the first.) +@end itemize + +@node Stab Sections +@appendix Using Stabs in Their Own Sections + +Many object file formats allow tools to create object files with custom +sections containing any arbitrary data. For any such object file +format, stabs can be embedded in special sections. This is how stabs +are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs +are used with COFF. + +@menu +* Stab Section Basics:: How to embed stabs in sections +* ELF Linker Relocation:: Sun ELF hacks +@end menu + +@node Stab Section Basics +@appendixsec How to Embed Stabs in Sections + +The assembler creates two custom sections, a section named @code{.stab} +which contains an array of fixed length structures, one struct per stab, +and a section named @code{.stabstr} containing all the variable length +strings that are referenced by stabs in the @code{.stab} section. The +byte order of the stabs binary data depends on the object file format. +For ELF, it matches the byte order of the ELF file itself, as determined +from the @code{EI_DATA} field in the @code{e_ident} member of the ELF +header. For SOM, it is always big-endian (is this true??? FIXME). For +COFF, it matches the byte order of the COFF headers. The meaning of the +fields is the same as for a.out (@pxref{Symbol Table Format}), except +that the @code{n_strx} field is relative to the strings for the current +compilation unit (which can be found using the synthetic N_UNDF stab +described below), rather than the entire string table. + +The first stab in the @code{.stab} section for each compilation unit is +synthetic, generated entirely by the assembler, with no corresponding +@code{.stab} directive as input to the assembler. This stab contains +the following fields: + +@table @code +@item n_strx +Offset in the @code{.stabstr} section to the source filename. + +@item n_type +@code{N_UNDF}. + +@item n_other +Unused field, always zero. +This may eventually be used to hold overflows from the count in +the @code{n_desc} field. + +@item n_desc +Count of upcoming symbols, i.e., the number of remaining stabs for this +source file. + +@item n_value +Size of the string table fragment associated with this source file, in +bytes. +@end table + +The @code{.stabstr} section always starts with a null byte (so that string +offsets of zero reference a null string), followed by random length strings, +each of which is null byte terminated. + +The ELF section header for the @code{.stab} section has its +@code{sh_link} member set to the section number of the @code{.stabstr} +section, and the @code{.stabstr} section has its ELF section +header @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a +string table. SOM and COFF have no way of linking the sections together +or marking them as string tables. + +For COFF, the @code{.stab} and @code{.stabstr} sections may be simply +concatenated by the linker. GDB then uses the @code{n_desc} fields to +figure out the extent of the original sections. Similarly, the +@code{n_value} fields of the header symbols are added together in order +to get the actual position of the strings in a desired @code{.stabstr} +section. Although this design obviates any need for the linker to +relocate or otherwise manipulate @code{.stab} and @code{.stabstr} +sections, it also requires some care to ensure that the offsets are +calculated correctly. For instance, if the linker were to pad in +between the @code{.stabstr} sections before concatenating, then the +offsets to strings in the middle of the executable's @code{.stabstr} +section would be wrong. + +The GNU linker is able to optimize stabs information by merging +duplicate strings and removing duplicate header file information +(@pxref{Include Files}). When some versions of the GNU linker optimize +stabs in sections, they remove the leading @code{N_UNDF} symbol and +arranges for all the @code{n_strx} fields to be relative to the start of +the @code{.stabstr} section. + +@node ELF Linker Relocation +@appendixsec Having the Linker Relocate Stabs in ELF + +This section describes some Sun hacks for Stabs in ELF; it does not +apply to COFF or SOM. + +To keep linking fast, you don't want the linker to have to relocate very +many stabs. Making sure this is done for @code{N_SLINE}, +@code{N_RBRAC}, and @code{N_LBRAC} stabs is the most important thing +(see the descriptions of those stabs for more information). But Sun's +stabs in ELF has taken this further, to make all addresses in the +@code{n_value} field (functions and static variables) relative to the +source file. For the @code{N_SO} symbol itself, Sun simply omits the +address. To find the address of each section corresponding to a given +source file, the compiler puts out symbols giving the address of each +section for a given source file. Since these are ELF (not stab) +symbols, the linker relocates them correctly without having to touch the +stabs section. They are named @code{Bbss.bss} for the bss section, +@code{Ddata.data} for the data section, and @code{Drodata.rodata} for +the rodata section. For the text section, there is no such symbol (but +there should be, see below). For an example of how these symbols work, +@xref{Stab Section Transformations}. GCC does not provide these symbols; +it instead relies on the stabs getting relocated. Thus addresses which +would normally be relative to @code{Bbss.bss}, etc., are already +relocated. The Sun linker provided with Solaris 2.2 and earlier +relocates stabs using normal ELF relocation information, as it would do +for any section. Sun has been threatening to kludge their linker to not +do this (to speed up linking), even though the correct way to avoid +having the linker do these relocations is to have the compiler no longer +output relocatable values. Last I heard they had been talked out of the +linker kludge. See Sun point patch 101052-01 and Sun bug 1142109. With +the Sun compiler this affects @samp{S} symbol descriptor stabs +(@pxref{Statics}) and functions (@pxref{Procedures}). In the latter +case, to adopt the clean solution (making the value of the stab relative +to the start of the compilation unit), it would be necessary to invent a +@code{Ttext.text} symbol, analogous to the @code{Bbss.bss}, etc., +symbols. I recommend this rather than using a zero value and getting +the address from the ELF symbols. + +Finding the correct @code{Bbss.bss}, etc., symbol is difficult, because +the linker simply concatenates the @code{.stab} sections from each +@file{.o} file without including any information about which part of a +@code{.stab} section comes from which @file{.o} file. The way GDB does +this is to look for an ELF @code{STT_FILE} symbol which has the same +name as the last component of the file name from the @code{N_SO} symbol +in the stabs (for example, if the file name is @file{../../gdb/main.c}, +it looks for an ELF @code{STT_FILE} symbol named @code{main.c}). This +loses if different files have the same name (they could be in different +directories, a library could have been copied from one system to +another, etc.). It would be much cleaner to have the @code{Bbss.bss} +symbols in the stabs themselves. Having the linker relocate them there +is no more work than having the linker relocate ELF symbols, and it +solves the problem of having to associate the ELF and stab symbols. +However, no one has yet designed or implemented such a scheme. + +@node Symbol Types Index +@unnumbered Symbol Types Index + +@printindex fn + +@contents +@bye |