Re: Move the multi-forks support to the generic multi-inferiors support.

[Pedro Alves <pedro at codesourcery dot com>]

On Wednesday 01 July 2009 20:15:51, Eli Zaretskii wrote:
> > From: Pedro Alves <pedro@codesourcery.com>

> > +from it by using the @w{@code{detach inferior}} command (allowing it
> > +to run independently), or kill it using the @w{@code{kill inferior}}
> > +command.  Again, @pxref{Inferiors, ,Debugging Multiple Inferiors}.
> 
> @pxref is inappropriate here, since it is designed to be used inside
> parentheses.  You want "see @ref" instead.
> 
> And I would lose the "Again" part (in which case you can simply use
> @xref).

Thanks.  I've read about @ref vs @xref vs @pxref now.  Always
learning.

> > +info inferiors
> > +  List the inferiors currently under GDB's control.
> > +
> > +inferior NUM
> > +  Switch focus to inferior number NUM.
> > +
> > +detach inferior NUM
> > +  Detach from inferior number NUM.
> > +
> > +kill inferior NUM
> > +  Kill inferior number NUM.
> 
> I think this deserves a short intro, like one or two sentences saying
> something about multi-inferior debugging.

Okay.  Let me know what you think of the new hunks (gdb.texinfo and NEWS)
below.

> > +process PID
> > +  Removed.
> 
> Perhaps say something about replacement command(s), or why none is
> needed.

Indeed.  Sorry I had to make you point at that.  :-)

-- 
Pedro Alves

Index: src/gdb/doc/gdb.texinfo
===================================================================
--- src.orig/gdb/doc/gdb.texinfo	2009-07-01 19:15:40.000000000 +0100
+++ src/gdb/doc/gdb.texinfo	2009-07-02 14:40:05.000000000 +0100
@@ -2374,7 +2374,39 @@ To find out what inferiors exist at any 
 @kindex info inferiors
 @item info inferiors
 Print a list of all inferiors currently being managed by @value{GDBN}.
+@end table
+
+To switch focus between inferiors, use the @code{inferior} command:
+
+@table @code
+@kindex inferior @var{inferior-id}
+@item inferior @var{inferior-id}
+Make inferior number @var{inferior-id} the current inferior.  The
+argument @var{inferior-id} is the internal inferior number assigned by
+@value{GDBN}, as shown in the first field of the @samp{info inferiors}
+display.
+@end table
+
+To quit debugging one of the inferiors, you can either detach from it
+by using the @w{@code{detach inferior}} command (allowing it to run
+independently), or kill it using the @w{@code{kill inferior}} command:
+
+@table @code
+@kindex detach inferior @var{inferior-id}
+@item detach inferior @var{inferior-id}
+Detach from the inferior identified by @value{GDBN} inferior number
+@var{inferior-id}, and remove it from the inferior list.
+
+@kindex kill inferior @var{inferior-id}
+@item kill inferior @var{inferior-id}
+Kill the inferior identified by @value{GDBN} inferior number
+@var{inferior-id}, and remove it from the inferior list.
+@end table
+
+To be notified when inferiors are started or exit under @value{GDBN}'s
+control use @w{@code{set print inferior-events}}:
 
+@table @code
 @kindex set print inferior-events
 @cindex print messages on inferior start and exit
 @item set print inferior-events
@@ -2758,51 +2790,17 @@ is held suspended.  
 Show whether detach-on-fork mode is on/off.
 @end table
 
-If you choose to set @samp{detach-on-fork} mode off, then
-@value{GDBN} will retain control of all forked processes (including
-nested forks).  You can list the forked processes under the control of
-@value{GDBN} by using the @w{@code{info forks}} command, and switch
-from one fork to another by using the @w{@code{fork}} command.
-
-@table @code
-@kindex info forks
-@item info forks
-Print a list of all forked processes under the control of @value{GDBN}.
-The listing will include a fork id, a process id, and the current 
-position (program counter) of the process.
-
-@kindex fork @var{fork-id}
-@item fork @var{fork-id}
-Make fork number @var{fork-id} the current process.  The argument
-@var{fork-id} is the internal fork number assigned by @value{GDBN},
-as shown in the first field of the @samp{info forks} display.
-
-@kindex process @var{process-id}
-@item process @var{process-id}
-Make process number @var{process-id} the current process.  The
-argument @var{process-id} must be one that is listed in the output of
-@samp{info forks}.
-
-@end table
+If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN}
+will retain control of all forked processes (including nested forks).
+You can list the forked processes under the control of @value{GDBN} by
+using the @w{@code{info inferiors}} command, and switch from one fork
+to another by using the @code{inferior} command (@pxref{Inferiors,
+,Debugging Multiple Inferiors}).
 
 To quit debugging one of the forked processes, you can either detach
