\input texinfo
@setfilename stabs.info
+@setchapternewpage odd
+@settitle STABS
-@c @finalout
+@c man begin INCLUDE
+@include gdb-cfg.texi
+@c man end
-@ifinfo
-@format
-START-INFO-DIR-ENTRY
-* Stabs:: The "stabs" debugging information format.
-END-INFO-DIR-ENTRY
-@end format
-@end ifinfo
+@c @finalout
-@ifinfo
-This document describes the stabs debugging symbol tables.
+@c This is a dir.info fragment to support semi-automated addition of
+@c manuals to an info tree.
+@dircategory Software development
+@direntry
+* Stabs: (stabs). The "stabs" debugging information format.
+@end direntry
-Copyright 1992, 1993 Free Software Foundation, Inc.
+@copying
+Copyright @copyright{} 1992-2019 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.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end copying
-@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).
+@ifnottex
+This document describes the stabs debugging symbol tables.
-@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
+@insertcopying
+@end ifnottex
-@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 $...$
+\def\$#1${{#1}} % Kludge: collect RCS revision info without $...$
\xdef\manvers{\$Revision$} % For use in headers, footers too
{\parskip=0pt
\hfill Cygnus Support\par
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1992, 1993 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.
-
+@insertcopying
@end titlepage
-@ifinfo
+@ifnottex
@node Top
@top The "stabs" representation of debugging information
* Constants:: Constants
* Variables::
* Types:: Type definitions
+* Macro define and undefine:: Representation of #define and #undef
* 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
-* Stabs In ELF:: Stabs in an ELF file.
+* Questions:: Questions and anomalies
+* Stab Sections:: In some object file formats, stabs are
+ in sections.
+* GNU Free Documentation License:: The license for this documentation
* Symbol Types Index:: Index of symbolic stab symbol type names.
@end menu
-@end ifinfo
+@end ifnottex
+@contents
@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
-@c FIXME! <<name of inventor>> at
+Peter Kessler at
the University of California at Berkeley, for the @code{pdx} Pascal
debugger; the format has spread widely since then.
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 @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.
+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
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
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++
+of dbx may not do this. Because of a conflict with C@t{++}
(@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:
+those from the C@t{++} type descriptor @samp{@@}. The attributes are:
@table @code
@item a@var{boundary}
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.
+
+@item V
+Indicate that this type is a vector instead of an array. The only
+major difference between vectors and arrays is that vectors are
+passed by value instead of by reference (vector coprocessor extension).
+
@end table
All of this can make the string field quite long. All versions of GDB,
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.
+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
* Procedures::
* Nested Procedures::
* Block Structure::
+* Alternate Entry Points:: Entering procedures except at the beginning.
@end menu
@node Main Program
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
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 use the desc field to indicate the language of the
+source file. Sun's compilers started this usage, and the first
+constants are derived from their documentation. Languages added
+by gcc/gdb start at 0x32 to avoid conflict with languages Sun may
+add in the future. A desc field with a value 0 indicates that no
+language has been specified via this mechanism.
+
+@table @asis
+@item @code{N_SO_AS} (0x1)
+Assembly language
+@item @code{N_SO_C} (0x2)
+K&R traditional C
+@item @code{N_SO_ANSI_C} (0x3)
+ANSI C
+@item @code{N_SO_CC} (0x4)
+C++
+@item @code{N_SO_FORTRAN} (0x5)
+Fortran
+@item @code{N_SO_PASCAL} (0x6)
+Pascal
+@item @code{N_SO_FORTRAN90} (0x7)
+Fortran90
+@item @code{N_SO_OBJC} (0x32)
+Objective-C
+@item @code{N_SO_OBJCPLUS} (0x33)
+Objective-C++
+@end table
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
+from the @code{cfront} C@t{++} 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.
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
@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 Sun's stabs-in-ELF and GNU's
-stabs-in-SOM, it is relative to the function in which the @code{N_SLINE}
-symbol occurs.
+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
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. See @ref{Stabs In ELF} 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
@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
@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 Sun's stabs-in-ELF and GNU's stabs-in-SOM, they are relative
-to the function in which they occur.
+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
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
@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
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.
+@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
.stabs "var_noinit:S1",40,0,0,_var_noinit # @r{40 is N_LCSYM}
@end example
-In XCOFF files, each symbol has a section number, so the stab type
-need not indicate the section.
+@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.
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
+The clean way to do all this would be to have 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{Stabs In ELF}.
+@xref{ELF Linker Relocation}.
@node Based Variables
@section Fortran Based Variables
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
@code{integer}. 32 bit signed integral type.
@item -16
-@code{boolean}. 32 bit type. How is the truth value encoded? Is it
-the least significant bit or is it a question of whether the whole value
-is zero or non-zero?
+@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 -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
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{:}.
-The name can contain @samp{::}---only a single @samp{:} ends the name;
-see @ref{Nested Symbols}.
+If the name contains @samp{::} between a @samp{<} and @samp{>} pair (for
+C@t{++} 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:
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}
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 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.
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}.
+The structure element descriptions are of the form
+@samp{@var{name}:@var{type}, @var{bit offset from the start of the
+struct}, @var{number of bits in the element}}.
@c FIXME: phony line break. Can probably be fixed by using an example
@c with fewer fields.
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.
+If a field is a static member (this is a C@t{++} 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@t{++} 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,
@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
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;}.
+descriptions. Their format is @samp{@var{name}:@var{type}, @var{bit
+offset into the union}, @var{number of bytes for the element};}.
The stab for the union variable is:
The variable defines a new type, 24, which is a pointer to another new
type, 25, which is a function returning @code{int}.
+@node Macro define and undefine
+@chapter Representation of #define and #undef
+
+This section describes the stabs support for macro define and undefine
+information, supported on some systems. (e.g., with @option{-g3}
+@option{-gstabs} when using GCC).
+
+A @code{#define @var{macro-name} @var{macro-body}} is represented with
+an @code{N_MAC_DEFINE} stab with a string field of
+@code{@var{macro-name} @var{macro-body}}.
+@findex N_MAC_DEFINE
+
+An @code{#undef @var{macro-name}} is represented with an
+@code{N_MAC_UNDEF} stabs with a string field of simply
+@code{@var{macro-name}}.
+@findex N_MAC_UNDEF
+
+For both @code{N_MAC_DEFINE} and @code{N_MAC_UNDEF}, the desc field is
+the line number within the file where the corresponding @code{#define}
+or @code{#undef} occurred.
+
+For example, the following C code:
+
+@example
+ #define NONE 42
+ #define TWO(a, b) (a + (a) + 2 * b)
+ #define ONE(c) (c + 19)
+
+ main(int argc, char *argv[])
+ @{
+ func(NONE, TWO(10, 11));
+ func(NONE, ONE(23));
+
+ #undef ONE
+ #define ONE(c) (c + 23)
+
+ func(NONE, ONE(-23));
+
+ return (0);
+ @}
+
+ int global;
+
+ func(int arg1, int arg2)
+ @{
+ global = arg1 + arg2;
+ @}
+@end example
+
+@noindent
+produces the following stabs (as well as many others):
+
+@example
+ .stabs "NONE 42",54,0,1,0
+ .stabs "TWO(a,b) (a + (a) + 2 * b)",54,0,2,0
+ .stabs "ONE(c) (c + 19)",54,0,3,0
+ .stabs "ONE",58,0,10,0
+ .stabs "ONE(c) (c + 23)",54,0,11,0
+@end example
+
+@noindent
+NOTE: In the above example, @code{54} is @code{N_MAC_DEFINE} and
+@code{58} is @code{N_MAC_UNDEF}.
+
@node Symbol Tables
@chapter Symbol Information in Symbol Tables
@menu
* Transformations On Static Variables::
* Transformations On Global Variables::
-* ELF Transformations:: In ELF, things are a bit different.
+* Stab Section Transformations:: For some object file formats,
+ things are a bit different.
@end menu
@node Transformations On Static Variables
0000e008 D _g_foo
@end example
-@node ELF and SOM Transformations
-@subsection Transformations of Stabs in ELF and SOM Files
+@node Stab Section Transformations
+@subsection Transformations of Stabs in separate sections
-For ELF and SOM files, 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.
+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{Stabs In ELF}). For example,
-if the source line
+relative to the compilation unit (@pxref{ELF Linker Relocation}). For
+example, if the source line
@example
static int ld = 5;
@end example
@node Cplusplus
-@chapter GNU C++ Stabs
+@chapter GNU C@t{++} Stabs
@menu
* Class Names:: C++ class names are both tags and typedefs.
* 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::
+* Inheritance::
* Virtual Base Classes::
* Static Members::
@end menu
-Type descriptors added for C++ descriptions:
-
-@table @code
-@item #
-method type (@code{##} if minimal debug)
-
-@item @@
-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.
-@end table
-
@node Class Names
-@section C++ Class Names
+@section C@t{++} Class Names
-In C++, a class name which is declared with @code{class}, @code{struct},
+In C@t{++}, 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}).
@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
+For example, the C@t{++} code
@example
struct foo @{int x;@};
@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.
+In C@t{++}, 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
symbol descriptor, and @samp{5=*6} is the type information.
@node Basic Cplusplus Types
-@section Basic Types For C++
+@section Basic Types For C@t{++}
<< the examples that follow are based on a01.C >>
-C++ adds two more builtin types to the set defined for C. These are
+C@t{++} 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.
<< 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
+This basic type is present in all C@t{++} programs even if there are no
virtual methods defined.
@display
@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
+The stabs describing C@t{++} language features are an extension of the
+stabs describing C. Stabs representing C@t{++} 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.
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
+A stab describing a C@t{++} 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@t{++} 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
+In this simple example the field part of the C@t{++} 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
+The field part of a C@t{++} 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,
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 descriptor
-@samp{#}, indicating a method type, and a second @samp{#}, indicating
-that this is the @dfn{minimal} type of method definition used by GCC2,
-not larger method definitions used by earlier versions of GCC. This is
-followed by a type reference showing the return type of the method and a
-semi-colon.
+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
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}
+in C@t{++} 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,
@node Class Instance
@section Class Instance
-As shown above, describing even a simple C++ class definition is
+As shown above, describing even a simple C@t{++} 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
@node Methods
@section Method Definition
-The class definition shown above declares Ameth. The C++ source below
+The class definition shown above declares Ameth. The C@t{++} source below
defines Ameth:
@example
@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}.
<< 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 used for a
+pointer-to-non-static-member-data type. It is followed
+by type information for the class (or union), a comma, and type
+information for the member data.
+
+The following C@t{++} source:
+
+@smallexample
+typedef int A::*int_in_a;
+@end smallexample
+
+generates the following stab:
+
+@smallexample
+.stabs "int_in_a:t20=21=@@19,1",128,0,0,0
+@end smallexample
+
+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@t{++} 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.
+functions were publicly accessible. The example that follows
+contrasts public, protected and privately accessible fields and shows
+how these protections are encoded in C@t{++} 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}
Visibility @samp{9} is not supported by GDB 4.11; this should be fixed
in the next GDB release.
-The following C++ source:
+The following C@t{++} source:
@example
class vis @{
(@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
+private, 1 if protected and 2 if public. Consider the C@t{++} class
definition below:
@example
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
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
+C@t{++} 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
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++
+17. Type 17 was the vtable record type defined by the boilerplate C@t{++}
type definitions, as shown earlier.
The bit offset of the vtable pointer field is 32. The number of bits
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
+Stabs describing C@t{++} derived classes include additional sections that
+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
-it does apply to stabs in ELF and stabs in SOM. Stabs in ECOFF use these
-values but add 0x8f300 to distinguish them from non-stab symbols.
+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}.
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
@item 0x34 N_NOMAP
No DST map; see @ref{N_NOMAP}.
+@item 0x36 N_MAC_DEFINE
+Name and body of a @code{#define}d macro; see @ref{Macro define and undefine}.
+
@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).
+@item 0x3a N_MAC_UNDEF
+Name of an @code{#undef}ed macro; see @ref{Macro define and undefine}.
+
@c See include/aout/stab.def for (a little) more info.
@item 0x3c N_OPT
Debugger options (Solaris2).
Function start/body/end line numbers (Solaris2).
@item 0x50 N_EHDECL
-GNU C++ exception variable; see @ref{N_EHDECL}.
+GNU C@t{++} 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}.
+GNU C@t{++} @code{catch} clause; see @ref{N_CATCH}.
@item 0x60 N_SSYM
Structure of union element; see @ref{N_SSYM}.
End of an include file; see @ref{Include Files}.
@item 0xa4 N_ENTRY
-Alternate entry point; see @ref{N_ENTRY}.
+Alternate entry point; see @ref{Alternate Entry Points}.
@item 0xc0 N_LBRAC
Beginning of a lexical block; see @ref{Block Structure}.
Variable on the stack; see @ref{Stack Variables}.
@item :
-C++ nested symbol; see @xref{Nested Symbols}
+C@t{++} nested symbol; see @xref{Nested Symbols}.
@item a
Parameter passed by reference in register; see @ref{Reference Parameters}.
@item C
Conformant array bound (Pascal, maybe other languages); @ref{Conformant
-Arrays}. Name of a caught exception (GNU C++). These can be
+Arrays}. Name of a caught exception (GNU C@t{++}). These can be
distinguished because the latter uses @code{N_CATCH} and the former uses
another symbol type.
@item S
File scope variable; see @ref{Statics}.
+@item s
+Local variable (OS9000).
+
@item t
Type name; see @ref{Typedefs}.
Reference to builtin type; see @ref{Negative Type Numbers}.
@item #
-Method (C++); see @ref{Cplusplus}.
+Method (C@t{++}); see @ref{Method Type Descriptor}.
@item *
Pointer; see @ref{Miscellaneous Types}.
@item &
-Reference (C++).
+Reference (C@t{++}).
@item @@
Type Attributes (AIX); see @ref{String Field}. Member (class and variable)
-type (GNU C++); see @ref{Cplusplus}.
+type (GNU C@t{++}); see @ref{Member Type Descriptor}.
@item a
Array; see @ref{Arrays}.
@item b
Pascal space type (AIX); see @ref{Miscellaneous Types}. Builtin integer
-type (Sun); see @ref{Builtin Type Descriptors}.
+type (Sun); see @ref{Builtin Type Descriptors}. Const and volatile
+qualified type (OS9000).
@item B
Volatile-qualified type; see @ref{Miscellaneous Types}.
@item c
-Complex builtin type; see @ref{Builtin Type Descriptors}.
+Complex builtin type (AIX); see @ref{Builtin Type Descriptors}.
+Const-qualified type (OS9000).
@item C
COBOL Picture type. See AIX documentation for details.
COBOL Group. See AIX documentation for details.
@item i
-Imported type; see @ref{Cross-References}.
+Imported type (AIX); see @ref{Cross-References}. Volatile-qualified
+type (OS9000).
@item k
Const-qualified type; see @ref{Miscellaneous Types}.
@item x
Cross-reference; see @ref{Cross-References}.
+@item Y
+Used by IBM's xlC C@t{++} compiler (for structures, I think).
+
@item z
gstring; see @ref{Strings}.
@end table
@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:
named and the rest NIL.
Subsequent lines expand upon the meaning and possible values for each
-significant stab field. @samp{#} stands in for the type descriptor.
+significant stab field.
Finally, any further information.
* N_MOD2:: Modula2 information "for imc"
* N_CATCH:: GNU C++ "catch" clause
* N_SSYM:: Structure or union element
-* N_ENTRY:: Alternate entry point
* N_SCOPE:: Modula2 scope information (Sun only)
* Gould:: non-base register symbols used on Gould systems
* N_LENG:: Length of preceding entry
@deffn @code{.stabs} N_EHDECL
@findex N_EHDECL
-GNU C++ exception variable <<?>>.
+GNU C@t{++} exception variable <<?>>.
"@var{string} is variable name"
@deffn @code{.stabn} N_CATCH
@findex N_CATCH
-GNU C++ @code{catch} clause
+GNU C@t{++} @code{catch} clause
-GNU C++ @code{catch} clause. The value is its address. The desc field
+GNU C@t{++} @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
<<?looking at structs and unions in C I didn't see these>>
@end deffn
-@node N_ENTRY
-@section N_ENTRY
-
-@deffn @code{.stabn} N_ENTRY
-@findex N_ENTRY
-Alternate entry point.
-The value is its address.
-<<?>>
-@end deffn
-
@node N_SCOPE
@section N_SCOPE
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
+@node Stab Sections
+@appendix Using Stabs in Their Own Sections
-@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.
+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.
-@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: Get C_* types for the block, figure out whether it is always
-@c used (I suspect not), explain clearly, and move to node Statics.
-Exception: initialised static @code{N_STSYM} and un-initialized static
-@code{N_LCSYM} both map to the @code{C_STSYM} storage class. But the
-distinction is preserved because in XCOFF @code{N_STSYM} and
-@code{N_LCSYM} must be emited in a named static block. Begin the block
-with @samp{.bs s[RW] data_section_name} for @code{N_STSYM} or @samp{.bs
-s bss_section_name} for @code{N_LCSYM}. End the block with @samp{.es}.
-
-@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 Stabs In ELF
-@appendix Using Stabs With The ELF Object File Format
+@menu
+* Stab Section Basics:: How to embed stabs in sections
+* ELF Linker Relocation:: Sun ELF hacks
+@end menu
-The ELF object file format allows tools to create object files with
-custom sections containing any arbitrary data. To use stabs in ELF
-object files, the tools create 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 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.
+@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
@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
@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.
+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. While @value{GDBN} no longer supports this hack
+for Sun Stabs in ELF, this section is kept to document the issue.
To keep linking fast, you don't want the linker to have to relocate very
-many stabs. Thus Sun has invented a scheme in which addresses in the
-@code{n_value} field are relative to the source file (or some entity
-smaller than a source file, like a function). 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{ELF 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.
+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
+@code{.stab} section comes from which @file{.o} file. The way GDB use to
+do 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
solves the problem of having to associate the ELF and stab symbols.
However, no one has yet designed or implemented such a scheme.
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include fdl.texi
+
@node Symbol Types Index
@unnumbered Symbol Types Index
@printindex fn
-@contents
@bye
projects / deliverable / binutils-gdb.git / blobdiff