stabs.texinfo

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

in another source file are specified (i.e., a function prototype in ANSI
C), traditionally compilers emit no stab; the only way for the debugger
to find the information is if the source file where the function is
defined was also compiled with debugging symbols.  As an extension the
Solaris compiler uses symbol descriptor @samp{P} followed by the return
type of the function, followed by the arguments, each preceded by
@samp{;}, as in a stab with symbol descriptor @samp{f} or @samp{F}.
This use of symbol descriptor @samp{P} can be distinguished from its use
for register parameters (@pxref{Register Parameters}) by the fact that it has
symbol type @code{N_FUN}.

The AIX documentation also defines symbol descriptor @samp{J} as an
internal function.  I assume this means a function nested within another
function.  It also says symbol descriptor @samp{m} is a module in
Modula-2 or extended Pascal.

Procedures (functions which do not return values) are represented as
functions returning the @code{void} type in C.  I don't see why this couldn't
be used for all languages (inventing a @code{void} type for this purpose if
necessary), but the AIX documentation defines @samp{I}, @samp{P}, and
@samp{Q} for internal, global, and static procedures, respectively.
These symbol descriptors are unusual in that they are not followed by
type information.

The following example shows a stab for a function @code{main} which
returns type number @code{1}.  The @code{_main} specified for the value
is a reference to an assembler label which is used to fill in the start
address of the function.

@example
.stabs "main:F1",36,0,0,_main      # @r{36 is N_FUN}
@end example

The stab representing a procedure is located immediately following the
code of the procedure.  This stab is in turn directly followed by a
group of other stabs describing elements of the procedure.  These other
stabs describe the procedure's parameters, its block local variables, and
its block structure.

If functions can appear in different sections, then the debugger may not
be able to find the end of a function.  Recent versions of GCC will mark
the end of a function with an @code{N_FUN} symbol with an empty string
for the name.  The value is the address of the end of the current
function.  Without such a symbol, there is no indication of the address
of the end of a function, and you must assume that it ended at the
starting address of the next function or at the end of the text section
for the program.

@node Nested Procedures
@section Nested Procedures

For any of the symbol descriptors representing procedures, after the
symbol descriptor and the type information is optionally a scope
specifier.  This consists of a comma, the name of the procedure, another
comma, and the name of the enclosing procedure.  The first name is local
to the scope specified, and seems to be redundant with the name of the
symbol (before the @samp{:}).  This feature is used by GCC, and
presumably Pascal, Modula-2, etc., compilers, for nested functions.

If procedures are nested more than one level deep, only the immediately
containing scope is specified.  For example, this code:

@example
int
foo (int x)
@{
  int bar (int y)
    @{
      int baz (int z)
        @{
          return x + y + z;
        @}
      return baz (x + 2 * y);
    @}
  return x + bar (3 * x);
@}
@end example

@noindent
produces the stabs:

@example
.stabs "baz:f1,baz,bar",36,0,0,_baz.15         # @r{36 is N_FUN}
.stabs "bar:f1,bar,foo",36,0,0,_bar.12
.stabs "foo:F1",36,0,0,_foo
@end example

@node Block Structure
@section Block Structure

@findex N_LBRAC
@findex N_RBRAC
@c For GCC 2.5.8 or so stabs-in-coff, these are absolute instead of
@c function relative (as documented below).  But GDB has never been able
@c to deal with that (it had wanted them to be relative to the file, but
@c I just fixed that (between GDB 4.12 and 4.13)), so it is function
@c relative just like ELF and SOM and the below documentation.
The program's block structure is represented by the @code{N_LBRAC} (left
brace) and the @code{N_RBRAC} (right brace) stab types.  The variables
defined inside a block precede the @code{N_LBRAC} symbol for most
compilers, including GCC.  Other compilers, such as the Convex, Acorn
RISC machine, and Sun @code{acc} compilers, put the variables after the
@code{N_LBRAC} symbol.  The values of the @code{N_LBRAC} and
@code{N_RBRAC} symbols are the start and end addresses of the code of
the block, respectively.  For most machines, they are relative to the
starting address of this source file.  For the Gould NP1, they are
absolute.  For stabs in sections (@pxref{Stab Sections}), they are
relative to the function in which they occur.

The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block
scope of a procedure are located after the @code{N_FUN} stab that
represents the procedure itself.

Sun documents the desc field of @code{N_LBRAC} and
@code{N_RBRAC} symbols as containing the nesting level of the block.
However, dbx seems to not care, and GCC always sets desc to
zero.

@findex .bb
@findex .be
@findex C_BLOCK
For XCOFF, block scope is indicated with @code{C_BLOCK} symbols.  If the
name of the symbol is @samp{.bb}, then it is the beginning of the block;
if the name of the symbol is @samp{.be}; it is the end of the block.

@node Alternate Entry Points
@section Alternate Entry Points

@findex N_ENTRY
@findex C_ENTRY
Some languages, like Fortran, have the ability to enter procedures at
some place other than the beginning.  One can declare an alternate entry
point.  The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN
compiler doesn't use it.  According to AIX documentation, only the name
of a @code{C_ENTRY} stab is significant; the address of the alternate
entry point comes from the corresponding external symbol.  A previous
revision of this document said that the value of an @code{N_ENTRY} stab
was the address of the alternate entry point, but I don't know the
source for that information.

@node Constants
@chapter Constants

The @samp{c} symbol descriptor indicates that this stab represents a
constant.  This symbol descriptor is an exception to the general rule
that symbol descriptors are followed by type information.  Instead, it
is followed by @samp{=} and one of the following:

@table @code
@item b @var{value}
Boolean constant.  @var{value} is a numeric value; I assume it is 0 for
false or 1 for true.

