stabs.texinfo

这个是LINUX下的GDB调度工具的源码

\input texinfo
@setfilename stabs.info

@c @finalout

@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

@ifinfo
This document describes the stabs debugging symbol tables.

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 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 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 ifinfo

@setchapternewpage odd
@settitle STABS
@titlepage
@title The ``stabs'' debug format
@author Julia Menapace, Jim Kingdon, David MacKenzie
@author Cygnus Support
@page
@tex
\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
\xdef\manvers{\$Revision: 2.130 $}  % For use in headers, footers too
{\parskip=0pt
\hfill Cygnus Support\par
\hfill \manvers\par
\hfill \TeX{}info \texinfoversion\par
}
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 1992,1993,1994,1995,1997,1998,2000,2001 Free Software Foundation, Inc.
Contributed by Cygnus Support.

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 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 titlepage

@ifinfo
@node Top
@top The "stabs" representation of debugging information

This document describes the stabs debugging format.

@menu
* Overview::			Overview of stabs
* Program Structure::		Encoding of the structure of the program
* Constants::			Constants
* Variables::
* Types::			Type definitions
* Symbol Tables::		Symbol information in symbol tables
* Cplusplus::			Stabs specific to C++
* Stab Types::			Symbol types in a.out files
* Symbol Descriptors::		Table of symbol descriptors
* Type Descriptors::		Table of type descriptors
* Expanded Reference::		Reference information by stab type
* Questions::			Questions and anomalies
* Stab Sections::		In some object file formats, stabs are
                                in sections.
* Symbol Types Index::          Index of symbolic stab symbol type names.
* GNU Free Documentation License::  The license for this documentation
@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

@dfn{Stabs} refers to a format for information that describes a program
to a debugger.  This format was apparently invented by
Peter Kessler at
the University of California at Berkeley, for the @code{pdx} Pascal
debugger; the format has spread widely since then.

This document is one of the few published sources of documentation on
stabs.  It is believed to be comprehensive for stabs used by C.  The
lists of symbol descriptors (@pxref{Symbol Descriptors}) and type
descriptors (@pxref{Type Descriptors}) are believed to be completely
comprehensive.  Stabs for COBOL-specific features and for variant
records (used by Pascal and Modula-2) are poorly documented here.

@c FIXME: Need to document all OS9000 stuff in GDB; see all references
@c to os9k_stabs in stabsread.c.

Other sources of information on stabs are @cite{Dbx and Dbxtool
Interfaces}, 2nd edition, by Sun, 1988, and @cite{AIX Version 3.2 Files
Reference}, Fourth Edition, September 1992, "dbx Stabstring Grammar" in
the a.out section, page 2-31.  This document is believed to incorporate
the information from those two sources except where it explicitly directs
you to them for more information.

@menu
* Flow::			Overview of debugging information flow
* Stabs Format::		Overview of stab format
* String Field::		The string field
* C Example::			A simple example in C source
* Assembly Code::		The simple example at the assembly level
@end menu

@node Flow
@section Overview of Debugging Information Flow

The GNU C compiler compiles C source in a @file{.c} file into assembly
language in a @file{.s} file, which the assembler translates into
a @file{.o} file, which the linker combines with other @file{.o} files and
libraries to produce an executable file.

With the @samp{-g} option, GCC puts in the @file{.s} file additional
debugging information, which is slightly transformed by the assembler
and linker, and carried through into the final executable.  This
debugging information describes features of the source file like line
numbers, the types and scopes of variables, and function names,
parameters, and scopes.

For some object file formats, the debugging information is encapsulated
in assembler directives known collectively as @dfn{stab} (symbol table)
directives, which are interspersed with the generated code.  Stabs are
the native format for debugging information in the a.out and XCOFF
object file formats.  The GNU tools can also emit stabs in the COFF and
ECOFF object file formats.

The assembler adds the information from stabs to the symbol information
it places by default in the symbol table and the string table of the
@file{.o} file it is building.  The linker consolidates the @file{.o}
files into one executable file, with one symbol table and one string
table.  Debuggers use the symbol and string tables in the executable as
a source of debugging information about the program.

@node Stabs Format
@section Overview of Stab Format

There are three overall formats for stab assembler directives,
differentiated by the first word of the stab.  The name of the directive
describes which combination of four possible data fields follows.  It is
either @code{.stabs} (string), @code{.stabn} (number), or @code{.stabd}
(dot).  IBM's XCOFF assembler uses @code{.stabx} (and some other
directives such as @code{.file} and @code{.bi}) instead of
@code{.stabs}, @code{.stabn} or @code{.stabd}.

The overall format of each class of stab is:

@example
.stabs "@var{string}",@var{type},@var{other},@var{desc},@var{value}
.stabn @var{type},@var{other},@var{desc},@var{value}
.stabd @var{type},@var{other},@var{desc}
.stabx "@var{string}",@var{value},@var{type},@var{sdb-type}
@end example

