merge 8.7

1 files changed, 59 insertions, 40 deletions

diff --git a/doc/process.n b/doc/process.n
index fbe307b..165e413 100644
--- a/doc/process.n
+++ b/doc/process.n
@@ -16,75 +16,81 @@ tcl::process \- Subprocess management
 .SH DESCRIPTION
 .PP
 This command provides a way to manage subprocesses created by the \fBopen\fR
-and \fBexec\fR commands. The legal \fIoptions\fR (which may be abbreviated) are:
+and \fBexec\fR commands, as identified by the process identifiers (PIDs) of
+those subprocesses. The legal \fIoptions\fR (which may be abbreviated) are:
+.TP
+\fB::tcl::process autopurge\fR ?\fIflag\fR?
+.
+Automatic purge facility. If \fIflag\fR is specified as a boolean value then
+it activates or deactivate autopurge. In all cases it returns the current
+status as a boolean value. When autopurge is active,
+\fBTcl_ReapDetachedProcs\fR is called each time the \fBexec\fR command is
+executed or a pipe channel created by \fBopen\fR is closed. When autopurge is
+inactive, \fB::tcl::process\fR purge must be called explicitly. By default
+autopurge is active.
 .TP
 \fB::tcl::process list\fR
 .
-Returns the list of subprocess PIDs.
+Returns the list of subprocess PIDs. This includes all currently executing
+subprocesses and all terminated subprocesses that have not yet had their
+corresponding process table entries purged.
+.TP
+\fB::tcl::process purge\fR ?\fIpids\fR?
+.
+Cleans up all data associated with terminated subprocesses. If \fIpids\fR is
+specified as a list of PIDs then the command only cleanup data for the matching
+subprocesses if they exist, and raises an error otherwise. If a process listed is
+still active, this command does nothing to that process.
 .TP
 \fB::tcl::process status\fR ?\fIswitches\fR? ?\fIpids\fR?
 .
-Returns a dictionary mapping subprocess PIDs to their respective status. If 
-\fIpids\fR is specified as a list of PIDs then the command only returns the 
-status of the matching subprocesses if they exist, and raises an error 
+Returns a dictionary mapping subprocess PIDs to their respective status. If
+\fIpids\fR is specified as a list of PIDs then the command only returns the
+status of the matching subprocesses if they exist, and raises an error
 otherwise. For active processes, the status is an empty value. For terminated
-processes, the status is a list with the following format: 
-.QW "{code ?\fImsg errorCode\fR?}" ,
+processes, the status is a list with the following format:
+.QW "\fB{\fIcode\fR ?\fImsg errorCode\fR?\fB}\fR" ,
 where:
 .RS
 .TP
-\fBcode\fR\0
+\fIcode\fR\0
 .
-is a standard Tcl return code,
+is a standard Tcl return code, i.e., \fB0\fR for TCL_OK and \fB1\fR
+for TCL_ERROR,
 .TP
-\fBmsg\fR\0
+\fImsg\fR\0
 .
 is the human-readable error message,
 .TP
-\fBerrorCode\fR\0
+\fIerrorCode\fR\0
 .
 uses the same format as the \fBerrorCode\fR global variable
-.RE
-Note that \fBmsg\fR and \fBerrorCode\fR are only present for abnormally 
-terminated processes (i.e. those where \fBcode\fR is nonzero). Under the hood
-this command calls \fBTcl_WaitPid\fR with the \fBWNOHANG\fR flag set for
+.PP
+Note that \fBmsg\fR and \fBerrorCode\fR are only present for abnormally
+terminated processes (i.e. those where the \fIcode\fR is nonzero). Under the
+hood this command calls \fBTcl_WaitPid\fR with the \fBWNOHANG\fR flag set for
 non-blocking behavior, unless the \fB\-wait\fR switch is set (see below).
-.RS
 .PP
 Additionally, \fB::tcl::process status\fR accepts the following switches:
 .TP
 \fB\-wait\fR\0
 .
 By default the command returns immediately (the underlying \fBTcl_WaitPid\fR is
-called with the \fBWNOHANG\fR flag set) unless this switch is set. If \fBpids\fR
+called with the \fBWNOHANG\fR flag set) unless this switch is set. If \fIpids\fR
 is specified as a list of PIDs then the command waits until the status of the
