1@c -*- mode: texinfo -*-
2@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @
3  const char *@var{pname}, const char *@var{tempbase})
4
5Prepare to execute one or more programs, with standard output of each
6program fed to standard input of the next.  This is a system
7independent interface to execute a pipeline.
8
9@var{flags} is a bitwise combination of the following:
10
11@table @code
12
13@vindex PEX_RECORD_TIMES
14@item PEX_RECORD_TIMES
15Record subprocess times if possible.
16
17@vindex PEX_USE_PIPES
18@item PEX_USE_PIPES
19Use pipes for communication between processes, if possible.
20
21@vindex PEX_SAVE_TEMPS
22@item PEX_SAVE_TEMPS
23Don't delete temporary files used for communication between
24processes.
25
26@end table
27
28@var{pname} is the name of program to be executed, used in error
29messages.  @var{tempbase} is a base name to use for any required
30temporary files; it may be @code{NULL} to use a randomly chosen name.
31
32@end deftypefn
33
34@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, @
35  int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @
36  const char *@var{outname}, const char *@var{errname}, int *@var{err})
37
38Execute one program in a pipeline.  On success this returns
39@code{NULL}.  On failure it returns an error message, a statically
40allocated string.
41
42@var{obj} is returned by a previous call to @code{pex_init}.
43
44@var{flags} is a bitwise combination of the following:
45
46@table @code
47
48@vindex PEX_LAST
49@item PEX_LAST
50This must be set on the last program in the pipeline.  In particular,
51it should be set when executing a single program.  The standard output
52of the program will be sent to @var{outname}, or, if @var{outname} is
53@code{NULL}, to the standard output of the calling program.  Do @emph{not}
54set this bit if you want to call @code{pex_read_output}
55(described below).  After a call to @code{pex_run} with this bit set,
56@var{pex_run} may no longer be called with the same @var{obj}.
57
58@vindex PEX_SEARCH
59@item PEX_SEARCH
60Search for the program using the user's executable search path.
61
62@vindex PEX_SUFFIX
63@item PEX_SUFFIX
64@var{outname} is a suffix.  See the description of @var{outname},
65below.
66
67@vindex PEX_STDERR_TO_STDOUT
68@item PEX_STDERR_TO_STDOUT
69Send the program's standard error to standard output, if possible.
70
71@vindex PEX_BINARY_INPUT
72@vindex PEX_BINARY_OUTPUT
73@vindex PEX_BINARY_ERROR
74@item PEX_BINARY_INPUT
75@itemx PEX_BINARY_OUTPUT
76@itemx PEX_BINARY_ERROR
77The standard input (output or error) of the program should be read (written) in
78binary mode rather than text mode.  These flags are ignored on systems
79which do not distinguish binary mode and text mode, such as Unix.  For
80proper behavior these flags should match appropriately---a call to
81@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
82call using @code{PEX_BINARY_INPUT}.
83
84@vindex PEX_STDERR_TO_PIPE
85@item PEX_STDERR_TO_PIPE
86Send the program's standard error to a pipe, if possible.  This flag
87cannot be specified together with @code{PEX_STDERR_TO_STDOUT}.  This
88flag can be specified only on the last program in pipeline.
89
90@end table
91
92@var{executable} is the program to execute.  @var{argv} is the set of
93arguments to pass to the program; normally @code{@var{argv}[0]} will
94be a copy of @var{executable}.
95
96@var{outname} is used to set the name of the file to use for standard
97output.  There are two cases in which no output file will be used:
98
99@enumerate
100@item
101if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
102was set in the call to @code{pex_init}, and the system supports pipes
103
104@item
105if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
106@code{NULL}
107@end enumerate
108
109@noindent
110Otherwise the code will use a file to hold standard
111output.  If @code{PEX_LAST} is not set, this file is considered to be
112a temporary file, and it will be removed when no longer needed, unless
113@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
114
115There are two cases to consider when setting the name of the file to
116hold standard output.
117
118@enumerate
119@item
120@code{PEX_SUFFIX} is set in @var{flags}.  In this case
121@var{outname} may not be @code{NULL}.  If the @var{tempbase} parameter
122to @code{pex_init} was not @code{NULL}, then the output file name is
123the concatenation of @var{tempbase} and @var{outname}.  If
124@var{tempbase} was @code{NULL}, then the output file name is a random
125file name ending in @var{outname}.
126
127@item
128@code{PEX_SUFFIX} was not set in @var{flags}.  In this
129case, if @var{outname} is not @code{NULL}, it is used as the output
130file name.  If @var{outname} is @code{NULL}, and @var{tempbase} was
131not NULL, the output file name is randomly chosen using
132@var{tempbase}.  Otherwise the output file name is chosen completely
133at random.
134@end enumerate
135
136@var{errname} is the file name to use for standard error output.  If
137it is @code{NULL}, standard error is the same as the caller's.
138Otherwise, standard error is written to the named file.
139
140On an error return, the code sets @code{*@var{err}} to an @code{errno}
141value, or to 0 if there is no relevant @code{errno}.
142
143@end deftypefn
144
145@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, @
146  int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @
147  char * const *@var{env}, int @var{env_size}, const char *@var{outname}, @
148  const char *@var{errname}, int *@var{err})
149
150Execute one program in a pipeline, permitting the environment for the
151program to be specified.  Behaviour and parameters not listed below are
152as for @code{pex_run}.
153
154@var{env} is the environment for the child process, specified as an array of
155character pointers.  Each element of the array should point to a string of the
156form @code{VAR=VALUE}, with the exception of the last element that must be
157@code{NULL}.
158
159@end deftypefn
160
161@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @
162  int @var{flags}, const char *@var{in_name})
163
164Return a stream for a temporary file to pass to the first program in
165the pipeline as input.
166
167The name of the input file is chosen according to the same rules
168@code{pex_run} uses to choose output file names, based on
169@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.
170
171Don't call @code{fclose} on the returned stream; the first call to
172@code{pex_run} closes it automatically.
173
174If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
175binary mode; otherwise, open it in the default mode.  Including
176@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
177@end deftypefn
178
179@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @
180  int @var{binary})
181
182Return a stream @var{fp} for a pipe connected to the standard input of
183the first program in the pipeline; @var{fp} is opened for writing.
184You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
185that returned @var{obj}.
186
187You must close @var{fp} using @code{fclose} yourself when you have
188finished writing data to the pipeline.
189
190The file descriptor underlying @var{fp} is marked not to be inherited
191by child processes.
192
193On systems that do not support pipes, this function returns
194@code{NULL}, and sets @code{errno} to @code{EINVAL}.  If you would
195like to write code that is portable to all systems the @code{pex}
196functions support, consider using @code{pex_input_file} instead.
197
198There are two opportunities for deadlock using
199@code{pex_input_pipe}:
200
201@itemize @bullet
202@item
203Most systems' pipes can buffer only a fixed amount of data; a process
204that writes to a full pipe blocks.  Thus, if you write to @file{fp}
205before starting the first process, you run the risk of blocking when
206there is no child process yet to read the data and allow you to
207continue.  @code{pex_input_pipe} makes no promises about the
208size of the pipe's buffer, so if you need to write any data at all
209before starting the first process in the pipeline, consider using
210@code{pex_input_file} instead.
211
212@item
213Using @code{pex_input_pipe} and @code{pex_read_output} together
214may also cause deadlock.  If the output pipe fills up, so that each
215program in the pipeline is waiting for the next to read more data, and
216you fill the input pipe by writing more data to @var{fp}, then there
217is no way to make progress: the only process that could read data from
218the output pipe is you, but you are blocked on the input pipe.
219
220@end itemize
221
222@end deftypefn
223
224@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @
225  int @var{binary})
226
227Returns a @code{FILE} pointer which may be used to read the standard
228output of the last program in the pipeline.  When this is used,
229@code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
230this is called, @code{pex_run} may no longer be called with the same
231@var{obj}.  @var{binary} should be non-zero if the file should be
232opened in binary mode.  Don't call @code{fclose} on the returned file;
233it will be closed by @code{pex_free}.
234
235@end deftypefn
236
237@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @
238  int @var{binary})
239
240Returns a @code{FILE} pointer which may be used to read the standard
241error of the last program in the pipeline.  When this is used,
242@code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
243this is called, @code{pex_run} may no longer be called with the same
244@var{obj}.  @var{binary} should be non-zero if the file should be
245opened in binary mode.  Don't call @code{fclose} on the returned file;
246it will be closed by @code{pex_free}.
247
248@end deftypefn
249
250
251@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @
252  int @var{count}, int *@var{vector})
253
254Returns the exit status of all programs run using @var{obj}.
255@var{count} is the number of results expected.  The results will be
256placed into @var{vector}.  The results are in the order of the calls
257to @code{pex_run}.  Returns 0 on error, 1 on success.
258
259@end deftypefn
260
261@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @
262  int @var{count}, struct pex_time *@var{vector})
263
264Returns the process execution times of all programs run using
265@var{obj}.  @var{count} is the number of results expected.  The
266results will be placed into @var{vector}.  The results are in the
267order of the calls to @code{pex_run}.  Returns 0 on error, 1 on
268success.
269
270@code{struct pex_time} has the following fields of the type
271@code{unsigned long}: @code{user_seconds},
272@code{user_microseconds}, @code{system_seconds},
273@code{system_microseconds}.  On systems which do not support reporting
274process times, all the fields will be set to @code{0}.
275
276@end deftypefn
277
278@deftypefn Extension void pex_free (struct pex_obj @var{obj})
279
280Clean up and free all data associated with @var{obj}.  If you have not
281yet called @code{pex_get_times} or @code{pex_get_status}, this will
282try to kill the subprocesses.
283
284@end deftypefn
285
286@deftypefn Extension {const char *} pex_one (int @var{flags}, @
287  const char *@var{executable}, char * const *@var{argv}, @
288  const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, @
289  int *@var{status}, int *@var{err})
290
291An interface to permit the easy execution of a
292single program.  The return value and most of the parameters are as
293for a call to @code{pex_run}.  @var{flags} is restricted to a
294combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
295@code{PEX_BINARY_OUTPUT}.  @var{outname} is interpreted as if
296@code{PEX_LAST} were set.  On a successful return, @code{*@var{status}} will
297be set to the exit status of the program.
298
299@end deftypefn
300
301@deftypefn Extension int pexecute (const char *@var{program}, @
302  char * const *@var{argv}, const char *@var{this_pname}, @
303  const char *@var{temp_base}, char **@var{errmsg_fmt}, @
304  char **@var{errmsg_arg}, int @var{flags})
305
306This is the old interface to execute one or more programs.  It is
307still supported for compatibility purposes, but is no longer
308documented.
309
310@end deftypefn
311
312@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
313
314Another part of the old execution interface.
315
316@end deftypefn
317