Re: [RFA 01/08] multi-process support: struct inferior (alternate manual content)

[Stan Shebs <stan@codesourcery.com>]

[-- Attachment #1: Type: text/plain, Size: 510 bytes --]

Here is an alternate phrasing for GDB's new inferior objects, 
wordsmithed so that it (mostly) makes sense with just Pedro's patches, 
and also so that it can be easily expanded into the full multi-exec 
section in the near future. To repeat from my last comment, I don't 
think we need to be really polished just yet, the single-exec + 
multi-inferior case is just a transitional stage of limited interest.

Stan

2008-09-16  Stan Shebs  <stan@codesourcery.com>

    * gdb.texinfo (Inferiors): New section.



[-- Attachment #2: manual-inf-patch-1 --]
[-- Type: text/plain, Size: 3045 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.521
diff -p -r1.521 gdb.texinfo
*** gdb.texinfo	3 Sep 2008 23:54:19 -0000	1.521
--- gdb.texinfo	17 Sep 2008 00:25:23 -0000
*************** kill a child process.
*** 1785,1790 ****
--- 1785,1791 ----
  * Attach::                      Debugging an already-running process
  * Kill Process::                Killing the child process
  
+ * Inferiors::                   Debugging multiple inferiors
  * Threads::                     Debugging programs with multiple threads
  * Processes::                   Debugging programs with multiple processes
  * Checkpoint/Restart::          Setting a @emph{bookmark} to return to later
*************** next type @code{run}, @value{GDBN} notic
*** 2354,2359 ****
--- 2355,2406 ----
  reads the symbol table again (while trying to preserve your current
  breakpoint settings).
  
+ @node Inferiors
+ @section Debugging Multiple Inferiors
+ 
+ Some @value{GDBN} targets are able to run multiple processes created
+ from a single executable. This can happen, for instance, with an
+ embedded system reporting back several processes via the remote
+ protocol.
+ 
+ @cindex inferior
+ @value{GDBN} represents the state of each program execution with an
+ object called an @dfn{inferior}. An inferior typically corresponds to a
+ process, but is more general and applies also to targets that do not
+ have processes. Inferiors may be created before a process runs, and
+ may (in future) be retained after a process exits. Each run of an
+ executable creates a new inferior, as does each attachment to an
+ existing process. Inferiors have unique identifiers that are different
+ from process ids, and may optionally be named as well. Usually each
+ inferior will also have its own distinct address space, although some
+ embedded targets may have several inferiors running in different parts
+ of a single space.
+ 
+ Each inferior may in turn have multiple threads running in it.
+ 
+ To find out what inferiors exist at any moment, use @code{info inferiors}:
+ 
+ @table @code
+ @kindex info inferiors
+ @item info inferiors
+ Print a list of all inferiors currently being managed by @value{GDBN}.
+ 
+ @kindex set print inferior-events
+ @cindex print messages on inferior start and exit
+ @item set print inferior-events
+ @itemx set print inferior-events on
+ @itemx set print inferior-events off
+ The @code{set print inferior-events} command allows you to enable or
+ disable printing of messages when @value{GDBN} notices that new
+ inferiors have started or that inferiors have exited or have been
+ detached.  By default, these messages will not be printed.
+ 
+ @kindex show print inferior-events
+ @item show print inferior-events
+ Show whether messages will be printed when @value{GDBN} detects that
+ inferiors have started, exited or have been detached.
+ @end table
+ 
  @node Threads
  @section Debugging Programs with Multiple Threads