@c what is the correct term for "current file location"?  My AIX
@c assembler manual calls it "the value of the current location counter".
For @code{.stabn} and @code{.stabd}, there is no @var{string} (the
@code{n_strx} field is zero; see @ref{Symbol Tables}).  For
@code{.stabd}, the @var{value} field is implicit and has the value of
the current file location.  For @code{.stabx}, the @var{sdb-type} field
is unused for stabs and can always be set to zero.  The @var{other}
field is almost always unused and can be set to zero.

The number in the @var{type} field gives some basic information about
which type of stab this is (or whether it @emph{is} a stab, as opposed
to an ordinary symbol).  Each valid type number defines a different stab
type; further, the stab type defines the exact interpretation of, and
possible values for, any remaining @var{string}, @var{desc}, or
@var{value} fields present in the stab.  @xref{Stab Types}, for a list
in numeric order of the valid @var{type} field values for stab directives.

@node String Field
@section The String Field

For most stabs the string field holds the meat of the
debugging information.  The flexible nature of this field
is what makes stabs extensible.  For some stab types the string field
contains only a name.  For other stab types the contents can be a great
deal more complex.

The overall format of the string field for most stab types is:

@example
"@var{name}:@var{symbol-descriptor} @var{type-information}"
@end example

@var{name} is the name of the symbol represented by the stab; it can
contain a pair of colons (@pxref{Nested Symbols}).  @var{name} can be
omitted, which means the stab represents an unnamed object.  For
example, @samp{:t10=*2} defines type 10 as a pointer to type 2, but does
not give the type a name.  Omitting the @var{name} field is supported by
AIX dbx and GDB after about version 4.8, but not other debuggers.  GCC
sometimes uses a single space as the name instead of omitting the name
altogether; apparently that is supported by most debuggers.

The @var{symbol-descriptor} following the @samp{:} is an alphabetic
character that tells more specifically what kind of symbol the stab
represents. If the @var{symbol-descriptor} is omitted, but type
information follows, then the stab represents a local variable.  For a
list of symbol descriptors, see @ref{Symbol Descriptors}.  The @samp{c}
symbol descriptor is an exception in that it is not followed by type
information.  @xref{Constants}.

@var{type-information} is either a @var{type-number}, or
@samp{@var{type-number}=}.  A @var{type-number} alone is a type
reference, referring directly to a type that has already been defined.

The @samp{@var{type-number}=} form is a type definition, where the
number represents a new type which is about to be defined.  The type
definition may refer to other types by number, and those type numbers
may be followed by @samp{=} and nested definitions.  Also, the Lucid
compiler will repeat @samp{@var{type-number}=} more than once if it
wants to define several type numbers at once.

In a type definition, if the character that follows the equals sign is
non-numeric then it is a @var{type-descriptor}, and tells what kind of
type is about to be defined.  Any other values following the
@var{type-descriptor} vary, depending on the @var{type-descriptor}.
@xref{Type Descriptors}, for a list of @var{type-descriptor} values.  If
a number follows the @samp{=} then the number is a @var{type-reference}.
For a full description of types, @ref{Types}.

A @var{type-number} is often a single number.  The GNU and Sun tools
additionally permit a @var{type-number} to be a pair
(@var{file-number},@var{filetype-number}) (the parentheses appear in the
string, and serve to distinguish the two cases).  The @var{file-number}
is 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@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@t{++} type descriptor @samp{@@}.  The attributes are:

@table @code
@item a@var{boundary}
@var{boundary} is an integer specifying the alignment.  I assume it
applies to all variables of this type.

@item p@var{integer}
Pointer class (for checking).  Not sure what this means, or how
@var{integer} is interpreted.

@item P
Indicate this is a packed type, meaning that structure fields or array
elements are placed more closely in memory, to save memory at the
expense of speed.

@item s@var{size}
Size in bits of a variable of this type.  This is fully supported by GDB
4.11 and later.

@item S
Indicate that this type is a string instead of an array of characters,
or a bitstring instead of a set.  It doesn't change the layout of the
data being represented, but does enable the debugger to know which type
it is.

@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,
and some versions of dbx, can handle arbitrarily long strings.  But many
versions of dbx (or assemblers or linkers, I'm not sure which)
cretinously limit the strings to about 80 characters, so compilers which
must work with such systems need to split the @code{.stabs} directive
into several @code{.stabs} directives.  Each stab duplicates every field
except the string field.  The string field of every stab except the last
is marked as continued with a backslash at the end (in the assembly code
this may be written as a double backslash, depending on the assembler).
Removing the backslashes and concatenating the string fields of each
stab produces the original, long string.  Just to be incompatible (or so
they don't have to worry about what the assembler does with
backslashes), AIX can use @samp{?} instead of backslash.

@node C Example
@section A Simple Example in C Source

To get the flavor of how stabs describe source information for a C
program, let's look at the simple program:

@example
main()
@{
        printf("Hello world");
@}
@end example