@item c @var{value}
Character constant.  @var{value} is the numeric value of the constant.

@item e @var{type-information} , @var{value}
Constant whose value can be represented as integral.
@var{type-information} is the type of the constant, as it would appear
after a symbol descriptor (@pxref{String Field}).  @var{value} is the
numeric value of the constant.  GDB 4.9 does not actually get the right
value if @var{value} does not fit in a host @code{int}, but it does not
do anything violent, and future debuggers could be extended to accept
integers of any size (whether unsigned or not).  This constant type is
usually documented as being only for enumeration constants, but GDB has
never imposed that restriction; I don't know about other debuggers.

@item i @var{value}
Integer constant.  @var{value} is the numeric value.  The type is some
sort of generic integer type (for GDB, a host @code{int}); to specify
the type explicitly, use @samp{e} instead.

@item r @var{value}
Real constant.  @var{value} is the real value, which can be @samp{INF}
(optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet
NaN (not-a-number), or @samp{SNAN} for a signalling NaN.  If it is a
normal number the format is that accepted by the C library function
@code{atof}.

@item s @var{string}
String constant.  @var{string} is a string enclosed in either @samp{'}
(in which case @samp{'} characters within the string are represented as
@samp{\'} or @samp{"} (in which case @samp{"} characters within the
string are represented as @samp{\"}).

@item S @var{type-information} , @var{elements} , @var{bits} , @var{pattern}
Set constant.  @var{type-information} is the type of the constant, as it
would appear after a symbol descriptor (@pxref{String Field}).
@var{elements} is the number of elements in the set (does this means
how many bits of @var{pattern} are actually used, which would be
redundant with the type, or perhaps the number of bits set in
@var{pattern}?  I don't get it), @var{bits} is the number of bits in the
constant (meaning it specifies the length of @var{pattern}, I think),
and @var{pattern} is a hexadecimal representation of the set.  AIX
documentation refers to a limit of 32 bytes, but I see no reason why
this limit should exist.  This form could probably be used for arbitrary
constants, not just sets; the only catch is that @var{pattern} should be
understood to be target, not host, byte order and format.
@end table

The boolean, character, string, and set constants are not supported by
GDB 4.9, but it ignores them.  GDB 4.8 and earlier gave an error
message and refused to read symbols from the file containing the
constants.

The above information is followed by @samp{;}.

@node Variables
@chapter Variables

Different types of stabs describe the various ways that variables can be
allocated: on the stack, globally, in registers, in common blocks,
statically, or as arguments to a function.

@menu
* Stack Variables::		Variables allocated on the stack.
* Global Variables::		Variables used by more than one source file.
* Register Variables::		Variables in registers.
* Common Blocks::		Variables statically allocated together.
* Statics::			Variables local to one source file.
* Based Variables::		Fortran pointer based variables.
* Parameters::			Variables for arguments to functions.
@end menu

@node Stack Variables
@section Automatic Variables Allocated on the Stack

If a variable's scope is local to a function and its lifetime is only as
long as that function executes (C calls such variables
@dfn{automatic}), it can be allocated in a register (@pxref{Register
Variables}) or on the stack.

@findex N_LSYM, for stack variables
@findex C_LSYM
Each variable allocated on the stack has a stab with the symbol
descriptor omitted.  Since type information should begin with a digit,
@samp{-}, or @samp{(}, only those characters precluded from being used
for symbol descriptors.  However, the Acorn RISC machine (ARM) is said
to get this wrong: it puts out a mere type definition here, without the
preceding @samp{@var{type-number}=}.  This is a bad idea; there is no
guarantee that type descriptors are distinct from symbol descriptors.
Stabs for stack variables use the @code{N_LSYM} stab type, or
@code{C_LSYM} for XCOFF.

The value of the stab is the offset of the variable within the
local variables.  On most machines this is an offset from the frame
pointer and is negative.  The location of the stab specifies which block
it is defined in; see @ref{Block Structure}.

For example, the following C code:

@example
int
main ()
@{
  int x;
@}
@end example

produces the following stabs:

@example
.stabs "main:F1",36,0,0,_main   # @r{36 is N_FUN}
.stabs "x:1",128,0,0,-12        # @r{128 is N_LSYM}
.stabn 192,0,0,LBB2             # @r{192 is N_LBRAC}
.stabn 224,0,0,LBE2             # @r{224 is N_RBRAC}
@end example

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.

@node Global Variables
@section Global Variables

@findex N_GSYM
@findex C_GSYM
@c FIXME: verify for sure that it really is C_GSYM on XCOFF
A variable whose scope is not specific to just one source file is
represented by the @samp{G} symbol descriptor.  These stabs use the
@code{N_GSYM} stab type (C_GSYM for XCOFF).  The type information for
the stab (@pxref{String Field}) gives the type of the variable.

For example, the following source code:

@example
char g_foo = 'c';
@end example

@noindent
yields the following assembly code:

@example
.stabs "g_foo:G2",32,0,0,0     # @r{32 is N_GSYM}
     .global _g_foo
     .data
_g_foo:
     .byte 99
@end example

The address of the variable represented by the @code{N_GSYM} is not
contained in the @code{N_GSYM} stab.  The debugger gets this information
from the external symbol for the global variable.  In the example above,
the @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to
produce an external symbol.

Some compilers, like GCC, output @code{N_GSYM} stabs only once, where
the variable is defined.  Other compilers, like SunOS4 /bin/cc, output a
@code{N_GSYM} stab for each compilation unit which references the
variable.

@node Register Variables
@section Register Variables

@findex N_RSYM
@findex C_RSYM
@c According to an old version of this manual, AIX uses C_RPSYM instead