RFA: explain loading symbols from relocatable files

Jim Blandy
2001-08-29T10:43:00Z

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.