RFA: explain loading symbols from relocatable files

[Jim Blandy <jimb@zwingli.cygnus.com>]

2001-08-29  Jim Blandy  <jimb@redhat.com>

	* gdb.texinfo (`add-symbol-file'): Correct synopsis.
	Explain what it means to load relocatable files.

Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/cvsfiles/devo/gdb/doc/gdb.texinfo,v
retrieving revision 2.261
diff -c -r2.261 gdb.texinfo
*** gdb/doc/gdb.texinfo	2001/08/29 04:06:56	2.261
--- gdb/doc/gdb.texinfo	2001/08/29 17:40:43
***************
*** 8858,8864 ****
  @cindex dynamic linking
  @item add-symbol-file @var{filename} @var{address}
  @itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
! @itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address}
  The @code{add-symbol-file} command reads additional symbol table
  information from the file @var{filename}.  You would use this command
  when @var{filename} has been dynamically loaded (by some other means)
--- 8858,8864 ----
  @cindex dynamic linking
  @item add-symbol-file @var{filename} @var{address}
  @itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
! @itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
  The @code{add-symbol-file} command reads additional symbol table
  information from the file @var{filename}.  You would use this command
  when @var{filename} has been dynamically loaded (by some other means)
***************
*** 8874,8879 ****
--- 8874,8913 ----
  @code{add-symbol-file} command any number of times; the new symbol data
  thus read keeps adding to the old.  To discard all old symbol data
  instead, use the @code{symbol-file} command without any arguments.
+ 
+ @cindex relocatable object files, reading symbols from
+ @cindex object files, relocatable, reading symbols from
+ @cindex reading symbols from relocatable object files
+ @cindex symbols, reading from relocatable object files
+ @cindex .o files, reading symbols from
+ Although @var{filename} is typically a shared library file, an
+ executable file, or some other object file which has been fully
+ relocated for loading into a process, you can also load symbolic
+ information from relocatable @file{.o} files, as long as:
+ 
+ @itemize @bullet
+ @item
+ the file's symbolic information refers only to linker symbols defined in
+ that file, not to symbols defined by other object files,
+ @item
+ every section the file's symbolic information refers to has actually
+ been loaded into the inferior, as it appears in the file, and
+ @item
+ you can determine the address at which every section was loaded, and
+ provide these to the @code{add-symbol-file} command.
+ @end itemize
+ 
+ @noindent
+ Some embedded operating systems, like Sun Chorus and VxWorks, can load
+ relocatable files into an already running program; such systems
+ typically make the requirements above easy to meet.  However, it's
+ important to recognize that many native systems use complex link
+ procedures (@code{.linkonce} section factoring and C++ constructor table
+ assembly, for example) that make the requirements difficult to meet.  In
+ general, one cannot assume that using @code{add-symbol-file} to read a
+ relocatable object file's symbolic information will have the same effect
+ as linking the relocatable object file into the program in the normal
+ way.
  
  @code{add-symbol-file} does not repeat if you press @key{RET} after using it.