1new_process
2
3 SYNOPSIS
4  Create a subprocess object
5
6 USAGE
7  Struct_Type new_process (String_Type argv[]; qualifiers)
8
9 DESCRIPTION
10  This function executes the program specified by the `argv'
11  parameter in a subprocess.  If `argv' is an array, the first
12  element (`argv[0]') of the array gives the name of the program
13  to be executed, and the remaining elements serve as arguments passed
14  to the program.  The program returns a structure that may be used to
15  interact with the process.  Upon error, an exception will be thrown.
16
17  The calling program may interact with the subprocess by reading from
18  or writing to the file descriptor fields of the structure returned
19  by the `new_process' function.  The specific file descriptors
20  are dictated via the `read', `write', and `dupN'
21  qualifiers, as described in detail below.
22
23  The function returns a structure containing zero or more fields of the form
24  `fdN' where `N' is an integer derived from the qualifiers,
25  e.g., `fd0' and `fd1' correspond to the child's stdin and
26  stdout, respectively.  The structure also contains fields of the
27  form `fpN' whose values are stdio File_Type objects
28  obtained using `fdopen' with the corresponding `fdN' value.
29
30  Other important fields include `pid' whose value is
31  the process-id of the newly created process.
32
33  The status of the process may be checked or collected using the
34  `wait' method.  It is very important to call this method to
35  avoid the creation of zombie processes.
36
37 QUALIFIERS
38  The following qualifiers are supported:
39
40   read=fds
41
42    fds is a list of integer file descriptors that are open for read
43    access in the subprocess, and may be written to by the calling
44    process using the fdN or fpN fields of the structure.
45
46   write=fds
47
48    fds is a list of integer file descriptors that are open for write
49    access in the subprocess, and may be read to by the calling
50    process using the fdN or fpN fields of the structure.
51
52   stdin=filename
53   stdout=filename
54   stderr=filename
55
56    These qualifiers allow the stdin, stdout, and stderr file
57    descriptors in the subprocess to be redirected to a file.  Note:
58    The filenames are interpreted relative to the value of the
59    `dir' qualifier.
60
61   fdN=string
62
63    This qualifier will cause the integer file descriptor N to be open
64    in the subprocess and redirected to the filename represented by
65    the string, which is interpreted relative to the value of the `dir'
66    qualifier.  The access mode is dictated by the first few
67    characters of the string as described in more detail below.
68
69   stdin=File_Type|FD_Type
70   stdout=File_Type|FD_Type
71   stderr=File_Type|FD_Type
72   fdN=FD_Type|FD_Type
73
74     If the stdin, stdout, stderr, or fdN qualifiers have File_Type or
75     FD_Type values, then corresponding file descriptors in the
76     subprocess will be dup'd to FD_Type or FP_Type file descriptor.
77     This form of the qualifier may be used to setup pipelines.
78
79   dupN=int
80
81     The file descriptor corresponding to the integer N in the
82     subprocess is created by duping the descriptor given by the
83     integer value of the qualifier.  For example, dup2=1 would cause
84     stderr (fd=2) in the subprocess to be redirected to stdout (fd=1).
85
86   dir=string
87
88     Change to the specified directory in the child process.  This
89     will happen after the child process is started, but before any
90     files have been opened.  Hence, files attached to `stdin',
91     `stdout', etc will be opened relative to this directory.
92
93   pre_exec_hook=&func
94
95     This qualifier will cause the function corresponding to `func' to
96     be called prior to closing unused file descriptors and invoking
97     the executable.  The function will be passed a list of integer
98     valued file descriptors that will be kept open.  Additional
99     integers may be added to the list by the function.  If the
100     qualifier `pre_exec_hook_optarg' exists, it will also be
101     passed as an addtional argument.
102
103   pre_exec_hook_optarg=VALUE
104
105     If this qualifier exists, its value will be passed as the second
106     argument to the `pre_exec_hook' callback function.
107
108  Note that the read and write qualifiers specify the nature of the
109  file descriptors from the child process's view.  That is, those
110  opened in the child process using the read qualifier, may be written
111  to by the parent.  Similarly, those opened using the write qualifier
112  may be read by the parent.
113
114 METHODS
115
116    Struct_Type .wait ( [ options ] )
117
118  The `.wait' method may be used to collect the exist status of
119  the process.  When called without arguments, it will cause the
120  parent process to wait for the subprocess to exit and return its
121  exit status in the form of a `waitpid' structure.  The optional
122  `options' argument corresponds to the options argument of the
123  `waitpid' function.  The most common is the WNOHANG option,
124  which will cause the `.wait' method to return immediately if
125  the process has not exited.
126
127  If an error occurs, the function will return NULL and set
128  `errno' accordingly.  Otherwise it will return a `waitpid'
129  structure.  See the documentation for `waitpid' for more
130  information.
131
132 EXAMPLE
133  In the following examples, `pgm' represents the program to be
134  invoked in the subprocess.  For simplicity, no addition arguments are
135  shown
136
137  Create subprocess that inherits stdin, stdout, stderr from the caller:
138
139   obj = new_process (pgm);
140
141
142  Create a subprocess that inherits stdin, stdout, and writes stderr
143  to a file:
144
145   obj = new_process (pgm; stderr="/tmp/file");   % form 1
146   obj = new_process (pgm; fd2=">/tmp/file");     % form 2
147
148
149  Mimic popen(pgm, "r"):
150
151   obj = new_process (pgm; write=1);   % Read from obj.fp1
152
153
154  Mimic popen(pgm, "w"):
155
156   obj = new_process (pgm; read=0);  % Write to obj.fp0
157
158
159  Mimic popen("pgm 2>&1", "r"):
160
161   obj = new_process (pgm; write=1, dup2=1);  % Read from fp1
162
163
164  Send stdout to a file, read from the subprocess's stderr:
165
166   obj = new_process (pgm; stdout="/tmp/file", write=2);
167   % Read from obj.fp2
168
169
170  Create a process with handles to its stdin, stdout, stderr
171
172   obj = new_process (pgm; write={1,2}, read=0);
173   % Use obj.fp0 for stdin, obj.fp1 for stdout, and obj.fp2 for stderr
174
175
176  Create a process with a write handle to the process's fd=27 and a
177  read handle to the process's stdout.
178
179   obj = new_process (pgm; read=27, write=1);
180   % write to fp27, read from fp1
181
182
183  Create a pipeline: pgm1 | pgm2 > /tmp/log :
184
185  obj1 = new_process (pgm1; write=1);
186  obj2 = new_process (pgm2; stdin=obj1.fp1, stdout="/tmp/log");
187
188
189  Create a pipeline with fd=27 from pgm1 redirected to stdin of pgm2:
190
191  obj1 = new_process (pgm1; write=27);
192  obj2 = new_process (pgm2; stdin=obj1.fp27);
193
194
195  Create a pipeline with fd=27 from pgm1 redirected to fd=9 of pgm2:
196
197  obj1 = new_process (pgm1; write=27);
198  obj2 = new_process (pgm2; fp9=obj1.fp27);
199
200
201  Mimic: pgm 2>&1 1>/dev/null
202
203  obj = new_process (pgm; fp2=1, stdout="/dev/null");
204
205
206  Mimic: pgm >/dev/null 2>&1
207
208  obj = new_process (pgm; stdout="/dev/null", dup2=1);
209
210
211  Append the output of pgm to /tmp/file.log:
212
213   obj = new_process (pgm; stdout=">>/tmp/file.log");
214
215
216 NOTES
217  Care must be exercised when reading or writing to multiple file
218  descriptors of a subprocess to avoid deadlock.  In such cases, the
219  select module should be used, or the file descriptors could be put in
220  non-blocking mode via the fcntl module.
221
222  It is important to call the `.wait' method prevent the process
223  from becoming a zombie and clogging the process table.
224
225 SEE ALSO
226  popen, system
227
228--------------------------------------------------------------
229