* stabs.texinfo (String Field): Document type number pairs here,

	instead of in the Sun specific section.
	(Include Files): The GNU linker supports the N_BINCL
	optimization.  Clarify the N_BINCL value, and what it is used
	for.
	(Procedures): Document N_FUN with an empty string to mark the end
	of a function.
	(Typedefs): Mention that Sun compilers may use N_GSYM for a type.
	(Sun Differences): Remove this node, as the information is now
	elsewhere in the main document.
	(Stab Section Basics): Mention that the GNU linker may optimize
	stabs and remove the leading N_UNDF symbol.

1 files changed, 52 insertions, 42 deletions

diff --git a/gdb/doc/stabs.texinfo b/gdb/doc/stabs.texinfo
index 0769272..f82f128 100644
--- a/gdb/doc/stabs.texinfo
+++ b/gdb/doc/stabs.texinfo
@@ -14,7 +14,7 @@ END-INFO-DIR-ENTRY
 @ifinfo
 This document describes the stabs debugging symbol tables.
 
-Copyright 1992, 1993 Free Software Foundation, Inc.
+Copyright 1992, 93, 94, 95, 1997 Free Software Foundation, Inc.
 Contributed by Cygnus Support.  Written by Julia Menapace, Jim Kingdon,
 and David MacKenzie.
 
@@ -52,7 +52,7 @@ regarded as a program in the language TeX).
 @end tex
 
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1992, 1993 Free Software Foundation, Inc.
+Copyright @copyright{} 1992, 93, 94, 95, 1997 Free Software Foundation, Inc.
 Contributed by Cygnus Support.
 
 Permission is granted to make and distribute verbatim copies of
@@ -80,8 +80,6 @@ This document describes the stabs debugging format.
 * Type Descriptors::		Table of type descriptors
 * Expanded Reference::		Reference information by stab type
 * Questions::			Questions and anomolies
-* Sun Differences::		Differences between GNU stabs and Sun
-                                native stabs
 * Stab Sections::		In some object file formats, stabs are
                                 in sections.
 * Symbol Types Index::          Index of symbolic stab symbol type names.
@@ -240,6 +238,18 @@ type is about to be defined.  Any other values following the
 a number follows the @samp{=} then the number is a @var{type-reference}.
 For a full description of types, @ref{Types}.
 
+A @var{type-number} is often a single number.  The GNU and Sun tools
+additionally permit a @var{type-number} to be a pair
+(@var{file-number},@var{filetype-number}) (the parentheses appear in the
+string, and serve to distinguish the two cases).  The @var{file-number}
+is a number starting with 1 which is incremented for each seperate
+source file in the compilation (e.g., in C, each header file gets a
+different number).  The @var{filetype-number} is a number starting with
+1 which is incremented for each new type defined in the file.
+(Separating the file number and the type number permits the
+@code{N_BINCL} optimization to succeed more often; see @ref{Include
+Files}).
+
 There is an AIX extension for type attributes.  Following the @samp{=}
 are any number of type attributes.  Each one starts with @samp{@@} and
 ends with @samp{;}.  Debuggers, including AIX's dbx and GDB 4.10, skip
@@ -463,7 +473,7 @@ the start of this one.  To specify the main source file again, use an
 @findex N_EXCL
 The @code{N_BINCL} approach works as follows.  An @code{N_BINCL} symbol
 specifies the start of an include file.  In an object file, only the
-string is significant; the Sun linker puts data into some of the other
+string is significant; the linker puts data into some of the other
 fields.  The end of the include file is marked by an @code{N_EINCL}
 symbol (which has no string field).  In an object file, there is no
 significant data in the @code{N_EINCL} symbol.  @code{N_BINCL} and
@@ -473,16 +483,17 @@ If the linker detects that two source files have identical stabs between
 an @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.
