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:: 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
+* 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
@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
@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
* Structures:: An aggregate type of different-typed elements.
* Typedefs:: Giving a type a name.
* Unions:: Different types sharing storage.
-* Function Types::
+* Function Types::
@end menu
@node Builtin types
@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
End of a lexical block, @xref{Block Structure}.
@item 0xe2 N_BCOMM
-Begin named common block, @xref{N_BCOMM}.
+Begin named common block, @xref{Common Blocks}.
@item 0xe4 N_ECOMM
-End named common block, @xref{N_ECOMM}.
+End named common block, @xref{Common Blocks}.
@item 0xe8 N_ECOML
-End common (local name), @xref{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
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_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)
-* 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
Modula2 scope information (Sun linker)
<<?>>
-@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
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