util/src/TclTk/tcl8.6.12/doc/DetachPids.3

   1 '\"
   2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tcl_DetachPids, Tcl_ReapDetachedProcs, Tcl_WaitPid \- manage child processes in background
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tcl.h>\fR
  16 .sp
  17 \fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
  18 .sp
  19 \fBTcl_ReapDetachedProcs\fR()
  20 .sp
  21 Tcl_Pid
  22 \fBTcl_WaitPid\fR(\fIpid, statusPtr, options\fR)
  23 .SH ARGUMENTS
  24 .AS Tcl_Pid *statusPtr out
  25 .AP int numPids in
  26 Number of process ids contained in the array pointed to by \fIpidPtr\fR.
  27 .AP int *pidPtr in
  28 Address of array containing \fInumPids\fR process ids.
  29 .AP Tcl_Pid pid in
  30 The id of the process (pipe) to wait for.
  31 .AP int *statusPtr out
  32 The result of waiting on a process (pipe). Either 0 or ECHILD.
  33 .AP int options in
  34 The options controlling the wait. WNOHANG specifies not to wait when
  35 checking the process.
  36 .BE
  37 .SH DESCRIPTION
  38 .PP
  39 \fBTcl_DetachPids\fR and \fBTcl_ReapDetachedProcs\fR provide a
  40 mechanism for managing subprocesses that are running in background.
  41 These procedures are needed because the parent of a process must
  42 eventually invoke the \fBwaitpid\fR kernel call (or one of a few other
  43 similar kernel calls) to wait for the child to exit.  Until the
  44 parent waits for the child, the child's state cannot be completely
  45 reclaimed by the system.  If a parent continually creates children
  46 and doesn't wait on them, the system's process table will eventually
  47 overflow, even if all the children have exited.
  48 .PP
  49 \fBTcl_DetachPids\fR may be called to ask Tcl to take responsibility
  50 for one or more processes whose process ids are contained in the
  51 \fIpidPtr\fR array passed as argument.  The caller presumably
  52 has started these processes running in background and does not
  53 want to have to deal with them again.
  54 .PP
  55 \fBTcl_ReapDetachedProcs\fR invokes the \fBwaitpid\fR kernel call
  56 on each of the background processes so that its state can be cleaned
  57 up if it has exited.  If the process has not exited yet,
  58 \fBTcl_ReapDetachedProcs\fR does not wait for it to exit;  it will check again
  59 the next time it is invoked.
  60 Tcl automatically calls \fBTcl_ReapDetachedProcs\fR each time the
  61 \fBexec\fR command is executed, so in most cases it is not necessary
  62 for any code outside of Tcl to invoke \fBTcl_ReapDetachedProcs\fR.
  63 However, if you call \fBTcl_DetachPids\fR in situations where the
  64 \fBexec\fR command may never get executed, you may wish to call
  65 \fBTcl_ReapDetachedProcs\fR from time to time so that background
  66 processes can be cleaned up.
  67 .PP
  68 \fBTcl_WaitPid\fR is a thin wrapper around the facilities provided by
  69 the operating system to wait on the end of a spawned process and to
  70 check a whether spawned process is still running. It is used by
  71 \fBTcl_ReapDetachedProcs\fR and the channel system to portably access
  72 the operating system.
  73
  74 .SH KEYWORDS
  75 background, child, detach, process, wait