@node Top
@top The "stabs" representation of debugging information
-This document describes the GNU stabs debugging format in a.out files.
+This document describes the stabs debugging format.
@menu
-* Overview:: Overview of stabs
-* Program structure:: Encoding of the structure of the program
+* Overview:: Overview of stabs
+* Program structure:: Encoding of the structure of the program
* Constants:: Constants
-* Example:: A comprehensive example in C
-* Variables::
+* Example:: A comprehensive example in C
+* Variables::
* Types:: Type definitions
-* Symbol Tables:: Symbol information in symbol tables
-* Cplusplus::
-
-Appendixes:
-* Example2.c:: Source code for extended example
-* Example2.s:: Assembly code for extended example
-* Stab types:: Table A: Symbol types from stabs
-* Assembler types:: Table B: Symbol types from assembler and linker
-* Symbol Descriptors:: Table C
-* Type Descriptors:: Table D
-* Expanded reference:: Reference information by stab type
-* Questions:: Questions and anomolies
-* xcoff-differences:: Differences between GNU stabs in a.out
+* Symbol Tables:: Symbol information in symbol tables
+* Cplusplus:: Appendixes:
+* Example2.c:: Source code for extended example
+* Example2.s:: Assembly code for extended example
+* Stab Types:: Symbol types in a.out files
+* Symbol Descriptors:: Table of Symbol Descriptors
+* Type Descriptors:: Table of Symbol 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
+* Sun-differences:: Differences between GNU stabs and Sun
native stabs
+* Stabs-in-elf:: Stabs in an ELF file.
@end menu
@end ifinfo
explictly directs you to them for more information.
@menu
-* Flow:: Overview of debugging information flow
-* Stabs Format:: Overview of stab format
-* C example:: A simple example in C source
-* Assembly code:: The simple example at the assembly level
+* Flow:: Overview of debugging information flow
+* Stabs Format:: Overview of stab format
+* C example:: A simple example in C source
+* Assembly code:: The simple example at the assembly level
@end menu
@node Flow
ordinary symbol). Each possible type number defines a different stab
type. The stab type further defines the exact interpretation of, and
possible values for, any remaining @code{"@var{string}"}, @var{desc}, or
-@var{value} fields present in the stab. Table A (@pxref{Stab
-types,,Table A: Symbol types from stabs}) lists in numeric order the
-possible type field values for stab directives. The reference section
-that follows Table A describes the meaning of the fields for each stab
-type in detail. The examples that follow this overview introduce the
-stab types in terms of the source code elements they describe.
+@var{value} fields present in the stab. @xref{Stab Types}, for a list
+in numeric order of the possible type field values for stab directives.
For @code{.stabs} the @code{"@var{string}"} field holds the meat of the
debugging information. The generally unstructured nature of this field
@chapter Encoding for the structure of the program
@menu
-* Source Files:: The path and name of the source file
-* Line Numbers::
-* Procedures::
-* Block Structure::
+* Main Program:: Indicate what the main program is
+* Source Files:: The path and name of the source file
+* Line Numbers::
+* Procedures::
+* Block Structure::
@end menu
+@node Main Program
+@section Main Program
+
+Most languages allow the main program to have any name. The
+@code{N_MAIN} stab type is used for a stab telling the debugger what
+name is used in this program. Only the name is significant; it will be
+the name of a function which is the main program. Most C compilers do
+not use this stab; they expect the debugger to simply assume that the
+name is @samp{main}, but some C compilers emit an @code{N_MAIN} stab for
+the @samp{main} function.
+
@node Source Files
@section The path and name of the source files
symbol is the start address of portion of the text section corresponding
to that file.
+With the Sun Solaris2 compiler, the @code{desc} field contains a
+source-language code.
+
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.
-According to a comment in GDB's @file{partial-stab.h}, other compilers
-(especially unnamed C++ compilers) put out useless N_SO's for
-nonexistent source files (after the N_SO for the real source file).
+symbol can be distinguished by the fact that it ends in a slash. Code
+from the cfront C++ 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.
For example:
A @code{N_BINCL} symbol specifies the start of an include file. In an
object file, only the name is significant. The Sun linker puts data
into some of the other fields. The end of the include file is marked by
-a @code{N_EINCL} symbol of the same name. In an ojbect 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 @code{N_EINCL} can be
-nested. If the linker detects that two source files have identical
-stabs with a @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.
+a @code{N_EINCL} symbol (which has no name field). In an ojbect 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
+@code{N_EINCL} can be nested. If the linker detects that two source
+files have identical stabs with a @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.
For the start of an include file in XCOFF, use the @file{.bi} assembler
directive which generates a @code{C_BINCL} symbol. A @file{.ei}
A @code{N_SLINE} symbol represents the start of a source line. The
@var{desc} field contains the line number and the @var{value} field
-contains the code address for the start of that source line.
+contains the code address for the start of that source line. On most
+machines the address is absolute; for Sun's stabs-in-elf, it is relative
+to the function in which the @code{N_SLINE} symbol occurs.
GNU documents @code{N_DSLINE} and @code{N_BSLINE} symbols for line
numbers in the data or bss segments, respectively. They are identical
of the function; thus @samp{foo:f5} means that foo is a function
returning type 5.
+The type information of the stab is optionally followed by type
+information for each argument, with each argument preceded by @samp{;}.
+An argument type of 0 means that additional arguments are being passed,
+whose types and number may vary (@samp{...} in ANSI C). This extension
+is used by Sun's Solaris compiler. GDB has tolerated it (i.e. at least
+parsed the syntax, if not necessarily used the information) at least
+since version 4.8; I don't know whether all versions of dbx will
+tolerate it. The argument types given here are not merely redundant
+with the symbols for the arguments themselves (@pxref{Parameters}), they
+are the types of the arguments as they are passed, before any
+conversions might take place. For example, if a C function which is
+declared without a prototype takes a @code{float} argument, the value is
+passed as a @code{double} but then converted to a @code{float}.
+Debuggers need to use the types given in the arguments when printing
+values, but if calling the function they need to use the types given in
+the symbol defining the function.
+
+If the return type and types of arguments of a function which is defined
+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{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
@node Block Structure
@section Block Structure
-@table @strong
-@item Directive:
-@code{.stabn}
-@item Types:
-@code{N_LBRAC}, @code{N_RBRAC}
-@end table
-
The program's block structure is represented by the @code{N_LBRAC} (left
-brace) and the @code{N_RBRAC} (right brace) stab types. The following code
-range, which is the body of @code{main}, is labeled with @samp{LBB2:} at the
-beginning and @samp{LBE2:} at the end.
-
-@example
-37 LBB2:
-38 sethi %hi(LC0),%o1
-39 or %o1,%lo(LC0),%o0
-40 call _printf,0
-41 nop
-42 .stabn 68,0,6,LM3
-43 LM3:
-44 LBE2:
-@end example
+brace) and the @code{N_RBRAC} (right brace) stab types. The variables
+defined inside a block preceded the @code{N_LBRAC} symbol for most
+compilers, including GCC. Other compilers, such as the Convex, Acorn
+RISC machine, and Sun 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 Sun's stabs-in-elf, 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 the procedure are located after the @code{N_FUNC} stab that
-represents the procedure itself. The @code{N_LBRAC} uses the
-@code{LBB2} label as the code address in its value field, and the
-@code{N_RBRAC} uses @code{LBE2}.
-
-@example
-50 .stabs "main:F1",36,0,0,_main
-@end example
-
-@example
- .stabn N_LBRAC, NIL, NIL, @var{left-brace-address}
- .stabn N_RBRAC, NIL, NIL, @var{right-brace-address}
-@end example
+scope of a procedure are located after the @code{N_FUN} stab that
+represents the procedure itself.
-@example
-51 .stabn 192,0,0,LBB2
-52 .stabn 224,0,0,LBE2
-@end example
+Sun documents the @code{desc} field of @code{N_LBRAC} and
+@code{N_RBRAC} symbols as containing the nesting level of the block.
+However, dbx seems not to care, and GCC just always set @code{desc} to
+zero.
@node Constants
@chapter Constants
@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{Stabs Format}).
-@var{elements} is the number of elements in the set (is this just the
-number of bits set in @var{pattern}? Or redundant with the type? 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.
+@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
@chapter Variables
@menu
-* Automatic variables:: locally scoped
-* Global Variables::
-* Register variables::
-* Initialized statics::
-* Un-initialized statics::
-* Parameters::
+* Automatic 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.
+* Parameters:: Variables for arguments to functions.
@end menu
@node Automatic variables
The value is the register number.
AIX defines a separate symbol descriptor @samp{d} for floating point
-registers. This seems incredibly stupid---why not just just give
-floating point registers different register numbers? I have not
-verified whether the compiler actually uses @samp{d}.
+registers. This seems unnecessary---why not just just give floating
+point registers different register numbers? I have not verified whether
+the compiler actually uses @samp{d}.
If the register is explicitly allocated to a global variable, but not
initialized, as in
the stab may be emitted at the end of the object file, with
the other bss symbols.
-@node Initialized statics
-@section Initialized static variables
-
-@table @strong
-@item Directive:
-@code{.stabs}
-@item Type:
-@code{N_STSYM}
-@item Symbol Descriptors:
-@code{S} (file scope), @code{V} (procedure scope)
-@end table
-
-Initialized static variables are represented by the @code{N_STSYM} stab
-type. The symbol descriptor part of the string field shows if the
-variable is file scope static (@samp{S}) or procedure scope static
-(@samp{V}). The source line
-
-@example
-3 static int s_g_repeat = 2;
+@node Common Blocks
+@section Common Blocks
+
+A common block is a statically allocated section of memory which can be
+referred to by several source files. It may contain several variables.
+I believe @sc{fortran} is the only language with this feature. A
+@code{N_BCOMM} stab begins a common block and an @code{N_ECOMM} stab
+ends it. The only thing which is significant about these two stabs is
+their name, which can be used to look up a normal (non-debugging) symbol
+which gives the address of the common block. Then each stab between the
+@code{N_BCOMM} and the @code{N_ECOMM} specifies a member of that common
+block; its value is the offset within the common block of that variable.
+The @code{N_ECOML} stab type is documented for this purpose, but Sun's
+@sc{fortran} compiler uses @code{N_GSYM} instead. The test case I
+looked at had a common block local to a function and it used the
+@samp{V} symbol descriptor; I assume one would use @samp{S} if not local
+to a function (that is, if a common block @emph{can} be anything other
+than local to a function).
+
+@node Statics
+@section Static Variables
+
+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.
+
+In a.out files, @code{N_STSYM} means the data segment (although gcc
+2.4.5 has a bug in that it uses @code{N_FUN}, so neither dbx nor gdb can
+find the variables), @code{N_FUN} means the text segment, and
+@code{N_LCSYM} means the bss segment.
+
+In xcoff files, each symbol has a section number, so the symbol type
+need not indicate the segment.
+
+@c In ELF files, it apparently is a big mess. See kludge in dbxread.c
+@c in GDB. FIXME: Investigate where this kludge comes from.
+@c
+@c This is the place to mention N_ROSYM; I'd rather do so once I can
+@c coherently explain how this stuff works for stabs-in-elf.
+@c
+For example, the source lines
+
+@example
+static const int var_const = 5;
+static int var_init = 2;
+static int var_noinit;
@end example
@noindent
-yields the following code. The stab is located immediately preceding
-the storage for the variable it represents. Since the variable in
-this example is file scope static the symbol descriptor is @samp{S}.
+yield the following stabs:
@example
-@exdent @code{N_STSYM} (38): initialized static variable (data seg w/internal linkage)
-
-.stabs "@var{name}:
- @var{descriptor}
- @var{type-ref}",
- N_STSYM,NIL,NIL,
- @var{address}
-
-26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
-27 .align 4
-28 _s_g_repeat:
-29 .word 2
+.stabs "var_const:S1",36,0,0,_var_const ; @r{36 = N_FUN}
+. . .
+.stabs "var_init:S1",38,0,0,_var_init ; @r{38 = N_STSYM}
+. . .
+.stabs "var_noinit:S1",40,0,0,_var_noinit ; @r{40 = N_LCSYM}
@end example
-
-@node Un-initialized statics
-@section Un-initialized static variables
-
-@table @strong
-@item Directive:
-@code{.stabs}
-@item Type:
-@code{N_LCSYM}
-@item Symbol Descriptors:
-@code{S} (file scope), @code{V} (procedure scope)
-@end table
-
-Un-initialized static variables are represented by the @code{N_LCSYM}
-stab type. The symbol descriptor part of the string shows if the
-variable is file scope static (@samp{S}) or procedure scope static
-(@samp{V}). In this example it is procedure scope static. The source
-line allocating @code{s_flap} immediately follows the open brace for the
-procedure @code{main}.
-
-@example
-20 @{
-21 static float s_flap;
-@end example
-
-The code that reserves storage for the variable @code{s_flap} precedes the
-body of body of @code{main}.
-
-@example
-39 .reserve _s_flap.0,4,"bss",4
-@end example
-
-But since @code{s_flap} is scoped locally to @code{main}, its stab is
-located with the other stabs representing symbols local to @code{main}.
-The stab for @code{s_flap} is located just before the @code{N_LBRAC} for
-@code{main}.
-
-@example
-@exdent @code{N_LCSYM} (40): uninitialized static var (BSS seg w/internal linkage)
-
-.stabs "@var{name}:
- @var{descriptor}
- @var{type-ref}",
- N_LCSYM, NIL, NIL,
- @var{address}
-
-97 .stabs "s_flap:V12",40,0,0,_s_flap.0
-98 .stabs "times:1",128,0,0,-20
-99 .stabn 192,0,0,LBB2 # N_LBRAC for main.
-@end example
-
-@c ............................................................
-
@node Parameters
-@section Parameters
+@section Parameters
+
+Parameters to a function are represented by a stab (or sometimes two,
+see below) for each parameter. The stabs are in the order in which the
+debugger should print the parameters (i.e. the order in which the
+parameters are declared in the source file).
The symbol descriptor @samp{p} is used to refer to parameters which are
in the arglist. Symbols have symbol type @samp{N_PSYM}. The value of
handle either one. Symbol type @samp{C_RPSYM} is used with @samp{R} and
@samp{N_RSYM} is used with @samp{P}.
-AIX, according to the documentation, uses @samp{D} for a parameter
-passed in a floating point register. This strikes me as incredibly
-bogus---why doesn't it just use @samp{R} with a register number which
+According to the AIX documentation symbol descriptor @samp{D} is for a
+parameter passed in a floating point register. This seems
+unnecessary---why not just use @samp{R} with a register number which
indicates that it's a floating point register? I haven't verified
whether the system actually does what the documentation indicates.
pointer to type 21.
@node Types
-@chapter Type definitions
+@chapter Type Definitions
Now let's look at some variable definitions involving complex types.
This involves understanding better how types are described. In the
* Strings:: Like an array but also has a length.
* Enumerations:: Like an integer but the values have names.
* Structures:: An aggregate type of different-typed elements.
-* Typedefs:: Giving a type a name
-* Unions::
-* Function types::
+* Typedefs:: Giving a type a name.
+* Unions:: Different types sharing storage.
+* Function Types::
@end menu
@node Builtin types
@item 3 (NF_COMPLEX)
@item 4 (NF_COMPLEX16)
@item 5 (NF_COMPLEX32)
-These are for complex numbers. A comment in
-@file{include/aout/stab_gnu.h} describes them as Fortran complex, double
-complex, and complex*16, respectively, but what does that mean? (i.e.
-Single precision? Double precison?).
+@c "GDB source" really means @file{include/aout/stab_gnu.h}, but trying
+@c to put that here got an overfull hbox.
+These are for complex numbers. A comment in the GDB source describes
+them as Fortran complex, double complex, and complex*16, respectively,
+but what does that mean? (i.e. Single precision? Double precison?).
@item 6 (NF_LDOUBLE)
-Long double. It would be cleaner to define a different code for every
-possible format of long double.
+Long double. This should probably only be used for Sun format long
+double, and new codes should be used for other floating point formats
+(NF_DOUBLE can be used if a long double is really just an IEEE double,
+of course).
@end table
@var{bytes} is the number of bytes occupied by the type. This allows a
@example
.stabs "void:t19=bs0;0;0",128,0,0,0
@end example
+The Solaris compiler seems to omit the trailing semicolon in this case.
+Getting sloppy in this way is not a swift move because if a type is
+embedded in a more complex expression it is necessary to be able to tell
+where it ends.
I'm not sure how a boolean type is represented.
@code{integer}. 32 bit signed integral type.
@item -16
-@code{boolean}. Only one bit is used, not sure about the actual size of the
-type.
+@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?
@item -17
@code{short real}. IEEE single precision.
@code{stringptr}. @xref{Strings}.
@item -20
-@code{character}, 8 bit unsigned type.
+@code{character}, 8 bit unsigned character type.
@item -21
@code{logical*1}, 8 bit unsigned integral type.
@code{integer*4}, 32 bit signed integral type.
@item -30
-@code{wchar}. Wide character, 16 bits wide (Unicode format?). This is
-not used for the C type @code{wchar_t}.
+@code{wchar}. Wide character, 16 bits wide, unsigned (what format?
+Unicode?).
@end table
@node Miscellaneous Types
integral upper bound, and a semicolon. The AIX documentation does not
specify the trailing semicolon, in an effort to specify array indexes
more cleanly, but a subrange which is not an array index has always
-included a trailing semicolong (@pxref{Arrays}).
+included a trailing semicolon (@pxref{Arrays}).
Instead of an integer, either bound can be one of the following:
through version 4.9) doesn't support any kind of index type other than a
range anyway; I'm not sure about dbx.
+It is well established, and widely used, that the type of the index,
+unlike most types found in the stabs, is merely a type definition, not
+type information (@pxref{Stabs Format}) (that is, it need not start with
+@var{type-number}@code{=} if it is defining a new type). According to a
+comment in GDB, this is also true of the type of the array elements; it
+gives @samp{ar1;1;10;ar1;1;10;4} as a legitimate way to express a two
+dimensional array. According to AIX documentation, the element type
+must be type information. GDB accepts either.
+
The type of the index is often a range type, expressed as the letter r
and some parameters. It defines the size of the array. In the example
below, the range @code{r1;0;2;} defines an index type which is a
specifies that @code{s_typedef} refers to type number 16. Such stabs
have symbol type @code{N_LSYM} or @code{C_DECL}.
-If instead, you are giving a name to a tag for a structure, union, or
+If instead, you are specifying the tag name for a structure, union, or
enumeration, use the @samp{T} symbol descriptor instead. I believe C is
the only language with this feature.
130 .stabs "an_u:23",128,0,0,-20
@end example
-@node Function types
+@node Function Types
@section Function types
There are various types for function variables. These types are not
@chapter GNU C++ stabs
@menu
-* Basic Cplusplus types::
-* Simple classes::
-* Class instance::
-* Methods:: Method definition
-* Protections::
-* Method Modifiers:: (const, volatile, const volatile)
-* Virtual Methods::
-* Inheritence::
-* Virtual Base Classes::
-* Static Members::
+* Basic Cplusplus types::
+* Simple classes::
+* Class instance::
+* Methods:: Method definition
+* Protections::
+* Method Modifiers::
+* Virtual Methods::
+* Inheritence::
+* Virtual Base Classes::
+* Static Members::
@end menu
@subsection type descriptors added for C++ descriptions
N_LSYM,NIL,NIL,NIL
@end display
+@c FIXME: bogus line break.
@example
-.stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
+.stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
+ A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
@end example
@node Inheritence
137 .common _g_an_s,20,"bss"
@end example
-@node Stab types
-@appendix Table A: Symbol types from stabs
+@node Stab Types
+@appendix Values for the Stab Type Field
-Table A lists stab types sorted by type number. Stab type numbers are
-32 and greater. This is the full list of stab numbers, including stab
-types that are used in languages other than C.
+These are all the possible values for the stab type field, for
+@code{a.out} files. This does not apply to XCOFF.
-The #define names for these stab types are defined in:
-devo/include/aout/stab.def
+The following types are used by the linker and assembler; there is
+nothing stabs-specific about them. Since this document does not attempt
+to describe aspects of object file format other than the debugging
+format, no details are given.
-@smallexample
-type type #define used to describe
-dec hex name source program feature
-------------------------------------------------
-32 0x20 N_GYSM global symbol
-34 0X22 N_FNAME function name (for BSD Fortran)
-36 0x24 N_FUN function name or text segment variable for C
-38 0x26 N_STSYM static symbol (data segment w/internal linkage)
-40 0x28 N_LCSYM .lcomm symbol(BSS-seg variable w/internal linkage)
-42 0x2a N_MAIN Name of main routine (not used in C)
-48 0x30 N_PC global symbol (for Pascal)
-50 0x32 N_NSYMS number of symbols (according to Ultrix V4.0)
-52 0x34 N_NOMAP no DST map for sym (according to Ultrix V4.0)
-64 0x40 N_RSYM register variable
-66 0x42 N_M2C Modula-2 compilation unit
-68 0x44 N_SLINE line number in text segment
-70 0x46 N_DSLINE line number in data segment
-
-72 0x48 N_BSLINE line number in bss segment
-72 0x48 N_BROWS Sun source code browser, path to .cb file
-
-74 0x4a N_DEFD GNU Modula2 definition module dependency
-
-80 0x50 N_EHDECL GNU C++ exception variable
-80 0x50 N_MOD2 Modula2 info "for imc" (according to Ultrix V4.0)
-
-84 0x54 N_CATCH GNU C++ "catch" clause
-96 0x60 N_SSYM structure of union element
-100 0x64 N_SO path and name of source file
-128 0x80 N_LSYM automatic var in the stack
- (also used for type desc.)
-130 0x82 N_BINCL beginning of an include file (Sun only)
-132 0x84 N_SOL Name of sub-source (#include) file.
-160 0xa0 N_PSYM parameter variable
-162 0xa2 N_EINCL end of an include file
-164 0xa4 N_ENTRY alternate entry point
-192 0xc0 N_LBRAC beginning of a lexical block
-194 0xc2 N_EXCL place holder for a deleted include file
-196 0xc4 N_SCOPE modula2 scope information (Sun linker)
-224 0xe0 N_RBRAC end of a lexical block
-226 0xe2 N_BCOMM begin named common block
-228 0xe4 N_ECOMM end named common block
-232 0xe8 N_ECOML end common (local name)
-
- << used on Gould systems for non-base registers syms >>
-240 0xf0 N_NBTEXT ??
-242 0xf2 N_NBDATA ??
-244 0xf4 N_NBBSS ??
-246 0xf6 N_NBSTS ??
-248 0xf8 N_NBLCS ??
-@end smallexample
+@c Try to get most of these to fit on a single line.
+@iftex
+@tableindent=1.5in
+@end iftex
-@node Assembler types
-@appendix Table B: Symbol types from assembler and linker
+@table @code
+@item 0x0 N_UNDF
+Undefined symbol
-Table B shows the types of symbol table entries that hold assembler
-and linker symbols.
+@item 0x2 N_ABS
+File scope absolute symbol
-The #define names for these n_types values are defined in
-/include/aout/aout64.h
+@item 0x3 N_ABS | N_EXT
+External absolute symbol
-@smallexample
-dec hex #define
-n_type n_type name used to describe
-------------------------------------------
-1 0x0 N_UNDF undefined symbol
-2 0x2 N_ABS absolute symbol -- defined at a particular address
-3 0x3 extern " (vs. file scope)
-4 0x4 N_TEXT text symbol -- defined at offset in text segment
-5 0x5 extern " (vs. file scope)
-6 0x6 N_DATA data symbol -- defined at offset in data segment
-7 0x7 extern " (vs. file scope)
-8 0x8 N_BSS BSS symbol -- defined at offset in zero'd segment
-9 extern " (vs. file scope)
-
-12 0x0C N_FN_SEQ func name for Sequent compilers (stab exception)
-
-49 0x12 N_COMM common sym -- visable after shared lib dynamic link
-31 0x1f N_FN file name of a .o file
-@end smallexample
+@item 0x4 N_TEXT
+File scope text symbol
+
+@item 0x5 N_TEXT | N_EXT
+External text symbol
+
+@item 0x6 N_DATA
+File scope data symbol
+
+@item 0x7 N_DATA | N_EXT
+External data symbol
+
+@item 0x8 N_BSS
+File scope BSS symbol
+
+@item 0x9 N_BSS | N_EXT
+External BSS symbol
+
+@item 0x0c N_FN_SEQ
+Same as N_FN, for Sequent compilers
+
+@item 0x0a N_INDR
+Symbol is indirected to another symbol
+
+@item 0x12 N_COMM
+Common sym -- visable after shared lib dynamic link
+
+@item 0x14 N_SETA
+Absolute set element
+
+@item 0x16 N_SETT
+Text segment set element
+
+@item 0x18 N_SETD
+Data segment set element
+
+@item 0x1a N_SETB
+BSS segment set element
+
+@item 0x1c N_SETV
+Pointer to set vector
+
+@item 0x1e N_WARNING
+Print a warning message during linking
+
+@item 0x1f N_FN
+File name of a .o file
+@end table
+
+The following symbol types indicate that this is a stab. This is the
+full list of stab numbers, including stab types that are used in
+languages other than C.
+
+@table @code
+@item 0x20 N_GSYM
+Global symbol, @xref{N_GSYM}.
+
+@item 0x22 N_FNAME
+Function name (for BSD Fortran), @xref{N_FNAME}.
+
+@item 0x24 N_FUN
+Function name (@pxref{Procedures}) or text segment variable
+(@pxref{Statics}).
+
+@item 0x26 N_STSYM
+Data segment file-scope variable, @xref{Statics}.
+
+@item 0x28 N_LCSYM
+BSS segment file-scope variable, @xref{Statics}.
+
+@item 0x2a N_MAIN
+Name of main routine, @xref{Main Program}.
+
+@c FIXME: discuss this in the main body of the text where we talk about
+@c using N_FUN for variables.
+@item 0x2c N_ROSYM
+Read-only data symbol (Solaris2). Most systems use N_FUN for this.
+
+@item 0x30 N_PC
+Global symbol (for Pascal), @xref{N_PC}.
+
+@item 0x32 N_NSYMS
+Number of symbols (according to Ultrix V4.0), @xref{N_NSYMS}.
+
+@item 0x34 N_NOMAP
+No DST map for sym (according to Ultrix V4.0), @xref{N_NOMAP}.
+
+@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).
+
+@c See include/aout/stab.def for (a little) more info.
+@item 0x3c N_OPT
+Debugger options (Solaris2).
+
+@item 0x40 N_RSYM
+Register variable, @xref{N_RSYM}.
+
+@item 0x42 N_M2C
+Modula-2 compilation unit, @xref{N_M2C}.
+
+@item 0x44 N_SLINE
+Line number in text segment, @xref{Line Numbers}.
+
+@item 0x46 N_DSLINE
+Line number in data segment, @xref{Line Numbers}.
+
+@item 0x48 N_BSLINE
+Line number in bss segment, @xref{Line Numbers}.
+
+@item 0x48 N_BROWS
+Sun source code browser, path to .cb file, @xref{N_BROWS}.
+
+@item 0x4a N_DEFD
+Gnu Modula2 definition module dependency, @xref{N_DEFD}.
+
+@item 0x4c N_FLINE
+Function start/body/end line numbers (Solaris2).
+
+@item 0x50 N_EHDECL
+Gnu C++ exception variable, @xref{N_EHDECL}.
+
+@item 0x50 N_MOD2
+Modula2 info "for imc" (according to Ultrix V4.0), @xref{N_MOD2}.
+
+@item 0x54 N_CATCH
+Gnu C++ "catch" clause, @xref{N_CATCH}.
+
+@item 0x60 N_SSYM
+Structure of union element, @xref{N_SSYM}.
+
+@item 0x62 N_ENDM
+Last stab for module (Solaris2).
+
+@item 0x64 N_SO
+Path and name of source file , @xref{Source Files}.
+
+@item 0x80 N_LSYM
+Automatic var in the stack or type definition, @xref{N_LSYM}, @xref{Typedefs}.
+
+@item 0x82 N_BINCL
+Beginning of an include file (Sun only), @xref{Source Files}.
+
+@item 0x84 N_SOL
+Name of include file, @xref{Source Files}.
+
+@item 0xa0 N_PSYM
+Parameter variable, @xref{Parameters}.
+
+@item 0xa2 N_EINCL
+End of an include file, @xref{Source Files}.
+
+@item 0xa4 N_ENTRY
+Alternate entry point, @xref{N_ENTRY}.
+
+@item 0xc0 N_LBRAC
+Beginning of a lexical block, @xref{Block Structure}.
+
+@item 0xc2 N_EXCL
+Place holder for a deleted include file, @xref{Source Files}.
+
+@item 0xc4 N_SCOPE
+Modula2 scope information (Sun linker), @xref{N_SCOPE}.
+
+@item 0xe0 N_RBRAC
+End of a lexical block, @xref{Block Structure}.
+
+@item 0xe2 N_BCOMM
+Begin named common block, @xref{Common Blocks}.
+
+@item 0xe4 N_ECOMM
+End named common block, @xref{Common Blocks}.
+
+@item 0xe8 N_ECOML
+Member of a common block, @xref{Common Blocks}.
+
+@c FIXME: How does this really work? Move it to main body of document.
+@item 0xea N_WITH
+Pascal @code{with} statement: type,,0,0,offset (Solaris2).
+
+@item 0xf0 N_NBTEXT
+Gould non-base registers, @xref{Gould}.
+
+@item 0xf2 N_NBDATA
+Gould non-base registers, @xref{Gould}.
+
+@item 0xf4 N_NBBSS
+Gould non-base registers, @xref{Gould}.
+
+@item 0xf6 N_NBSTS
+Gould non-base registers, @xref{Gould}.
+
+@item 0xf8 N_NBLCS
+Gould non-base registers, @xref{Gould}.
+@end table
+
+@c Restore the default table indent
+@iftex
+@tableindent=.8in
+@end iftex
@node Symbol Descriptors
-@appendix Table C: Symbol descriptors
+@appendix Table of Symbol Descriptors
@c Please keep this alphabetical
@table @code
-@item @var{(digit)}
+@c In TeX, this looks great, digit is in italics. But makeinfo insists
+@c on putting it in `', not realizing that @var should override @code.
+@c I don't know of any way to make makeinfo do the right thing. Seems
+@c like a makeinfo bug to me.
+@item @var{digit}
@itemx (
@itemx -
Local variable, @xref{Automatic variables}.
Parameter in floating point register, @xref{Parameters}.
@item f
-Static function, @xref{Procedures}.
+File scope function, @xref{Procedures}.
@item F
Global function, @xref{Procedures}.
Register variable, @xref{Register variables}.
@item S
-Static file scope variable @xref{Initialized statics},
-@xref{Un-initialized statics}.
+File scope variable, @xref{Statics}.
@item t
Type name, @xref{Typedefs}.
Parameter passed by reference, @xref{Parameters}.
@item V
-Static procedure scope variable @xref{Initialized statics},
-@xref{Un-initialized statics}.
+Procedure scope static variable, @xref{Statics}.
@item x
Conformant array, @xref{Parameters}.
@end table
@node Type Descriptors
-@appendix Table D: Type Descriptors
+@appendix Table of Type Descriptors
@table @code
@item @var{digit}
N-dimensional subarray, @xref{Arrays}.
@item f
-Function type, @xref{Function types}.
+Function type, @xref{Function Types}.
+
+@item F
+Pascal function parameter, @xref{Function Types}
@item g
Builtin floating point type, @xref{Builtin Type Descriptors}.
@item K
COBOL File Descriptor. See AIX documentation for details.
+@item M
+Multiple instance type, @xref{Miscellaneous Types}.
+
@item n
String type, @xref{Strings}.
@item N
Stringptr, @xref{Strings}.
-@item M
-Multiple instance type, @xref{Miscellaneous Types}.
-
@item o
Opaque type, @xref{Typedefs}.
+@item p
+Procedure, @xref{Function Types}.
+
@item P
Packed array, @xref{Arrays}.
Range type, @xref{Subranges}.
@item R
-Builtin floating type, @xref{Builtin Type Descriptors}.
+Builtin floating type, @xref{Builtin Type Descriptors} (Sun). Pascal
+subroutine parameter, @xref{Function Types} (AIX). Detecting this
+conflict is possible with careful parsing (hint: a Pascal subroutine
+parameter type will always contain a comma, and a builtin type
+descriptor never will).
@item s
Structure type, @xref{Structures}.
@node Expanded reference
@appendix Expanded reference by stab type.
-@c FIXME: For most types this should be much shorter and much sweeter,
-@c see N_PSYM or N_SO for an example.
+@c FIXME: This appendix should go away, see N_PSYM or N_SO for an example.
-@c FIXME: It probably should be merged with Tables A and B.
+For a full list of stab types, and cross-references to where they are
+described, @xref{Stab Types}. This appendix just duplicates certain
+information from the main body of this document; eventually the
+information will all be in one place.
Format of an entry:
Finally, any further information.
@menu
-* N_GSYM:: Global variable
-* N_FNAME:: Function name (BSD Fortran)
-* N_FUN:: C Function name or text segment variable
-* N_STSYM:: Initialized static symbol
-* N_LCSYM:: Uninitialized static symbol
-* N_MAIN:: Name of main routine (not for C)
-* N_PC:: Pascal global symbol
-* N_NSYMS:: Number of symbols
-* N_NOMAP:: No DST map
-* N_RSYM:: Register variable
-* N_M2C:: Modula-2 compilation unit
-* N_SLINE: Line Numbers. Line number in text segment
-* N_DSLINE: Line Numbers. Line number in data segment
-* N_BSLINE: Line Numbers. Line number in bss segment
-* N_BROWS:: Path to .cb file for Sun source code browser
-* N_DEFD:: GNU Modula2 definition module dependency
-* N_EHDECL:: GNU C++ exception variable
-* N_MOD2:: Modula2 information "for imc"
-* N_CATCH:: GNU C++ "catch" clause
-* N_SSYM:: Structure or union element
-* N_SO: Source Files. Source file
-* N_LSYM:: Automatic variable
-* N_BINCL: Source Files. Beginning of include file
-* N_SOL: Source Files. Name of include file
-* N_PSYM: Parameters. Parameter variable
-* N_EINCL: Source Files. End of include file
-* N_ENTRY:: Alternate entry point
-* N_LBRAC:: Beginning of lexical block
-* N_EXCL: Source Files. Deleted include file
-* N_SCOPE:: Modula2 scope information (Sun only)
-* N_RBRAC:: End of lexical block
-* N_BCOMM:: Begin named common block
-* N_ECOMM:: End named common block
-* N_ECOML:: End common
-* Gould:: non-base register symbols used on Gould systems
-* N_LENG:: Length of preceding entry
+* N_GSYM:: Global variable
+* N_FNAME:: Function name (BSD Fortran)
+* N_PC:: Pascal global symbol
+* N_NSYMS:: Number of symbols
+* N_NOMAP:: No DST map
+* N_RSYM:: Register variable
+* N_M2C:: Modula-2 compilation unit
+* N_BROWS:: Path to .cb file for Sun source code browser
+* N_DEFD:: GNU Modula2 definition module dependency
+* N_EHDECL:: GNU C++ exception variable
+* N_MOD2:: Modula2 information "for imc"
+* N_CATCH:: GNU C++ "catch" clause
+* N_SSYM:: Structure or union element
+* N_LSYM:: Automatic variable
+* 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
@end menu
@node N_GSYM
Only the "name" field is significant. The location of the symbol is
obtained from the corresponding extern symbol.
-@node N_FUN
-@section 36 - 0x24 - N_FUN
-
-Function name (@pxref{Procedures}) or text segment variable
-(@pxref{Variables}).
-@example
-@exdent @emph{For functions:}
-"name" -> "proc_name:#return_type"
- # -> F (global function)
- f (local function)
-desc -> line num for proc start. (GCC doesn't set and DBX doesn't miss it.)
-value -> Code address of proc start.
-
-@exdent @emph{For text segment variables:}
-<<How to create one?>>
-@end example
-
-@node N_STSYM
-@section 38 - 0x26 - N_STSYM
-Initialized static symbol (data segment w/internal linkage).
-
-@display
-.stabs "name", N_STSYM, NIL, NIL, value
-@end display
-
-@example
-"name" -> "symbol_name#type"
- # -> S (scope global to compilation unit)
- -> V (scope local to a procedure)
-value -> Data Address
-@end example
-
-@node N_LCSYM
-@section 40 - 0x28 - N_LCSYM
-Unitialized static (.lcomm) symbol(BSS segment w/internal linkage).
-
-@display
-.stabs "name", N_LCLSYM, NIL, NIL, value
-@end display
-
-@example
-"name" -> "symbol_name#type"
- # -> S (scope global to compilation unit)
- -> V (scope local to procedure)
-value -> BSS Address
-@end example
-
-@node N_MAIN
-@section 42 - 0x2a - N_MAIN
-Name of main routine (not used in C)
-
-@display
-.stabs "name", N_MAIN, NIL, NIL, NIL
-@end display
-
-@example
-"name" -> "name_of_main_routine"
-@end example
-
@node N_PC
@section 48 - 0x30 - N_PC
Global symbol (for Pascal)
Value is its address.
<<?>>
-@node N_LBRAC
-@section 192 - 0xc0 - N_LBRAC
-
-Beginning of a lexical block (left brace). The variable defined
-inside the block precede the N_LBRAC symbol. Or can they follow as
-well as long as a new N_FUNC was not encountered. <<?>>
-
-@display
-.stabn N_LBRAC, NIL, NIL, value
-@end display
-
-@example
-value -> code address of block start.
-@end example
-
@node N_SCOPE
@section 196 - 0xc4 - N_SCOPE
Modula2 scope information (Sun linker)
<<?>>
-@node N_RBRAC
-@section 224 - 0xe0 - N_RBRAC
-
-End of a lexical block (right brace)
-
-@display
-.stabn N_RBRAC, NIL, NIL, value
-@end display
-
-@example
-value -> code address of the end of the block.
-@end example
-
-@node N_BCOMM
-@section 226 - 0xe2 - N_BCOMM
-
-Begin named common block.
-
-Only the name is significant.
-<<?>>
-
-@node N_ECOMM
-@section 228 - 0xe4 - N_ECOMM
-
-End named common block.
-
-Only the name is significant and it should match the N_BCOMM
-<<?>>
-
-@node N_ECOML
-@section 232 - 0xe8 - N_ECOML
-
-End common (local name)
-
-value is address.
-<<?>>
-
@node Gould
@section Non-base registers on Gould systems
-<< used on Gould systems for non-base registers syms, values assigned
-at random, need real info from Gould. >>
-<<?>>
+
+These are used on Gould systems for non-base registers syms.
+
+However, the following values are not the values used by Gould; they are
+the values which GNU has been documenting for these values for a long
+time, without actually checking what Gould uses. I include these values
+only because perhaps some someone actually did something with the GNU
+information (I hope not, why GNU knowingly assigned wrong values to
+these in the header file is a complete mystery to me).
@example
240 0xf0 N_NBTEXT ??
next N_FUN? (I believe its the first.)
@item
-The comment in xcoff.h says DBX_STATIC_CONST_VAR_CODE is used for
-static const variables. DBX_STATIC_CONST_VAR_CODE is set to N_FUN by
-default, in dbxout.c. If included, xcoff.h redefines it to N_STSYM.
-But testing the default behaviour, my Sun4 native example shows
-N_STSYM not N_FUN is used to describe file static initialized
-variables. (the code tests for TREE_READONLY(decl) &&
-!TREE_THIS_VOLATILE(decl) and if true uses DBX_STATIC_CONST_VAR_CODE).
-
-@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?
+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.
@item
Can gcc be configured to output stabs the way the Sun compiler
does, so that their native debugging tools work? <NO?> It doesn't by
mapping is N_STABTYPE becomes C_STABTYPE. Some stab types in a.out
are not supported in xcoff. See Table E. for full mappings.
+@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 N_STSYM and un-initialized static N_LCSYM both map
to the C_STSYM storage class. But the destinction is preserved
block. Begin the block with .bs s[RW] data_section_name for N_STSYM
or .bs s bss_section_name for N_LCSYM. End the block with .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 a N_FUN (C_FUN) then follow the string field with
,. instead of just ,
@end itemize
-
(I think that's it for .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 *lot* of differences in the information in the symbol
GNU C stabs define *all* types, file or procedure scope, as
N_LSYM. Sun doc talks about using N_GSYM too.
-@item
-Stabs describing block scopes, N_LBRAC and N_RBRAC are supposed to
-contain the nesting level of the block in the desc field, re Sun doc.
-GNU stabs always have 0 in that field. dbx seems not to care.
-
@item
Sun C stabs use type number pairs in the format (a,b) where a is a
number starting with 1 and incremented for each sub-source file in the
alone, with no source file number.
@end itemize
+@node Stabs-in-elf
+@appendix Using stabs with the ELF object file format.
+
+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 ".stab" section which contains
+an array of fixed length structures, one struct per stab, and a ".stabstr"
+section containing all the variable length strings that are referenced by
+stabs in the ".stab" section. The byte order of the stabs binary data
+matches the byte order of the ELF file itself, as determined from the
+EI_DATA field in the e_ident member of the ELF header.
+
+The first stab in the ".stab" section for each object file is a "synthetic
+stab", generated entirely by the assembler, with no corresponding ".stab"
+directive as input to the assembler. This stab contains the following
+fields:
+
+@itemize @bullet
+@item
+Offset in the ".stabstr" section to the source filename.
+
+@item
+N_UNDF
+
+@item
+Unused field, always zero.
+
+@item
+Count of upcoming symbols. I.E. the number of remaining stabs for this
+object module.
+
+@item
+Size of the string table fragment associated with this object module, in
+bytes.
+
+@end itemize
+
+The ".stabstr" section always starts with a null byte (so that string
+offsets of zero reference a null string), followed by random length strings,
+each of which is null byte terminated.
+
+The ELF section header for the ".stab" section has it's sh_link member set
+to the section number of the ".stabstr" section, and the ".stabstr" section
+has it's ELF section header sh_type member set to SHT_STRTAB to mark it as
+a string table.
+
@contents
@bye
projects / deliverable / binutils-gdb.git / blobdiff