-from it by using the @w{@code{detach fork}} command (allowing it to
-run independently), or delete (and kill) it using the
-@w{@code{delete fork}} command.
-
-@table @code
-@kindex detach fork @var{fork-id}
-@item detach fork @var{fork-id}
-Detach from the process identified by @value{GDBN} fork number
-@var{fork-id}, and remove it from the fork list.  The process will be
-allowed to run independently.
-
-@kindex delete fork @var{fork-id}
-@item delete fork @var{fork-id}
-Kill the process identified by @value{GDBN} fork number @var{fork-id},
-and remove it from the fork list.
-
-@end table
+from it by using the @w{@code{detach inferior}} command (allowing it
+to run independently), or kill it using the @w{@code{kill inferior}}
+command.  @xref{Inferiors, ,Debugging Multiple Inferiors}.
 
 If you ask to debug a child process and a @code{vfork} is followed by an
 @code{exec}, @value{GDBN} executes the new target up to the first
@@ -2810,8 +2808,8 @@ breakpoint in the new target.  If you ha
 @code{main} in your original program, the breakpoint will also be set on
 the child process's @code{main}.
 
-When a child process is spawned by @code{vfork}, you cannot debug the
-child or parent until an @code{exec} call completes.
+On some systems, when a child process is spawned by @code{vfork}, you
+cannot debug the child or parent until an @code{exec} call completes.
 
 If you issue a @code{run} command to @value{GDBN} after an @code{exec}
 call executes, the new target restarts.  To restart the parent process,
Index: src/gdb/NEWS
===================================================================
--- src.orig/gdb/NEWS	2009-07-01 19:16:33.000000000 +0100
+++ src/gdb/NEWS	2009-07-02 15:31:35.000000000 +0100
@@ -175,6 +175,16 @@ GDB will now correctly handle all of:
 * Support for user-defined prefixed commands.  The "define" command can
 add new commands to existing prefixes, e.g. "target".
 
+* Multi-inferior, multi-process debugging.
+
+  GDB now has generalized support for multi-inferior debugging.  See
+  "Debugging Multiple Inferiors" in the manual for more information.
+  Although support availability still depends on target support, the
+  command set has been uniformalised.  The GNU/Linux specific
+  multi-forks support has been migrated to this new framework.  This
+  implied some user visible changes; see "New commands" and also
+  "Removed commands" below.
+
 * New commands (for set/show, see "New options" below)
 
 find [/size-char] [/max-count] start-address, end-address|+search-space-size,
@@ -197,6 +207,18 @@ macro undef
 info os processes
   Show operating system information about processes.
 
+info inferiors
+  List the inferiors currently under GDB's control.
+
+inferior NUM
+  Switch focus to inferior number NUM.
+
+detach inferior NUM
+  Detach from inferior number NUM.
+
+kill inferior NUM
+  Kill inferior number NUM.
+
 * New options
 
 set sh calling-convention
@@ -320,6 +342,36 @@ show schedule-multiple
   Allow GDB to resume all threads of all processes or only threads of
   the current process.
 
+* Removed commands
+
+info forks
+  For program forks, this is replaced by the new more generic `info
+  inferiors' command.  To list checkpoints, you can still use the
+  `info checkpoints' command, which was an alias for the `info forks'
+  command.
+
+fork NUM
+  Replaced by the new `inferior' command.  To switch between
+  checkpoints, you can still use the `restart' command, which was an
+  alias for the `fork' command.
+
+process PID
+  This is removed, since some targets don't have a notion of
+  processes.  To switch between processes, you can still use the
+  `inferior' command using GDB's own inferior number.
+
+delete fork NUM
+  For program forks, this is replaced by the new more generic `kill
+  inferior' command.  To delete a checkpoint, you can still use the
+  `delete checkpoint' command, which was an alias for the `delete
+  fork' command.
+
+detach fork NUM
+  For program forks, this is replaced by the new more generic `detach
+  inferior' command.  To detach a checkpoint, you can still use the
+  `detach checkpoint' command, which was an alias for the `detach
+  fork' command.
+
 * New native configurations
 
 x86/x86_64 Darwin		i[34567]86-*-darwin*