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