* stabs.texinfo: Update ld stabs in elf relocation to reflect the fact

	that Sun has backed away from the linker kludge and thus the relevant
	issue is changes to the SunPRO tools, not the Solaris linker.

	* stabs.texinfo (Traditional Integer Types): Clean up description
	of octal bounds a little bit.  Document extra leading zeroes.

2 files changed, 79 insertions, 46 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 470a1d9..9adbe65 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,12 @@
+Tue Oct 12 09:11:45 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* stabs.texinfo: Update ld stabs in elf relocation to reflect the fact
+	that Sun has backed away from the linker kludge and thus the relevant
+	issue is changes to the SunPRO tools, not the Solaris linker.
+
+	* stabs.texinfo (Traditional Integer Types): Clean up description
+	of octal bounds a little bit.  Document extra leading zeroes.
+
 Thu Oct  7 16:15:37 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
 
 	* gdb.texinfo (Signaling): Update for symbolic symbol names
diff --git a/gdb/doc/stabs.texinfo b/gdb/doc/stabs.texinfo
index 84f2a27..2fa12e3 100644
--- a/gdb/doc/stabs.texinfo
+++ b/gdb/doc/stabs.texinfo
@@ -517,12 +517,22 @@ one has complained).
 
 A function is represented by an @samp{F} symbol descriptor for a global
 (extern) function, and @samp{f} for a static (local) function.  The
-value is the address of the start of the function (absolute
-for @code{a.out}; relative to the start of the file for Sun's
-stabs-in-ELF).  The type information of the stab represents the return
-type of the function; thus @samp{foo:f5} means that foo is a function
-returning type 5.  There is no need to try to get the line number of the
-start of the function from the stab for the function; it is in the next
+value is the address of the start of the function.  For @code{a.out}, it
+is already relocated.  For stabs in ELF, the SunPRO compiler version
+2.0.1 and GCC put out an address which gets relocated by the linker.  In
+a future release SunPRO is planning to put out zero, in which case the
+address can be found from the ELF (non-stab) symbol.  Because looking
+things up in the ELF symbols would probably be slow, I'm not sure how to
+find which symbol of that name is the right one, and this doesn't
+provide any way to deal with nested functions, it would probably be
+better to make the value of the stab an address relative to the start of
+the file.  See @ref{Stabs In ELF} for more information on linker
+relocation of stabs in ELF files.
+
+The type information of the stab represents the return type of the
+function; thus @samp{foo:f5} means that foo is a function returning type
+5.  There is no need to try to get the line number of the start of the
+function from the stab for the function; it is in the next
 @code{N_SLINE} symbol.
 
 @c FIXME: verify whether the "I suspect" below is true or not.
@@ -910,12 +920,18 @@ need not indicate the section.
 In ECOFF files, the storage class is used to specify the section, so the
 stab type need not indicate the section.
 
-In ELF files, for Solaris 2.1, symbol descriptor @samp{S} means that the
-address is absolute (ld relocates it) and symbol descriptor @samp{V}
-means that the address is relative to the start of the relevant section
-for that compilation unit.  I don't know what it does for @samp{S} stabs
-on Solaris 2.3 (in which ld no longer relocates stabs).  For more
-information on ld stab relocation, @xref{Stabs In ELF}.
+In ELF files, for the SunPRO compiler version 2.0.1, symbol descriptor
+@samp{S} means that the address is absolute (the linker relocates it)
+and symbol descriptor @samp{V} means that the address is relative to the
+start of the relevant section for that compilation unit.  SunPRO has
+plans to have the linker stop relocating stabs; I suspect that their the
+debugger gets the address from the corresponding ELF (not stab) symbol.
+I'm not sure how to find which symbol of that name is the right one.
+The clean way to do all this would be to have a the value of a symbol
+descriptor @samp{S} symbol be an offset relative to the start of the
+file, just like everything else, but that introduces obvious
+compatibility problems.  For more information on linker stab relocation,
+@xref{Stabs In ELF}.
 
 @node Based Variables
 @section Fortran Based Variables
@@ -1218,13 +1234,22 @@ big to describe in an @code{int}.  Traditionally this is only used for
 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
 @end example
 