-
-The SunOS4 linker sets the value of a @code{N_BINCL} symbol to the total
-of all the characters in the stabs strings included in the header file,
-omitting the file number.  The value of an @code{N_EXCL} symbol is the
-same as the value of the @code{N_BINCL} symbol it replaces.  I do not
-know if this information is used by anything.  The @code{N_EINCL} value,
-and the values of the other and description fields for all three, appear
-to always be zero.
+the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
+ones which supports this feature.
+
+A linker which supports this feature will set the value of a
+@code{N_BINCL} symbol to the total of all the characters in the stabs
+strings included in the header file, omitting any file numbers.  The
+value of an @code{N_EXCL} symbol is the same as the value of the
+@code{N_BINCL} symbol it replaces.  This information can be used to
+match up @code{N_EXCL} and @code{N_BINCL} symbols which have the same
+filename.  The @code{N_EINCL} value, and the values of the other and
+description fields for all three, appear to always be zero.
 
 @findex C_BINCL
 @findex C_EINCL
@@ -632,6 +643,15 @@ group of other stabs describing elements of the procedure.  These other
 stabs describe the procedure's parameters, its block local variables, and
 its block structure.
 
+If functions can appear in different sections, then the debugger may not
+be able to find the end of a function.  Recent versions of GCC will mark
+the end of a function with an @code{N_FUN} symbol with an empty string
+for the name.  The value is the address of the end of the current
+function.  Without such a symbol, there is no indication of the address
+of the end of a function, and you must assume that it ended at the
+starting address of the next function or at the end of the text section
+for the program.
+
 @node Nested Procedures
 @section Nested Procedures
 
@@ -2060,7 +2080,8 @@ For example,
 @end example
 
 specifies that @code{s_typedef} refers to type number 16.  Such stabs
-have symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF).
+have symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF).  (The Sun
+documentation mentions using @code{N_GSYM} in some cases).
 
 If you are specifying the tag name for a structure, union, or
 enumeration, use the @samp{T} symbol descriptor instead.  I believe C is
@@ -3841,25 +3862,6 @@ What ends the procedure scope?  Is it the proc block's @code{N_RBRAC} or the
 next @code{N_FUN}?  (I believe its the first.)
 @end itemize
 
-@node Sun Differences
-@appendix Differences Between GNU Stabs and Sun Native Stabs
-
-@c FIXME: Merge all this stuff into the main body of the document.
-
-@itemize @bullet
-@item
-GNU C stabs define @emph{all} types, file or procedure scope, as
-@code{N_LSYM}.  Sun doc talks about using @code{N_GSYM} too.
-
-@item
-Sun C stabs use type number pairs in the format
-(@var{file-number},@var{type-number}) where @var{file-number} is a
-number starting with 1 and incremented for each sub-source file in the
-compilation.  @var{type-number} is a number starting with 1 and
-incremented for each new type defined in the compilation.  GNU C stabs
-use the type number alone, with no source file number.
-@end itemize
-
 @node Stab Sections
 @appendix Using Stabs in Their Own Sections
 
@@ -3928,17 +3930,25 @@ header @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a
 string table.  SOM and COFF have no way of linking the sections together
 or marking them as string tables.
 
-For COFF, the @code{.stab} and @code{.stabstr} sections are simply
+For COFF, the @code{.stab} and @code{.stabstr} sections may be simply
 concatenated by the linker.  GDB then uses the @code{n_desc} fields to
 figure out the extent of the original sections.  Similarly, the
 @code{n_value} fields of the header symbols are added together in order
 to get the actual position of the strings in a desired @code{.stabstr}
-section.  Although this design obviates any need for the linker to relocate
-or otherwise manipulate @code{.stab} and @code{.stabstr} sections, it also
-requires some care to ensure that the offsets are calculated correctly.
-For instance, if the linker were to pad in between the @code{.stabstr}
-sections before concatenating, then the offsets to strings in the middle
-of the executable's @code{.stabstr} section would be wrong.
+section.  Although this design obviates any need for the linker to
+relocate or otherwise manipulate @code{.stab} and @code{.stabstr}
+sections, it also requires some care to ensure that the offsets are
+calculated correctly.  For instance, if the linker were to pad in
+between the @code{.stabstr} sections before concatenating, then the
+offsets to strings in the middle of the executable's @code{.stabstr}
+section would be wrong.
+
+The GNU linker is able to optimize stabs information by merging
+duplicate strings and removing duplicate header file information
+(@pxref{Include Files}).  When the GNU linker optimizes stabs in
+sections, it removes the leading @code{N_UNDF} symbol, and arranges for
+all the @code{n_strx} fields to be relative to the start of the
+@code{.stabstr} section.
 
 @node ELF Linker Relocation
 @appendixsec Having the Linker Relocate Stabs in ELF