Target remote mode fork and exec event documentation

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.

gdb/ChangeLog:

	* NEWS: Announce fork and exec event support for target remote.

gdb/doc/ChangeLog:

	* 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.
	(Server): Note effects of target extended-remote mode.
	Delete section on Multi-Process Mode for gdbserver.
	Move some text to "Connecting" node.
This commit is contained in:
Don Breazeal 2015-12-14 11:18:06 -08:00
parent 8020350c52
commit 19d9d4efd1
4 changed files with 213 additions and 77 deletions

View file

@ -1,3 +1,7 @@
2015-12-11 Don Breazeal <donb@codesourcery.com>
* NEWS: Announce fork and exec event support for target remote.
2015-12-11 Don Breazeal <donb@codesourcery.com>
* inferior.c (number_of_live_inferiors): New function.

View file

@ -135,6 +135,13 @@ show remote exec-event-feature-packet
The reply to qXfer:threads:read may now include a name attribute for each
thread.
* 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, follow-exec-mode, and
fork and exec catchpoints.
* MI changes
** The -var-set-format command now accepts the zero-hexadecimal

View file

@ -1,3 +1,16 @@
2015-12-11 Don Breazeal <donb@codesourcery.com>
* 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.
(Server): Note effects of target extended-remote mode.
Delete section on Multi-Process Mode for gdbserver.
Move some text to "Connecting" node.
2015-12-10 Pedro Alves <palves@redhat.com>
* gdb.texinfo (Threads): Replace warning with explanation

View file

