@ifinfo
This document describes the stabs debugging symbol tables.
-Copyright 1992, 1993 Free Software Foundation, Inc.
+Copyright 1992,1993,1994,1995,1997,1998,2000,2001
+ 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.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
-@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).
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
@end ifinfo
@setchapternewpage odd
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1992, 1993 Free Software Foundation, Inc.
+Copyright @copyright{} 1992,1993,1994,1995,1997,1998,2000,2001 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.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
@end titlepage
* Variables::
* Types:: Type definitions
* Symbol Tables:: Symbol information in symbol tables
-* Cplusplus:: Appendixes:
+* 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
-* XCOFF Differences:: Differences between GNU stabs in a.out
- and GNU stabs in XCOFF
-* Sun Differences:: Differences between GNU stabs and Sun
- native stabs
+* Questions:: Questions and anomalies
* 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
+@c TeX can handle the contents at the start but makeinfo 3.12 can not
+@iftex
+@contents
+@end iftex
@node Overview
@chapter Overview of Stabs
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 0 for the base source file, 1 for the first included file, 2 for the
+next, and so on. 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
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.
+function. I'm not sure how XCOFF handles this.
@node Source Files
@section Paths and Names of the Source Files
Ltext0:
@end example
+@findex C_FILE
Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler
-directive which assembles to a standard COFF @code{.file} symbol;
-explaining this in detail is outside the scope of this document.
+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
@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 Sun 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; the Sun
-linker puts data into some of the fields. @code{N_BINCL} and
+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 Sun (SunOS4, not sure about Solaris) linker is the only one which
-supports this feature.
-@c What do the fields of N_EXCL contain? -djm
+additional occurrence 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
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. 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).
-
+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. The
-value is the address of the start of the function. For @code{a.out}, 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.
+(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
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
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.
+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
@dfn{automatic}), it can be allocated in a register (@pxref{Register
Variables}) or on the stack.
-@findex N_LSYM
+@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
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.
+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
.stabn 224,0,0,LBE2 # @r{224 is N_RBRAC}
@end example
-@xref{Procedures} for more information on the @code{N_FUN} stab, and
+See @ref{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.
@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. The type information for the stab
-(@pxref{String Field}) gives the type of the variable.
+@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:
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}, and their
-own symbol descriptor, @samp{r}. The stab's value is the
-number of the register where the variable data will be stored.
+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
.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 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.
+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.
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. 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.
+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:
@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 with @samp{R} and
-@code{N_RSYM} is used with @samp{P}. 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.
+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
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
+The traditional way to define builtin types is convoluted, 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
formats. The following sections describe each of these formats.
@menu
-* Traditional Builtin Types:: Put on your seatbelts and prepare for kludgery
+* Traditional Builtin Types:: Put on your seat belts and prepare for kludgery
* Builtin Type Descriptors:: Builtin types with special type descriptors
* Negative Type Numbers:: Builtin types using negative type numbers
@end menu
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?).
+precision? Double precision?).
@item 6 (NF_LDOUBLE)
Long double. This should probably only be used for Sun format
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). For example,
+like AIX dbx or GDB). For example,
@example
.stabs "boolean:t10=@@s8;-16",128,0,0,0
@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
the argument list.
@item a @var{register-number}
-The bound is pased by reference in register number
+The bound is passed by reference in register number
@var{register-number}.
@item t @var{register-number}
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 with a new type. Separate 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
+stabs for the tag and the @code{typedef} are emitted 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.
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.
+array element looks just like a type definition for a stand-alone 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.
@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,
@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).
+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 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
+for @code{u_type} do not convey any information about its procedure local
scope.
@c FIXME: phony line break. Can probably be fixed by using an example
* Protections::
* Method Modifiers::
* Virtual Methods::
-* Inheritence::
+* Inheritance::
* Virtual Base Classes::
* Static Members::
@end menu
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.
+expanded to include extra information relevant 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.
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
+method, preceded 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}.
@c GDB. But gpcompare.texi doesn't seem to be in the FSF GCC.
@example
-.stabs "name:symbol_desriptor(global function)return_type(int)",
+.stabs "name:symbol_descriptor(global function)return_type(int)",
N_FUN, NIL, NIL, code_addr_of_method_start
.stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic
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
+but a stab defining @code{baseA} has not yet been emitted. Since the
+compiler knows it will be emitted shortly, here it just outputs a cross
reference to the undefined symbol, by prefixing the symbol name with
@samp{xs}.
@node Method Type Descriptor
@section The @samp{#} Type Descriptor
-This is like the @samp{f} type descriptor for functions (@pxref{Function
-Types}), except that a function which uses the @samp{#} type descriptor
-takes an extra argument as its first argument, for the @code{this}
-pointer. The @samp{#} type descriptor is optionally followed by the
-types of the arguments, then another @samp{#}. If the types of the
-arguments are omitted, so that the second @samp{#} immediately follows
-the @samp{#} which is the type descriptor, the arguments are being
-omitted (to save space) and can be deduced from the mangled name of the
-method. After the second @samp{#} there is type information for the
-return type of the method and a semicolon.
+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
@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
+functions were publicly accessible. The example that follows
+contrasts public, protected and privately accessible fields and shows
how these protections are encoded in C++ stabs.
If the character following the @samp{@var{field-name}:} part of the
(@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
+Protections for member functions are signified by one digit embedded 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:
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);
+ :args(char);protection(protected)modifier(normal)virtual(no);
meth_name::type_def(24)=sym_desc(method)returning(float);
:args(float);protection(public)modifier(normal)virtual(no);;",
N_LSYM,NIL,NIL,NIL
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)
+ returning(float);:arg(float);protection(public)modifier(const volatile)
virtual(no);;", @dots{}
@end display
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
+inheritance 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
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.
+class. This is preceded by @samp{~%} and followed by a final semi-colon.
@display
.stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8)
A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
@end example
-@node Inheritence
-@section Inheritence
+@node Inheritance
+@section Inheritance
Stabs describing C++ derived classes include additional sections that
-describe the inheritence hierarchy of the class. A derived class stab
+describe the inheritance 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
+if the base class is virtual or not, and if the inheritance 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
+This additional information is embedded 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
+visibility character, a number, a comma, another number, and a
semi-colon.
The virtual character is @samp{1} if the base class is virtual and
@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_virtual(no)inheritance_public(no)base_offset(0),
base_class_type_ref(A);
- base_virtual(yes)inheritence_public(no)base_offset(NIL),
+ base_virtual(yes)inheritance_public(no)base_offset(NIL),
base_class_type_ref(B);
- base_virtual(no)inheritence_public(yes)base_offset(64),
+ base_virtual(no)inheritance_public(yes)base_offset(64),
base_class_type_ref(C); @dots{}
@end display
@node Virtual Base Classes
@section Virtual Base Classes
-A derived class object consists of a concatination in memory of the data
+A derived class object consists of a concatenation 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}
+rule is for virtual inheritance. 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.
@appendix Table of Stab Types
The following are all the possible values for the stab type field, for
-@code{a.out} files, in numeric order. This does not apply to XCOFF, but
+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.
Variable on the stack; see @ref{Stack Variables}.
@item :
-C++ nested symbol; see @xref{Nested Symbols}
+C++ nested symbol; see @xref{Nested Symbols}.
@item a
Parameter passed by reference in register; see @ref{Reference Parameters}.
@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).
+qualified type (OS9000).
@item B
Volatile-qualified type; see @ref{Miscellaneous Types}.
@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 duplicates certain
-information from the main body of this document; eventually the
-information will all be in one place.
+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:
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
+stab type. Types defined at procedure scope are emitted 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
+GDB over-compensates 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.)
-
-@item
-@c FIXME: This should go with the other stuff about global variables.
-Global variable stabs don't have location information. This comes
-from the external symbol for the same variable. The external symbol
-has a leading underbar on the _name of the variable and the stab does
-not. How do we know these two symbol table entries are talking about
-the same symbol when their names are different? (Answer: the debugger
-knows that external symbols have leading underbars).
-
-@c FIXME: This is absurdly vague; there all kinds of differences, some
-@c of which are the same between gnu & sun, and some of which aren't.
-@c In particular, I'm pretty sure GCC works with Sun dbx by default.
-@c @item
-@c Can GCC be configured to output stabs the way the Sun compiler
-@c does, so that their native debugging tools work? <NO?> It doesn't by
-@c default. GDB reads either format of stab. (GCC or SunC). How about
-@c dbx?
-@end itemize
-
-@node XCOFF Differences
-@appendix Differences Between GNU Stabs in a.out and GNU Stabs in XCOFF
-
-@c FIXME: Merge *all* these into the main body of the document.
-The AIX/RS6000 native object file format is XCOFF with stabs. This
-appendix only covers those differences which are not covered in the main
-body of this document.
-
-@itemize @bullet
-@item
-BSD a.out stab types correspond to AIX XCOFF storage classes. In general
-the mapping is @code{N_@var{stabtype}} becomes @code{C_@var{stabtype}}.
-Some stab types in a.out are not supported in XCOFF; most of these use
-@code{C_DECL}.
-
-@c FIXME: I think they are trying to say something about whether the
-@c assembler defaults the value to the location counter.
-@item
-If the XCOFF stab is an @code{N_FUN} (@code{C_FUN}) then follow the
-string field with @samp{,.} instead of just @samp{,}.
-@end itemize
-
-I think that's it for @file{.s} file differences. They could stand to be
-better presented. This is just a list of what I have noticed so far.
-There are a @emph{lot} of differences in the information in the symbol
-tables of the executable and object files.
-
-Mapping of a.out stab types to XCOFF storage classes:
-
-@example
-stab type storage class
--------------------------------
-N_GSYM C_GSYM
-N_FNAME unused
-N_FUN C_FUN
-N_STSYM C_STSYM
-N_LCSYM C_STSYM
-N_MAIN unknown
-N_PC unknown
-N_RSYM C_RSYM
-unknown C_RPSYM
-N_M2C unknown
-N_SLINE unknown
-N_DSLINE unknown
-N_BSLINE unknown
-N_BROWSE unchanged
-N_CATCH unknown
-N_SSYM unknown
-N_SO unknown
-N_LSYM C_LSYM
-various C_DECL
-N_BINCL unknown
-N_SOL unknown
-N_PSYM C_PSYM
-N_EINCL unknown
-N_ENTRY C_ENTRY
-N_LBRAC unknown
-N_EXCL unknown
-N_SCOPE unknown
-N_RBRAC unknown
-N_BCOMM C_BCOMM
-N_ECOMM C_ECOMM
-N_ECOML C_ECOML
-
-N_LENG unknown
-@end example
-
-@node Sun Differences
-@appendix Differences Between GNU Stabs and Sun Native Stabs
-
-@c FIXME: Merge all this stuff into the main body of the document.
-
-@itemize @bullet
-@item
-GNU C stabs define @emph{all} types, file or procedure scope, as
-@code{N_LSYM}. Sun doc talks about using @code{N_GSYM} too.
-
-@item
-Sun C stabs use type number pairs in the format
-(@var{file-number},@var{type-number}) where @var{file-number} is a
-number starting with 1 and incremented for each sub-source file in the
-compilation. @var{type-number} is a number starting with 1 and
-incremented for each new type defined in the compilation. GNU C stabs
-use the type number alone, with no source file number.
@end itemize
@node Stab Sections
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.
+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
@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
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
@printindex fn
+@c TeX can handle the contents at the start but makeinfo 3.12 can not
+@ifinfo
@contents
+@end ifinfo
+@ifhtml
+@contents
+@end ifhtml
+
@bye
projects / deliverable / binutils-gdb.git / blobdiff