-For larger types, GCC 2.4.5 puts out bounds in octal, with a leading 0.
-In this case a negative bound consists of a number which is a 1 bit
-followed by a bunch of 0 bits, and a positive bound is one in which a
-bunch of bits are 1.  All known versions of dbx and GDB version 4 accept
-this, but GDB 3.5 refuses to read the whole file containing such
-symbols.  So GCC 2.3.3 did not output the proper size for these types.
-@c FIXME: How about an example?
+For larger types, GCC 2.4.5 puts out bounds in octal, with one or more
+leading zeroes.  In this case a negative bound consists of a number
+which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in
+the number (except the sign bit), and a positive bound is one which is a
+1 bit for each bit in the number (except possibly the sign bit).  All
+known versions of dbx and GDB version 4 accept this (at least in the
+sense of not refusing to process the file), but GDB 3.5 refuses to read
+the whole file containing such symbols.  So GCC 2.3.3 did not output the
+proper size for these types.  As an example of octal bounds, the string
+fields of the stabs for 64 bit integer types look like:
+
+@c .stabs directives, etc., omitted to make it fit on the page.
+@example
+long int:t3=r1;001000000000000000000000;000777777777777777777777;
+long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777;
+@end example
 
 If the lower bound of a subrange is 0 and the upper bound is negative,
 the type is an unsigned integral type whose size in bytes is the
@@ -3725,36 +3750,35 @@ header @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a
 string table.
 
 To keep linking fast, it is a bad idea to have the linker relocating
-stabs, so (except for Solaris 2.2 and earlier, see below) none of the
-addresses in the @code{n_value} field of the stabs are relocated by the
-linker.  Instead they are relative to the source file (or some entity
-smaller than a source file, like a function).  To find the address of
-each section corresponding to a given source file, the compiler puts out
+stabs, so (except for a few cases, see below) none of the addresses in
+the @code{n_value} field of the stabs are relocated by the linker.
+Instead they are relative to the source file (or some entity smaller
+than a source file, like a function).  To find the address of each
+section corresponding to a given source file, the compiler puts out
 symbols giving the address of each section for a given source file.
-Since these are ELF (not stab) symbols, the linker can relocate them
-correctly.  They are named @code{Bbss.bss} for the bss section,
-@code{Ddata.data} for the data section, and @code{Drodata.rodata} for
-the rodata section.  For the text section, there is no such symbol.  For
+Since these are ELF (not stab) symbols, the linker relocates them
+correctly without having to touch the stabs section.  They are named
+@code{Bbss.bss} for the bss section, @code{Ddata.data} for the data
+section, and @code{Drodata.rodata} for the rodata section.  For the text
+section, there is no such symbol (but there should be, see below).  For
 an example of how these symbols work, @xref{ELF Transformations}.  GCC
 does not provide these symbols; it instead relies on the stabs getting
-relocated, which loses for Solaris 2.3 (see below).  Thus address which
-would normally be relative to @code{Bbss.bss}, etc., are absolute.  The
-linker provided with Solaris 2.2 and earlier relocates stabs using
-relocation information from a @code{.rela.stab} section, which means
-that the value of an @code{N_FUN} stab in an executable is the actual
-address.  I think this is just standard ELF relocations, as it would do
-for any section, rather than a special-purpose stabs hack.  For Solaris
-2.3 and later, the linker ignores relocations for the stabs section.
-The value of a @code{N_FUN} stab is zero and the address of a function
-can be obtained from the ELF (non-stab) symbols.  Sun, in reference to
-bug 1142109, has verified that this is intentional.  Because looking
-things up in the ELF symbols would probably be slow, and this doesn't
-provide any way to deal with nested functions, it would probably be
-better to use a @code{Ttext.text} symbol for stabs-in-elf on non-Solaris
-machines, and make the address in the @code{N_FUN} relative to the
-@code{Ttext.text} symbol.  In addition to @code{N_FUN} symbols, whether
-the linker relocates stabs also affects some @code{N_ROSYM},
-@code{N_STSYM}, and @code{N_LCSYM} symbols; see @ref{Statics}.
+relocated, which slows down linking.  Thus addresses which would
+normally be relative to @code{Bbss.bss}, etc., are already relocated.
+The Sun linker provided with Solaris 2.2 and earlier relocates stabs
+using normal ELF relocation information, as it would do for any section.
+Sun has been threatening to kludge their linker to not do this (to speed
+up linking), even though the correct way to avoid having the linker do
+these relocations is to have the compiler no longer output relocatable
+values.  Last I heard they had been talked out of the linker kludge.
+See Sun point patch 101052-01 and Sun bug 1142109.  This affects
+@samp{S} symbol descriptor stabs (@pxref{Statics}) and functions
+(@pxref{Procedures}).  In the latter case, to adopt the clean solution
+(making the value of the stab relative to the start of the compilation
+unit), it would be necessary to invent a @code{Ttext.text} symbol,
+analogous to the @code{Bbss.bss}, etc., symbols.  I recommend this
+rather than using a zero value and getting the address from the ELF
+symbols.
 
 @node Symbol Types Index
 @unnumbered Symbol Types Index