@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
differentiated by the first word of the stab. The name of the directive
describes what combination of four possible data fields will follow. It
is either @code{.stabs} (string), @code{.stabn} (number), or
-@code{.stabd} (dot).
+@code{.stabd} (dot). IBM's xcoff 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},0,@var{desc},@var{value}
-.stabn @var{type},0,@var{desc},@var{value}
-.stabd @var{type},0,@var{desc}
+.stabx "@var{string}",@var{value},@var{type},@var{sdb-type}
+.stabn @var{type},0,@var{desc},@var{value}
+.stabd @var{type},0,@var{desc}
@end example
-In general, in @code{.stabs} the @var{string} field contains name and type
-information. For @code{.stabd} the value field is implicit and has the value
-of the current file location. Otherwise the value field often
-contains a relocatable address, frame pointer offset, or register
-number, that maps to the source code element described by the stab.
+@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 string (the
+@code{n_strx} field is zero, @pxref{Symbol Tables}). For @code{.stabd}
+the value field is implicit and has the value of the current file
+location. The @var{sdb-type} field to @code{.stabx} is unused for stabs
+and can always be set to 0.
The number in the type field gives some basic information about what
type of stab this is (or whether it @emph{is} a stab, as opposed to an
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
There is an AIX extension for type attributes. Following the @samp{=}
is any number of type attributes. Each one starts with @samp{@@} and
ends with @samp{;}. Debuggers, including AIX's dbx, skip any type
-attributes they do not recognize. GDB 4.9 does not do this--it will
+attributes they do not recognize. GDB 4.9 does not do this---it will
ignore the entire symbol containing a type attribute. Hopefully this
will be fixed in the next GDB release. Because of a conflict with C++
(@pxref{Cplusplus}), new attributes should not be defined which begin
@chapter Encoding for the structure of the program
@menu
-* Source file:: The path and name of the source file
-* Line numbers::
-* Procedures::
-* Block Structure::
+* Source Files:: The path and name of the source file
+* Line Numbers::
+* Procedures::
+* Block Structure::
@end menu
-@node Source file
-@section The path and name of the source file
-
-@table @strong
-@item Directive:
-@code{.stabs}
-@item Type:
-@code{N_SO}
-@end table
-
-The first stabs in the .s file contain the name and path of the source
-file that was compiled to produce the .s file. This information is
-contained in two records of stab type N_SO (100).
-
-@example
- .stabs "path_name", N_SO, NIL, NIL, Code_address_of_program_start
- .stabs "file_name:", N_SO, NIL, NIL, Code_address_of_program_start
-@end example
-
-@example
-2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
-3 .stabs "hello.c",100,0,0,Ltext0
-4 .text
-5 Ltext0:
-@end example
-
-@node Line numbers
+@node Source Files
+@section The path and name of the source files
+
+Before any other stabs occur, there must be a stab specifying the source
+file. This information is contained in a symbol of stab type
+@code{N_SO}; the string contains the name of the file. The value of the
+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. 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:
+
+@example
+.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 ; 100 is N_SO
+.stabs "hello.c",100,0,0,Ltext0
+ .text
+Ltext0:
+@end example
+
+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.
+
+There are several different schemes for dealing with include files: the
+traditional @code{N_SOL} approach, Sun's @code{N_BINCL} scheme, and the
+XCOFF @code{C_BINCL} (which despite the similar name has little in
+common with @code{N_BINCL}).
+
+An @code{N_SOL} symbol specifies which include file subsequent symbols
+refer to. The string field is the name of the file and the value is the
+text address corresponding to the start of the previous include file and
+the start of this one. To specify the main source file again, use an
+@code{N_SOL} symbol with the name of the main source file.
+
+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 (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}
+directive, which generates a @code{C_EINCL} symbol, denotes the end of
+the include file. Both directives are followed by the name of the
+source file in quotes, which becomes the string for the symbol. The
+value of each symbol, produced automatically by the assembler and
+linker, is an offset into the executable which points to the beginning
+(inclusive, as you'd expect) and end (inclusive, as you would not
+expect) of the portion of the COFF linetable which corresponds to this
+include file. @code{C_BINCL} and @code{C_EINCL} do not nest.
+
+@node Line Numbers
@section Line Numbers
-@table @strong
-@item Directive:
-@code{.stabn}
-@item Type:
-@code{N_SLINE}
-@end table
-
-The start of source lines is represented by the @code{N_SLINE} (68) stab
-type.
-
-@example
-.stabn N_SLINE, NIL, @var{line}, @var{address}
-@end example
+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. 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
+to @code{N_SLINE} but are relocated differently by the linker. They
+were intended to be used to describe the source location of a variable
+declaration, but I believe that gcc2 actually puts the line number in
+the desc field of the stab for the variable itself. GDB has been
+ignoring these symbols (unless they contain a string field) at least
+since GDB 3.5.
+
+XCOFF uses COFF line numbers instead, which are outside the scope of
+this document, ammeliorated by adequate marking of include files
+(@pxref{Source Files}).
-@var{line} is a source line number; @var{address} represents the code
-address for the start of that source line.
-
-@example
-27 _main:
-28 .stabn 68,0,4,LM1
-29 LM1:
-30 !#PROLOGUE# 0
-@end example
+For single source lines that generate discontiguous code, such as flow
+of control statements, there may be more than one line number entry for
+the same source line. In this case there is a line number entry at the
+start of each code range, each with the same line number.
@node Procedures
@section Procedures
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.
+* Initialized statics:: Static variables with values.
+* Un-initialized statics:: Static variables initialialized to 0.
+* Parameters:: Passing variables 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 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. Each variable in the
+common block has a @code{N_ECOML} stab, whose value is the offset within
+the common block of that variable. I'm not sure what symbol descriptor
+is used for the @code{N_ECOML} stabs.
+
@node Initialized statics
@section Initialized static variables
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.
type. It is followed by type information for the type which it is a
subrange of, a semicolon, an integral lower bound, a semicolon, an
integral upper bound, and a semicolon. The AIX documentation does not
-specify the trailing semicolon; I believe it is confused.
+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 semicolon (@pxref{Arrays}).
-AIX allows the bounds to be one of the following instead of an integer:
+Instead of an integer, either bound can be one of the following:
@table @code
@item A @var{offset}
@section Array types
Arrays use the @samp{a} type descriptor. Following the type descriptor
-is the type of the index and the type of the array elements. The two
-types types are not separated by any sort of delimiter; if the type of
-the index does not end in a semicolon I don't know what is supposed to
-happen. IBM documents a semicolon between the two types. For the
-common case (a range type), this ends up as being the same since IBM
-documents a range type as not ending in a semicolon, but the latter does
-not accord with common practice, in which range types do end with
-semicolons.
+is the type of the index and the type of the array elements. If the
+index type is a range type, it will end in a semicolon; if it is not a
+range type (for example, if it is a type reference), there does not
+appear to be any way to tell where the types are separated. In an
+effort to clean up this mess, IBM documents the two types as being
+separated by a semicolon, and a range type as not ending in a semicolon
+(but this is not right for range types which are not array indexes,
+@pxref{Subranges}). I think probably the best solution is to specify
+that a semicolon ends a range type, and that the index type and element
+type of an array are separated by a semicolon, but that if the index
+type is a range type, the extra semicolon can be omitted. GDB (at least
+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
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
The variable defines a new type, 24, which is a pointer to another new
type, 25, which is defined as a function returning int.
-@node Symbol tables
+@node Symbol Tables
@chapter Symbol information in symbol tables
This section examines more closely the format of symbol table entries
@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
@c FIXME!!! the linebreaks in the following example probably make the
@c examples literally unusable, but I don't know any other way to get
@c them on the page.
+@c One solution would be to put some of the type definitions into
+@c separate stabs, even if that's not exactly what the compiler actually
+@c emits.
@smallexample
.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
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 or text segment variable for C, @xref{N_FUN}.
+
+@item 0x26 N_STSYM
+Static symbol (data segment variable with internal linkage), @xref{N_STSYM}.
+
+@item 0x28 N_LCSYM
+.lcomm symbol (BSS segment variable with internal linkage), @xref{N_LCSYM}.
+
+@item 0x2a N_MAIN
+Name of main routine (not used in C), @xref{N_MAIN}.
+
+@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}.
@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 for an example. For stuff like N_SO where the stab type
-@c really is the important thing, the information can stay here.
+@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 number in text segment
-* N_DSLINE:: Line number in data segment
-* N_BSLINE:: 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 file containing main
-* N_LSYM:: Automatic variable
-* N_BINCL:: Beginning of include file (Sun only)
-* N_SOL:: Name of include file
-* N_PSYM:: Parameter variable
-* N_EINCL:: End of include file
-* N_ENTRY:: Alternate entry point
-* N_LBRAC:: Beginning of lexical block
-* N_EXCL:: 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_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_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
1 (any other unit)
@end example
-@node N_SLINE
-@section 68 - 0x44 - N_SLINE
-Line number in text segment
-
-@display
-.stabn N_SLINE, 0, desc, value
-@end display
-
-@example
-desc -> line_number
-value -> code_address (relocatable addr where the corresponding code starts)
-@end example
-
-For single source lines that generate discontiguous code, such as flow
-of control statements, there may be more than one N_SLINE stab for the
-same source line. In this case there is a stab at the start of each
-code range, each with the same line number.
-
-@node N_DSLINE
-@section 70 - 0x46 - N_DSLINE
-Line number in data segment
-
-@display
-.stabn N_DSLINE, 0, desc, value
-@end display
-
-@example
-desc -> line_number
-value -> data_address (relocatable addr where the corresponding code
-starts)
-@end example
-
-See comment for N_SLINE above.
-
-@node N_BSLINE
-@section 72 - 0x48 - N_BSLINE
-Line number in bss segment
-
-@display
-.stabn N_BSLINE, 0, desc, value
-@end display
-
-@example
-desc -> line_number
-value -> bss_address (relocatable addr where the corresponding code
-starts)
-@end example
-
-See comment for N_SLINE above.
-
@node N_BROWS
@section 72 - 0x48 - N_BROWS
Sun source code browser, path to .cb file
<<?looking at structs and unions in C I didn't see these>>
-@node N_SO
-@section 100 - 0x64 - N_SO
-Path and name of source file containing main routine
-
-@display
-.stabs "name", N_SO, NIL, NIL, value
-@end display
-
-@example
-"name" -> /source/directory/
- -> source_file
-
-value -> the starting text address of the compilation.
-@end example
-
-These are found two in a row. The name field of the first N_SO contains
-the directory that the source file is relative to. The name field of
-the second N_SO contains the name of the source file itself.
-
-Only some compilers (e.g. gcc2, Sun cc) include the directory; this
-symbol can be distinguished by the fact that it ends in a slash.
-According to a comment in GDB's 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).
-
@node N_LSYM
@section 128 - 0x80 - N_LSYM
Automatic var in the stack (also used for type descriptors.)
defines the type. See the Table D for type descriptors and the
section on types for what data follows each type descriptor.
-@node N_BINCL
-@section 130 - 0x82 - N_BINCL
-
-Beginning of an include file (Sun only)
-
-Beginning of an include file. Only Sun uses this. In an object file,
-only the name is significant. The Sun linker puts data into some of
-the other fields.
-
-@node N_SOL
-@section 132 - 0x84 - N_SOL
-
-Name of a sub-source file (#include file). Value is starting address
-of the compilation.
-<<?>>
-
-@node N_PSYM
-@section 160 - 0xa0 - N_PSYM
-
-Parameter variable. @xref{Parameters}.
-
-@node N_EINCL
-@section 162 - 0xa2 - N_EINCL
-
-End of an include file. This and N_BINCL act as brackets around the
-file's output. In an ojbect file, there is no significant data in
-this entry. The Sun linker puts data into some of the fields.
-<<?>>
-
@node N_ENTRY
@section 164 - 0xa4 - N_ENTRY
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_EXCL
-@section 194 - 0xc2 - N_EXCL
-
-Place holder for a deleted include file. Replaces a N_BINCL and
-everything up to the corresponding N_EINCL. The Sun linker generates
-these when it finds multiple indentical copies of the symbols from an
-included file. This appears only in output from the Sun linker.
-<<?>>
-
@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 ??
body of this document.
@itemize @bullet
-@item
-Instead of .stabs, xcoff uses .stabx.
-
-@item
-The data fields of an xcoff .stabx are in a different order than an
-a.out .stabs. The order is: string, value, type, sdb-type. The desc
-and null fields present in a.out stabs are missing in xcoff stabs. For
-N_GSYM the value field is the name of the symbol. sdb-type is unused
-with stabs; it can always be set to 0.
-
@item
BSD a.out stab types correspond to AIX xcoff storage classes. In general the
mapping is N_STABTYPE becomes C_STABTYPE. Some stab types in a.out
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
-@item
-xcoff uses a .file stab type to represent the source file name. There
-is no stab for the path to the source file.
-
-@item
-xcoff uses a .line stab type to represent source lines. The format
-is: .line line_number.
-
-@item
-xcoff emits line numbers relative to the start of the current
-function. The start of a function is marked by .bf. If a function
-includes lines from a seperate file, then those line numbers are
-absolute line numbers in the <<sub-?>> file being compiled.
-
-@item
-The start of current include file is marked with: .bi "filename" and
-the end marked with .ei "filename"
-
@item
If the xcoff stab is a N_FUN (C_FUN) then follow the string field with
,. instead of just ,
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