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