-matching subprocesses are available. If \fBpids\fR is not specified then it
-waits for all known subprocesses.
+matching subprocesses are available. If \fIpids\fR was not specified, this
+command will wait for all known subprocesses.
 .TP
 \fB\-\|\-\fR
 .
 Marks the end of switches.  The argument following this one will
 be treated as the first \fIarg\fR even if it starts with a \fB\-\fR.
 .RE
-.TP
-\fB::tcl::process purge ?\fIpids\fR?
-.
-Cleans up all data associated with terminated subprocesses. If \fBpids\fR is
-specified as a list of PIDs then the command only cleanup data for the matching
-subprocesses if they exist, and raises an error otherwise. If the process is
-still active then it does nothing.
-.TP
-\fB::tcl::process autopurge ?\fIflag\fR?
-.
-Automatic purge facility. If \fBflag\fR is specified as a boolean value then it
-activates or deactivate autopurge. In all cases it returns the current status as
-a boolean value. When autopurge is active, \fBTcl_ReapDetachedProcs\fR is called
-each time the exec command is executed or a pipe channel created by open is
-closed. When autopurge is inactive, \fB::tcl::process\fR purge must be called
-explicitly. By default autopurge is active.
-.RE
 .SH "EXAMPLES"
 .PP
+These show the use of \fB::tcl::process\fR. Some of the results from
+\fB::tcl::process status\fR are split over multiple lines for readability.
+.PP
 .CS
 \fB::tcl::process autopurge\fR
      \fI\(-> true\fR
@@ -102,7 +108,12 @@ set pid2 [pid $chan]
      \fI\(-> 123 456 789 1011\fR
 
 \fB::tcl::process status\fR
-     \fI\(-> 123 0 456 {1 "child killed: write on pipe with no readers" {CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}} 789 {1 "child suspended: background tty read" {CHILDSUSP 789 SIGTTIN "background tty read"}} 1011 {}\fR
+     \fI\(-> 123 0
+       456 {1 "child killed: write on pipe with no readers" {
+         CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}}
+       789 {1 "child suspended: background tty read" {
+         CHILDSUSP 789 SIGTTIN "background tty read"}}
+       1011 {}\fR
 
 \fB::tcl::process status\fR 123
      \fI\(-> 123 0\fR
@@ -111,10 +122,17 @@ set pid2 [pid $chan]
      \fI\(-> 1011 {}\fR
 
 \fB::tcl::process status\fR -wait
-     \fI\(-> 123 0 456 {1 "child killed: write on pipe with no readers" {CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}} 789 {1 "child suspended: background tty read" {CHILDSUSP 789 SIGTTIN "background tty read"}} 1011 {1 "child process exited abnormally" {CHILDSTATUS 1011 -1}}\fR
+     \fI\(-> 123 0
+       456 {1 "child killed: write on pipe with no readers" {
+         CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}}
+       789 {1 "child suspended: background tty read" {
+         CHILDSUSP 789 SIGTTIN "background tty read"}}
+       1011 {1 "child process exited abnormally" {
+         CHILDSTATUS 1011 -1}}\fR
 
 \fB::tcl::process status\fR 1011
-     \fI\(-> 1011 {1 "child process exited abnormally" {CHILDSTATUS 1011 -1}}\fR
+     \fI\(-> 1011 {1 "child process exited abnormally" {
+         CHILDSTATUS 1011 -1}}\fR
 
 \fB::tcl::process purge\fR
 exec command1 1 2 3 &
@@ -123,7 +141,8 @@ exec command1 1 2 3 &
      \fI\(-> 1213\fR
 .CE
 .SH "SEE ALSO"
-exec(n), open(n), Tcl_DetachPids(3), Tcl_WaitPid(3), Tcl_ReapDetachedProcs(3)
+exec(n), open(n), pid(n),
+Tcl_DetachPids(3), Tcl_WaitPid(3), Tcl_ReapDetachedProcs(3)
 .SH "KEYWORDS"
 background, child, detach, process, wait
 '\" Local Variables: