This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
[COMMIT] Minor changes in gdb.texinfo
- From: Eli Zaretskii <eliz at gnu dot org>
- To: gdb-patches at sourceware dot org
- Date: Sat, 18 Jun 2005 16:17:25 +0200
- Subject: [COMMIT] Minor changes in gdb.texinfo
- Reply-to: Eli Zaretskii <eliz at gnu dot org>
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