This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[PATCH 3/3] Target remote mode fork and exec docs
- From: Don Breazeal <donb at codesourcery dot com>
- To: <gdb-patches at sourceware dot org>
- Date: Fri, 6 Nov 2015 15:56:28 -0800
- Subject: [PATCH 3/3] Target remote mode fork and exec docs
- Authentication-results: sourceware.org; auth=none
- References: <1446854188-496-1-git-send-email-donb at codesourcery dot com>
This patch implements documentation updates for target remote mode
fork and exec events. A summary of the rationale for the changes
made here:
* Connecting to a remote target -- explain that the two protocols exist.
* Connecting in target remote mode -- explain invoking gdbserver for
target remote mode, and move remote-specific text from original
"Connecting to a remote target" section.
* Connecting in target extended-remote mode -- promote this section
from "Using the gdbserver Program | Running gdbserver | Multi-Process Mode
for gdbserver". Put it next to the target remote mode section.
* Host and target files -- collect paragraphs dealing with how to locate
symbol files from original sections "Connecting to a remote target" and
"Using the gdbserver program | Connecting to gdbserver".
* Steps for connecting to a remote target -- used to be "Using the
gdbserver program | Connecting to gdbserver"
* Remote connection commands -- used to be the bulk of "Connecting to a
remote target". Added "target extended-remote" commands and information.
Thanks,
--Don
gdb/
2015-11-06 Don Breazeal <donb@sourceware.org>
* NEWS: Announce fork and exec event support for target remote.
gdb/doc/
2015-11-06 Don Breazeal <donb@sourceware.org>
* gdb.texinfo (Forks): Correct Linux kernel version where
fork and exec events are supported, add notes about support
of these events in target remote mode.
(Connecting): Reorganize and clarify distinctions between
target remote, extended-remote, and multiprocess.
Reorganize related text from separate sections into new
sections. Use @kbd consistently for target commands
instead of @code or @samp.
---
gdb/NEWS | 8 ++
gdb/doc/gdb.texinfo | 212 ++++++++++++++++++++++++++++++++--------------------
2 files changed, 137 insertions(+), 83 deletions(-)
diff --git a/gdb/NEWS b/gdb/NEWS
index b2b1e99..166a6ca 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -87,6 +87,14 @@ set remote exec-event-feature-packet
show remote exec-event-feature-packet
Set/show the use of the remote exec event feature.
+* Target remote mode fork and exec events
+
+ ** GDB now has support for fork and exec events on target remote mode
+ Linux targets. For such targets with Linux kernels 2.5.46 and later,
+ this enables follow-fork-mode, detach-on-fork and fork and exec
+ catchpoints. Note that follow-exec-mode is not supported, because
+ target remote mode does not support the 'run' command.
+
*** Changes in GDB 7.10
* Support for process record-replay and reverse debugging on aarch64*-linux*
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 3c1f785..e364efb 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3133,10 +3133,11 @@ the child process just like any other process which you attached to.
On some systems, @value{GDBN} provides support for debugging programs that
create additional processes using the @code{fork} or @code{vfork} functions.
Currently, the only platforms with this feature are HP-UX (11.x and later
-only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
+only?) and @sc{gnu}/Linux (kernel version 2.5.46 and later).
-The fork debugging commands are supported in both native mode and when
-connected to @code{gdbserver} using @kbd{target extended-remote}.
+The fork debugging commands are supported in native mode and when
+connected to @code{gdbserver} in either @kbd{target remote} mode or
+@kbd{target extended-remote} mode.
By default, when a program forks, @value{GDBN} will continue to debug
the parent process and the child process will run unimpeded.
@@ -3282,6 +3283,11 @@ Program exited normally.
@end table
@end table
+@code{follow-exec-mode} is supported in native mode and
+@kbd{target extended-remote} mode. It has no real effect in
+@kbd{target remote} mode since the run command is not supported in that
+mode.
+
You can use the @code{catch} command to make @value{GDBN} stop whenever
a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
Catchpoints, ,Setting Catchpoints}.
@@ -19221,28 +19227,126 @@ configuration of @value{GDBN}; use @code{help target} to list them.
@node Connecting
@section Connecting to a Remote Target
-@value{GDBN} needs an unstripped copy of your program to access symbol
-and debugging information. Some remote targets (@pxref{qXfer
-executable filename read}, and @pxref{Host I/O Packets}) allow
-@value{GDBN} to access program files over the same connection used to
-communicate with @value{GDBN}. With such a target, if the remote
-program is unstripped, the only command you need is @code{target
-remote}. Otherwise, start up @value{GDBN} using the name of the local
+@value{GDBN} supports two types of remote connections, @kbd{target remote}
+mode and @kbd{target extended-remote} mode. There are several major
+differences between the two. In @kbd{target extended-remote} mode, GDB
+stays connected to @code{gdbserver} after the debugged program exits or you
+detach from it, and @code{gdbserver} provides support for the @code{run}
+and @code{attach} commands.
+
+@subsection Connecting in @kbd{target remote} mode
+
+When you invoke @code{gdbserver} for a @kbd{target remote} mode
+session, you must either specify the program to debug or use the
+@option{--attach} option (@pxref{Server,,Running gdbserver}).
+
+Once the connection has been established, you can use all the usual
+@value{GDBN} commands to examine and change data. The remote program
+is already running, so you can use commands like @kbd{step} and
+@kbd{continue}. In @kbd{target remote} mode the @kbd{run} command is
+not supported.
+
+@subsection Connecting in @kbd{target extended-remote} mode
+@cindex @code{gdbserver}, extended-remote mode
+@cindex @code{gdbserver}, exit
+
+When you connect to @code{gdbserver} using @kbd{target remote},
+@code{gdbserver} debugs the specified program only once. When the
+program exits, or you detach from it, @value{GDBN} closes the connection
+and @code{gdbserver} exits.
+
+If you connect using @kbd{target extended-remote}, @code{gdbserver}
+enters extended mode. When the debugged program exits, or you
+detach from it, @value{GDBN} stays connected to @code{gdbserver} even
+though no program is running. The @code{run} and @code{attach}
+commands instruct @code{gdbserver} to run or attach to a new program.
+The @code{run} command uses the value set by @code{set remote exec-file}
+(@pxref{set remote exec-file}) to select the program to run. Command line
+arguments are supported, except for wildcard expansion and I/O
+redirection (@pxref{Arguments}).
+
+@cindex @option{--multi}, @code{gdbserver} option
+To start @code{gdbserver} without supplying an initial command to run
+or process ID to attach, use the @option{--multi} command line option.
+Then you can connect using @kbd{target extended-remote} and start
+the program you want to debug.
+
+In extended mode @code{gdbserver} does not automatically exit unless you
+use the option @option{--once}. You can terminate it by using
+@code{monitor exit} (@pxref{Monitor Commands for gdbserver}). Note that the
+conditions under which @code{gdbserver} terminates depend on how @value{GDBN}
+connects to it (@kbd{target remote} or @kbd{target extended-remote}). The
+@option{--multi} option to @code{gdbserver} has no influence on that.
+
+@subsection Host and target files
+
+@value{GDBN}, running on the host, needs access to symbol and debugging
+information for your program running on the target. This requires
+access to an unstripped copy of your program, and possibly any associated
+symbol files.
+
+Some remote targets (@pxref{qXfer executable filename read}, and
+@pxref{Host I/O Packets}) allow @value{GDBN} to access program files over
+the same connection used to communicate with @value{GDBN}. With such a
+target, if the remote program is unstripped, the only command you need is
+@kbd{target remote} (or @kbd{target extended-remote}).
+
+If the remote program is stripped, or the target does not support remote
+program file access, start up @value{GDBN} using the name of the local
unstripped copy of your program as the first argument, or use the
-@code{file} command.
+@code{file} command. Use @code{set sysroot} to specify the location (on
+the host) of target libraries (unless your @value{GDBN} was compiled with
+the correct sysroot using @code{--with-sysroot}). Alternatively, you
+may use @code{set solib-search-path} to specify how @value{GDBN} locates
+target libraries.
+
+The symbol file and target libraries must exactly match the executable
+and libraries on the target, with one exception: the files on the host
+system should not be stripped, even if the files on the target system
+are. Mismatched or missing files will lead to confusing results
+during debugging. On @sc{gnu}/Linux targets, mismatched or missing
+files may also prevent @code{gdbserver} from debugging multi-threaded
+programs.
+
+@subsection Steps for connecting to a remote target
+
+The basic procedure for connecting to the remote target is:
+
+@itemize @bullet
+@item
+First, run @value{GDBN} on the host system.
+
+@item
+Next, specify the how @value{GDBN} finds symbol files
+(@pxref{Connecting,,Host and target files}).
+
+@item
+Finally, connect to your target. For TCP connections, you must start up
+@code{gdbserver} prior to using the @kbd{target remote} or
+@kbd{target extended-remote} command. Otherwise you may get an error
+whose text depends on the host system, but which usually looks something
+like @samp{Connection refused}. Don't use the @code{load} command in
+@value{GDBN} when using @code{gdbserver}, since the program is already on
+the target.
+
+@end itemize
+
+@subsection Remote connection commands
-@cindex @code{target remote}
+@cindex @kbd{target remote}
+@cindex @kbd{target extended-remote}
@value{GDBN} can communicate with the target over a serial line, or
over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In
each case, @value{GDBN} uses the same protocol for debugging your
program; only the medium carrying the debugging packets varies. The
-@code{target remote} command establishes a connection to the target.
-Its arguments indicate which medium to use:
+@kbd{target remote} and @kbd{target extended-remote} commands establish
+a connection to the target. Their arguments indicate which medium to use:
@table @code
@item target remote @var{serial-device}
-@cindex serial line, @code{target remote}
+@item target extended-remote @var{serial-device}
+@cindex serial line, @kbd{target remote}
Use @var{serial-device} to communicate with the target. For example,
to use a serial line connected to the device named @file{/dev/ttyb}:
@@ -19253,11 +19357,13 @@ target remote /dev/ttyb
If you're using a serial line, you may want to give @value{GDBN} the
@samp{--baud} option, or use the @code{set serial baud} command
(@pxref{Remote Configuration, set serial baud}) before the
-@code{target} command.
+@kbd{target} command.
@item target remote @code{@var{host}:@var{port}}
@itemx target remote @code{tcp:@var{host}:@var{port}}
-@cindex @acronym{TCP} port, @code{target remote}
+@item target extended-remote @code{@var{host}:@var{port}}
+@itemx target extended-remote @code{tcp:@var{host}:@var{port}}
+@cindex @acronym{TCP} port, @kbd{target remote}
Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
The @var{host} may be either a host name or a numeric @acronym{IP}
address; @var{port} must be a decimal number. The @var{host} could be
@@ -19285,7 +19391,8 @@ target remote :1234
Note that the colon is still required here.
@item target remote @code{udp:@var{host}:@var{port}}
-@cindex @acronym{UDP} port, @code{target remote}
+@item target extended-remote @code{udp:@var{host}:@var{port}}
+@cindex @acronym{UDP} port, @kbd{target remote}
Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
@@ -19299,7 +19406,8 @@ can silently drop packets on busy or unreliable networks, which will
cause havoc with your debugging session.
@item target remote | @var{command}
-@cindex pipe, @code{target remote} to
+@item target extended-remote | @var{command}
+@cindex pipe, @kbd{target remote} to
Run @var{command} in the background and communicate with it using a
pipe. The @var{command} is a shell command, to be parsed and expanded
by the system's command shell, @code{/bin/sh}; it should expect remote
@@ -19314,11 +19422,6 @@ program has already exited, this will have no effect.)
@end table
-Once the connection has been established, you can use all the usual
-commands to examine and change data. The remote program is already
-running; you can use @kbd{step} and @kbd{continue}, and you do not
-need to use @kbd{run}.
-
@cindex interrupting remote programs
@cindex remote programs, interrupting
Whenever @value{GDBN} is waiting for the remote program, if you type the
@@ -19333,7 +19436,7 @@ Give up (and stop debugging it)? (y or n)
@end smallexample
If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
-(If you decide you want to try again later, you can use @samp{target
+(If you decide you want to try again later, you can use @kbd{target
remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
goes back to waiting.
@@ -19433,7 +19536,7 @@ target system with the same privileges as the user running
@code{gdbserver}.
@end quotation
-@subsection Running @code{gdbserver}
+@subsection Running gdbserver
@cindex arguments, to @code{gdbserver}
@cindex @code{gdbserver}, command-line arguments
@@ -19526,38 +19629,6 @@ In case more than one copy of @var{program} is running, or @var{program}
has multiple threads, most versions of @code{pidof} support the
@code{-s} option to only return the first process ID.
-@subsubsection Multi-Process Mode for @code{gdbserver}
-@cindex @code{gdbserver}, multiple processes
-@cindex multiple processes with @code{gdbserver}
-
-When you connect to @code{gdbserver} using @code{target remote},
-@code{gdbserver} debugs the specified program only once. When the
-program exits, or you detach from it, @value{GDBN} closes the connection
-and @code{gdbserver} exits.
-
-If you connect using @kbd{target extended-remote}, @code{gdbserver}
-enters multi-process mode. When the debugged program exits, or you
-detach from it, @value{GDBN} stays connected to @code{gdbserver} even
-though no program is running. The @code{run} and @code{attach}
-commands instruct @code{gdbserver} to run or attach to a new program.
-The @code{run} command uses @code{set remote exec-file} (@pxref{set
-remote exec-file}) to select the program to run. Command line
-arguments are supported, except for wildcard expansion and I/O
-redirection (@pxref{Arguments}).
-
-@cindex @option{--multi}, @code{gdbserver} option
-To start @code{gdbserver} without supplying an initial command to run
-or process ID to attach, use the @option{--multi} command line option.
-Then you can connect using @kbd{target extended-remote} and start
-the program you want to debug.
-
-In multi-process mode @code{gdbserver} does not automatically exit unless you
-use the option @option{--once}. You can terminate it by using
-@code{monitor exit} (@pxref{Monitor Commands for gdbserver}). Note that the
-conditions under which @code{gdbserver} terminates depend on how @value{GDBN}
-connects to it (@kbd{target remote} or @kbd{target extended-remote}). The
-@option{--multi} option to @code{gdbserver} has no influence on that.
-
@subsubsection TCP port allocation lifecycle of @code{gdbserver}
This section applies only when @code{gdbserver} is run to listen on a TCP port.
@@ -19640,31 +19711,6 @@ environment:
$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
@end smallexample
-@subsection Connecting to @code{gdbserver}
-
-Run @value{GDBN} on the host system.
-
-First make sure you have the necessary symbol files. Load symbols for
-your application using the @code{file} command before you connect. Use
-@code{set sysroot} to locate target libraries (unless your @value{GDBN}
-was compiled with the correct sysroot using @code{--with-sysroot}).
-
-The symbol file and target libraries must exactly match the executable
-and libraries on the target, with one exception: the files on the host
-system should not be stripped, even if the files on the target system
-are. Mismatched or missing files will lead to confusing results
-during debugging. On @sc{gnu}/Linux targets, mismatched or missing
-files may also prevent @code{gdbserver} from debugging multi-threaded
-programs.
-
-Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}).
-For TCP connections, you must start up @code{gdbserver} prior to using
-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}. Don't use the @code{load}
-command in @value{GDBN} when using @code{gdbserver}, since the program is
-already on the target.
-
@subsection Monitor Commands for @code{gdbserver}
@cindex monitor commands, for @code{gdbserver}
@anchor{Monitor Commands for gdbserver}
--
1.8.1.1