@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
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 Files:: 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 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}.
+scope of a procedure are located after the @code{N_FUN} stab that
+represents the procedure itself.
-@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
-
-@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.
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 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 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_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
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 ??
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