@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
* Symbol Descriptors:: Table of symbol descriptors
* Type Descriptors:: Table of type descriptors
* Expanded Reference:: Reference information by stab type
-* Questions:: Questions and anomolies
-* 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
@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
+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
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.
-
-The SunOS4 linker sets 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 the file number. The value of an @code{N_EXCL} symbol is the
-same as the value of the @code{N_BINCL} symbol it replaces. I do not
-know if this information is used by anything. The @code{N_EINCL} value,
-and the values of the other and description fields for all three, appear
-to always be zero.
+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
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
.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.
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
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.
@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.
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}.
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.)
next @code{N_FUN}? (I believe its the first.)
@end itemize
-@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
@appendix Using Stabs in Their Own Sections
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 are simply
+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.
+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