@ -3119,10 +3119,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. On @sc{gnu}/Linux platforms, this feature is supported
with kernel version 2.5.60 and later.
with 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 @code{target remote} mode or
@code{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.
@ -3268,6 +3269,9 @@ Program exited normally.
@end table
@end table
@code{follow-exec-mode} is supported in native mode and
@code{target extended-remote} 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}.
@ -19248,28 +19252,148 @@ configuration of @value{GDBN}; use @code{help target} to list them.
@node Connecting
@section Connecting to a Remote Target
@cindex remote debugging, connecting
@cindex @code{gdbserver}, connecting
@cindex remote debugging, types of connections
@cindex @code{gdbserver}, types of connections
@cindex @code{gdbserver}, @code{target remote} mode
@cindex @code{gdbserver}, @code{target extended-remote} mode
@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
This section describes how to connect to a remote target, including the
types of connections and their differences, how to set up executable and
symbol files on the host and target, and the commands used for
connecting to and disconnecting from the remote target.
@subsection Types of Remote Connections
@value{GDBN} supports two types of remote connections, @code{target remote}
mode and @code{target extended-remote} mode. Note that many remote targets
support only @code{target remote} mode. There are several major
differences between the two types of connections, enumerated here:
@table @asis
@cindex remote debugging, detach and program exit
@item Result of detach or program exit
@strong{With target remote mode:} When the debugged program exits or you
detach from it, @value{GDBN} disconnects from the target. When using
@code{gdbserver}, @code{gdbserver} will exit.
@strong{With target extended-remote mode:} When the debugged program exits or
you detach from it, @value{GDBN} remains connected to the target, even
though no program is running. You can rerun the program, attach to a
running program, or use @code{monitor} commands specific to the target.
When using @code{gdbserver} in this case, it does not exit unless it was
invoked using the @option{--once} option. If the @option{--once} option
was not used, you can ask @code{gdbserver} to exit using the
@code{monitor exit} command (@pxref{Monitor Commands for gdbserver}).
@item Specifying the program to debug
For both connection types you use the @code{file} command to specify the
program on the host system. If you are using @code{gdbserver} there are
some differences in how to specify the location of the program on the
target.
@strong{With target remote mode:} You must either specify the program to debug
on the @code{gdbserver} command line or use the @option{--attach} option
(@pxref{Attaching to a program,,Attaching to a Running Program}).
@cindex @option{--multi}, @code{gdbserver} option
@strong{With target extended-remote mode:} You may specify the program to debug
on the @code{gdbserver} command line, or you can load the program or attach
to it using @value{GDBN} commands after connecting to @code{gdbserver}.
@anchor{--multi Option in Types of Remote Connnections}
You can start @code{gdbserver} without supplying an initial command to run
or process ID to attach. To do this, use the @option{--multi} command line
option. Then you can connect using @code{target extended-remote} and start
the program you want to debug (see below for details on using the
@code{run} command in this scenario). Note that the conditions under which
@code{gdbserver} terminates depend on how @value{GDBN} connects to it
(@code{target remote} or @code{target extended-remote}). The
@option{--multi} option to @code{gdbserver} has no influence on that.
@item The @code{run} command
@strong{With target remote mode:} The @code{run} command is not
supported. Once a 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}.
@strong{With target extended-remote mode:} The @code{run} command is
supported. 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}).
If you specify the program to debug on the command line, then the
@code{run} command is not required to start execution, and you can
resume using commands like @kbd{step} and @kbd{continue} as with
@code{target remote} mode.
@anchor{Attaching in Types of Remote Connections}
@item Attaching
@strong{With target remote mode:} The @value{GDBN} command @code{attach} is
not supported. To attach to a running program using @code{gdbserver}, you
must use the @option{--attach} option (@pxref{Running gdbserver}).
@strong{With target extended-remote mode:} To attach to a running program,
you may use the @code{attach} command after the connection has been
established. If you are using @code{gdbserver}, you may also invoke
@code{gdbserver} using the @option{--attach} option
(@pxref{Running gdbserver}).
@end table
@anchor{Host and target files}
@subsection Host and Target Files
@cindex remote debugging, symbol files
@cindex symbol files, remote debugging
@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. Note that this section applies equally to both @code{target
remote} mode and @code{target extended-remote} mode.
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} (or @code{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.
@cindex @code{target remote}
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 Remote Connection Commands
@cindex remote connection commands
@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:
@code{target remote} and @code{target extended-remote} commands
establish a connection to the target. Both commands accept the same
arguments, which indicate the medium to use:
@table @code
@item target remote @var{serial-device}
@itemx target extended-remote @var{serial-device}
@cindex serial line, @code{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}:
@ -19285,6 +19409,8 @@ If you're using a serial line, you may want to give @value{GDBN} the
@item target remote @code{@var{host}:@var{port}}
@itemx target remote @code{tcp:@var{host}:@var{port}}
@itemx target extended-remote @code{@var{host}:@var{port}}
@itemx target extended-remote @code{tcp:@var{host}:@var{port}}
@cindex @acronym{TCP} port, @code{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}
@ -19313,6 +19439,7 @@ target remote :1234
Note that the colon is still required here.
@item target remote @code{udp:@var{host}:@var{port}}
@itemx target extended-remote @code{udp:@var{host}:@var{port}}
@cindex @acronym{UDP} port, @code{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}:
@ -19327,6 +19454,7 @@ can silently drop packets on busy or unreliable networks, which will
cause havoc with your debugging session.
@item target remote | @var{command}
@itemx target extended-remote | @var{command}
@cindex pipe, @code{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
@ -19342,11 +19470,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
@ -19360,10 +19483,13 @@ Interrupted while waiting for the program.
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
remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
goes back to waiting.
In @code{target remote} mode, if you type @kbd{y}, @value{GDBN} abandons
the remote debugging session. (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.
In @code{target extended-remote} mode, typing @kbd{n} will leave
@value{GDBN} connected to the target.
@table @code
@kindex detach (remote)
@ -19372,11 +19498,13 @@ When you have finished debugging the remote program, you can use the
@code{detach} command to release it from @value{GDBN} control.
Detaching from the target normally resumes its execution, but the results
will depend on your particular remote stub. After the @code{detach}
command, @value{GDBN} is free to connect to another target.
command in @code{target remote} mode, @value{GDBN} is free to connect to
another target. In @code{target extended-remote} mode, @value{GDBN} is
still connected to the target.
@kindex disconnect
@item disconnect
The @code{disconnect} command behaves like @code{detach}, except that
The @code{disconnect} command closes the connection to the target, and
the target is generally not resumed. It will wait for @value{GDBN}
(this instance or another one) to connect and continue debugging. After
the @code{disconnect} command, @value{GDBN} is again free to connect to
@ -19433,7 +19561,8 @@ Delete @var{targetfile} from the target system.
@cindex remote connection without stubs
@code{gdbserver} is a control program for Unix-like systems, which
allows you to connect your program with a remote @value{GDBN} via
@code{target remote}---but without linking in the usual debugging stub.
@code{target remote} or @code{target extended-remote}---but without
linking in the usual debugging stub.
@code{gdbserver} is not a complete replacement for the debugging stubs,
because it requires essentially the same operating-system facilities
@ -19461,6 +19590,7 @@ target system with the same privileges as the user running
@code{gdbserver}.
@end quotation
@anchor{Running gdbserver}
@subsection Running @code{gdbserver}
@cindex arguments, to @code{gdbserver}
@cindex @code{gdbserver}, command-line arguments
@ -19528,6 +19658,7 @@ Programs started with stdio-connected gdbserver have @file{/dev/null} for
display through a pipe connected to gdbserver.
Both @code{stdout} and @code{stderr} use the same pipe.
@anchor{Attaching to a program}
@subsubsection Attaching to a Running Program
@cindex attach to a program, @code{gdbserver}
@cindex @option{--attach}, @code{gdbserver} option
@ -19539,8 +19670,12 @@ This is accomplished via the @code{--attach} argument. The syntax is:
target> gdbserver --attach @var{comm} @var{pid}
@end smallexample
@var{pid} is the process ID of a currently running process. It isn't necessary
to point @code{gdbserver} at a binary for the running process.
@var{pid} is the process ID of a currently running process. It isn't
necessary to point @code{gdbserver} at a binary for the running process.
In @code{target extended-remote} mode, you can also attach using the
@value{GDBN} attach command
(@pxref{Attaching in Types of Remote Connections}).
@pindex pidof
You can debug processes by name instead of process ID if your target has the
@ -19554,41 +19689,10 @@ 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.
This section applies only when @code{gdbserver} is run to listen on a TCP
port.
@code{gdbserver} normally terminates after all of its debugged processes have
terminated in @kbd{target remote} mode. On the other hand, for @kbd{target
@ -19619,6 +19723,12 @@ instance closes its port after the first connection.
@anchor{Other Command-Line Arguments for gdbserver}
@subsubsection Other Command-Line Arguments for @code{gdbserver}
You can use the @option{--multi} option to start @code{gdbserver} without
specifying a program to debug or a process to attach to. Then you can
attach in @code{target extended-remote} mode and run or attach to a
program. For more information,
@pxref{--multi Option in Types of Remote Connnections}.
@cindex @option{--debug}, @code{gdbserver} option
The @option{--debug} option tells @code{gdbserver} to display extra
status information about the debugging process.
@ -19670,32 +19780,34 @@ $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
@subsection Connecting to @code{gdbserver}
The basic procedure for connecting to the remote target is:
@itemize
@item
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.
@item
Make sure you have the necessary symbol files
(@pxref{Host and target 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}).
@item
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
the @code{target} 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.
command in @value{GDBN} when using @code{target remote} mode, since the
program is already on the target.
@end itemize
@anchor{Monitor Commands for gdbserver}
@subsection Monitor Commands for @code{gdbserver}
@cindex monitor commands, for @code{gdbserver}
@anchor{Monitor Commands for gdbserver}
During a @value{GDBN} session using @code{gdbserver}, you can use the
@code{monitor} command to send special requests to @code{gdbserver}.