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 |
---|