This is the mail archive of the gdb-patches@sources.redhat.com mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[COMMIT] Minor changes in gdb.texinfo


FYI, I've committed the following changes in the manual, based on
recent discussions about related matters.

2005-06-18  Eli Zaretskii  <eliz@gnu.org>

	* gdb.texinfo (Server): Clarify that `file' should be used before
	connecting to the server.
	(Files): Add an xref to the above description.
	(Output Formats): More detailed description of the `c' format.
	(Memory): List explicitly all the formats supported by `x'.
	(Threads): Add an @cindex entry for "thread apply".
	(Files): Document the possibility of loading unlinked object
	files.  Add more indexing for solib-absolute-prefix and
	--with-sysroot.
	(Machine Code): Document possible problems with locations in
	shared libraries.
	(Backtrace): Document that free-standing environments do not need
	to have a `main' function.


Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.262
retrieving revision 1.269
diff -u -r1.262 -r1.269
--- gdb.texinfo	18 Jun 2005 03:01:48 -0000	1.262
+++ gdb.texinfo	18 Jun 2005 13:12:04 -0000	1.269
@@ -2386,6 +2386,7 @@
 threads.
 
 @kindex thread apply
+@cindex apply command to several threads
 @item thread apply [@var{threadno}] [@var{all}]  @var{args}
 The @code{thread apply} command allows you to apply a command to one or
 more threads.  Specify the numbers of the threads that you want affected
@@ -4299,7 +4300,11 @@
 @cindex startup code, and backtrace
 Most programs have a standard user entry point---a place where system
 libraries and startup code transition into user code.  For C this is
-@code{main}.  When @value{GDBN} finds the entry function in a backtrace
+@code{main}@footnote{
+Note that embedded programs (the so-called ``free-standing''
+environment) are not required to have a @code{main} function as the
+entry point.  They could even have multiple entry points.}.
+When @value{GDBN} finds the entry function in a backtrace
 it will terminate the backtrace, to avoid tracing into highly
 system-specific (and generally uninteresting) code.
 
@@ -4921,6 +4926,12 @@
 Some architectures have more than one commonly-used set of instruction
 mnemonics or other syntax.
 
+For programs that were dynamically linked and use shared libraries,
+instructions that call functions or branch to locations in the shared
+libraries might show a seemingly bogus location---it's actually a
+location of the relocation table.  On some architectures, @value{GDBN}
+might be able to resolve these to actual function names.
+
 @table @code
 @kindex set disassembly-flavor
 @cindex Intel disassembly flavor
@@ -5309,7 +5320,10 @@
 @xref{Symbols, info symbol}.
 
 @item c
-Regard as an integer and print it as a character constant.
+Regard as an integer and print it as a character constant.  This
+prints both the numerical value and its character representation.  The
+character representation is replaced with the octal escape @samp{\nnn}
+for characters outside the 7-bit @sc{ascii} range.
 
 @item f
 Regard the bits of the value as a floating point number and print
@@ -5359,10 +5373,12 @@
 @c 4.1.2.
 
 @item @var{f}, the display format
-The display format is one of the formats used by @code{print},
-@samp{s} (null-terminated string), or @samp{i} (machine instruction).
-The default is @samp{x} (hexadecimal) initially.
-The default changes each time you use either @code{x} or @code{print}.
+The display format is one of the formats used by @code{print}
+(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c},
+@samp{f}), and in addition @samp{s} (for null-terminated strings) and
+@samp{i} (for machine instructions).  The default is @samp{x}
+(hexadecimal) initially.  The default changes each time you use either
+@code{x} or @code{print}.
 
 @item @var{u}, the unit size
 The unit size is any of
@@ -10618,9 +10634,10 @@
 Out of @value{GDBN}}).
 
 Occasionally it is necessary to change to a different file during a
-@value{GDBN} session.  Or you may run @value{GDBN} and forget to specify
-a file you want to use.  In these situations the @value{GDBN} commands
-to specify new files are useful.
+@value{GDBN} session.  Or you may run @value{GDBN} and forget to
+specify a file you want to use.  Or you are debugging a remote target
+via @code{gdbserver} (@pxref{Server, file}).  In these situations the
+@value{GDBN} commands to specify new files are useful.
 
 @table @code
 @cindex executable file
@@ -10644,6 +10661,17 @@
 and with the commands @code{file}, @code{symbol-file}, or
 @code{add-symbol-file}, described below), for more information.
 
+@cindex unlinked object files
+@cindex patching object files
+You can load unlinked object @file{.o} files into @value{GDBN} using
+the @code{file} command.  You will not be able to ``run'' an object
+file, but you can disassemble functions and inspect variables.  Also,
+if the underlying BFD functionality supports it, you could use
+@kbd{gdb -write} to patch object files using this technique.  Note
+that @value{GDBN} can neither interpret nor modify relocations in this
+case, so branches and some initialized variables will appear to go to
+the wrong place.  But this feature is still handy from time to time.
+
 @item file
 @code{file} with no argument makes @value{GDBN} discard any information it
 has on both executable file and the symbol table.
@@ -11044,12 +11072,14 @@
 copies on the target can be stripped as long as the copies on the host are
 not.
 
-You need to tell @value{GDBN} where the target libraries are, so that it can
-load the correct copies---otherwise, it may try to load the host's libraries.
-@value{GDBN} has two variables to specify the search directories for target
-libraries.
+@cindex where to look for shared libraries
+For remote debugging, you need to tell @value{GDBN} where the target
+libraries are, so that it can load the correct copies---otherwise, it
+may try to load the host's libraries.  @value{GDBN} has two variables
+to specify the search directories for target libraries.
 
 @table @code
+@cindex prefix for shared library file names
 @kindex set solib-absolute-prefix
 @item set solib-absolute-prefix @var{path}
 If this variable is set, @var{path} will be used as a prefix for any
@@ -11059,6 +11089,8 @@
 out in the same way that they are on the target, with e.g.@: a
 @file{/usr/lib} hierarchy under @var{path}.
 
+@cindex default value of @samp{solib-absolute-prefix}
+@cindex @samp{--with-sysroot}
 You can set the default value of @samp{solib-absolute-prefix} by using the
 configure-time @samp{--with-sysroot} option.
 
@@ -11941,8 +11973,12 @@
 the @code{target remote} command.  Otherwise you may get an error whose
 text depends on the host system, but which usually looks something like
 @samp{Connection refused}.  You don't need to use the @code{load}
-command in @value{GDBN} when using gdbserver, since the program is
-already on the target.
+command in @value{GDBN} when using @code{gdbserver}, since the program is
+already on the target.  However, if you want to load the symbols (as
+you normally would), do that with the @code{file} command, and issue
+it @emph{before} connecting to the server; otherwise, you will get an
+error message saying @code{"Program is already running"}, since the
+program is considered running after the connection.
 
 @end table
 


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]