Commit | Line | Data |
---|---|---|
f13c9bea | 1 | @deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase}) |
5a17353c | 2 | |
b109e79a ILT |
3 | Prepare to execute one or more programs, with standard output of each |
4 | program fed to standard input of the next. This is a system | |
5 | independent interface to execute a pipeline. | |
5a17353c | 6 | |
b109e79a | 7 | @var{flags} is a bitwise combination of the following: |
5a17353c | 8 | |
b109e79a | 9 | @table @code |
5a17353c | 10 | |
b109e79a ILT |
11 | @vindex PEX_RECORD_TIMES |
12 | @item PEX_RECORD_TIMES | |
13 | Record subprocess times if possible. | |
5a17353c | 14 | |
b109e79a ILT |
15 | @vindex PEX_USE_PIPES |
16 | @item PEX_USE_PIPES | |
17 | Use pipes for communication between processes, if possible. | |
5a17353c | 18 | |
b109e79a ILT |
19 | @vindex PEX_SAVE_TEMPS |
20 | @item PEX_SAVE_TEMPS | |
21 | Don't delete temporary files used for communication between | |
22 | processes. | |
5a17353c | 23 | |
b109e79a | 24 | @end table |
5a17353c | 25 | |
b109e79a ILT |
26 | @var{pname} is the name of program to be executed, used in error |
27 | messages. @var{tempbase} is a base name to use for any required | |
28 | temporary files; it may be @code{NULL} to use a randomly chosen name. | |
5a17353c DD |
29 | |
30 | @end deftypefn | |
31 | ||
f13c9bea | 32 | @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 |
33 | |
34 | Execute one program in a pipeline. On success this returns | |
35 | @code{NULL}. On failure it returns an error message, a statically | |
36 | allocated string. | |
37 | ||
38 | @var{obj} is returned by a previous call to @code{pex_init}. | |
39 | ||
40 | @var{flags} is a bitwise combination of the following: | |
41 | ||
42 | @table @code | |
43 | ||
44 | @vindex PEX_LAST | |
45 | @item PEX_LAST | |
46 | This must be set on the last program in the pipeline. In particular, | |
47 | it should be set when executing a single program. The standard output | |
48 | of the program will be sent to @var{outname}, or, if @var{outname} is | |
f13c9bea DD |
49 | @code{NULL}, to the standard output of the calling program. Do @emph{not} |
50 | set this bit if you want to call @code{pex_read_output} | |
b109e79a ILT |
51 | (described below). After a call to @code{pex_run} with this bit set, |
52 | @var{pex_run} may no longer be called with the same @var{obj}. | |
53 | ||
54 | @vindex PEX_SEARCH | |
55 | @item PEX_SEARCH | |
56 | Search for the program using the user's executable search path. | |
57 | ||
58 | @vindex PEX_SUFFIX | |
59 | @item PEX_SUFFIX | |
60 | @var{outname} is a suffix. See the description of @var{outname}, | |
61 | below. | |
62 | ||
63 | @vindex PEX_STDERR_TO_STDOUT | |
64 | @item PEX_STDERR_TO_STDOUT | |
65 | Send the program's standard error to standard output, if possible. | |
66 | ||
67 | @vindex PEX_BINARY_INPUT | |
68 | @vindex PEX_BINARY_OUTPUT | |
69 | @item PEX_BINARY_INPUT | |
70 | @itemx PEX_BINARY_OUTPUT | |
71 | The standard input (output) of the program should be read (written) in | |
72 | binary mode rather than text mode. These flags are ignored on systems | |
73 | which do not distinguish binary mode and text mode, such as Unix. For | |
f13c9bea | 74 | proper behavior these flags should match appropriately---a call to |
b109e79a ILT |
75 | @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a |
76 | call using @code{PEX_BINARY_INPUT}. | |
77 | @end table | |
78 | ||
79 | @var{executable} is the program to execute. @var{argv} is the set of | |
80 | arguments to pass to the program; normally @code{@var{argv}[0]} will | |
81 | be a copy of @var{executable}. | |
82 | ||
83 | @var{outname} is used to set the name of the file to use for standard | |
f13c9bea DD |
84 | output. There are two cases in which no output file will be used: |
85 | ||
86 | @enumerate | |
87 | @item | |
b109e79a | 88 | if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} |
f13c9bea DD |
89 | was set in the call to @code{pex_init}, and the system supports pipes |
90 | ||
91 | @item | |
92 | if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is | |
93 | @code{NULL} | |
94 | @end enumerate | |
95 | ||
96 | @noindent | |
97 | Otherwise the code will use a file to hold standard | |
b109e79a ILT |
98 | output. If @code{PEX_LAST} is not set, this file is considered to be |
99 | a temporary file, and it will be removed when no longer needed, unless | |
100 | @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. | |
101 | ||
102 | There are two cases to consider when setting the name of the file to | |
103 | hold standard output. | |
104 | ||
f13c9bea DD |
105 | @enumerate |
106 | @item | |
107 | @code{PEX_SUFFIX} is set in @var{flags}. In this case | |
b109e79a ILT |
108 | @var{outname} may not be @code{NULL}. If the @var{tempbase} parameter |
109 | to @code{pex_init} was not @code{NULL}, then the output file name is | |
110 | the concatenation of @var{tempbase} and @var{outname}. If | |
111 | @var{tempbase} was @code{NULL}, then the output file name is a random | |
112 | file name ending in @var{outname}. | |
113 | ||
f13c9bea DD |
114 | @item |
115 | @code{PEX_SUFFIX} was not set in @var{flags}. In this | |
b109e79a ILT |
116 | case, if @var{outname} is not @code{NULL}, it is used as the output |
117 | file name. If @var{outname} is @code{NULL}, and @var{tempbase} was | |
118 | not NULL, the output file name is randomly chosen using | |
119 | @var{tempbase}. Otherwise the output file name is chosen completely | |
120 | at random. | |
f13c9bea | 121 | @end enumerate |
b109e79a ILT |
122 | |
123 | @var{errname} is the file name to use for standard error output. If | |
f13c9bea | 124 | it is @code{NULL}, standard error is the same as the caller's. |
b109e79a ILT |
125 | Otherwise, standard error is written to the named file. |
126 | ||
127 | On an error return, the code sets @code{*@var{err}} to an @code{errno} | |
128 | value, or to 0 if there is no relevant @code{errno}. | |
129 | ||
130 | @end deftypefn | |
131 | ||
f13c9bea | 132 | @deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary}) |
b109e79a ILT |
133 | |
134 | Returns a @code{FILE} pointer which may be used to read the standard | |
135 | output of the last program in the pipeline. When this is used, | |
136 | @code{PEX_LAST} should not be used in a call to @code{pex_run}. After | |
137 | this is called, @code{pex_run} may no longer be called with the same | |
138 | @var{obj}. @var{binary} should be non-zero if the file should be | |
139 | opened in binary mode. Don't call @code{fclose} on the returned file; | |
140 | it will be closed by @code{pex_free}. | |
141 | ||
142 | @end deftypefn | |
143 | ||
144 | @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector}) | |
145 | ||
146 | Returns the exit status of all programs run using @var{obj}. | |
147 | @var{count} is the number of results expected. The results will be | |
148 | placed into @var{vector}. The results are in the order of the calls | |
149 | to @code{pex_run}. Returns 0 on error, 1 on success. | |
150 | ||
151 | @end deftypefn | |
152 | ||
153 | @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector}) | |
5a17353c | 154 | |
b109e79a ILT |
155 | Returns the process execution times of all programs run using |
156 | @var{obj}. @var{count} is the number of results expected. The | |
157 | results will be placed into @var{vector}. The results are in the | |
158 | order of the calls to @code{pex_run}. Returns 0 on error, 1 on | |
159 | success. | |
5a17353c | 160 | |
f13c9bea DD |
161 | @code{struct pex_time} has the following fields of the type |
162 | @code{unsigned long}: @code{user_seconds}, | |
b109e79a ILT |
163 | @code{user_microseconds}, @code{system_seconds}, |
164 | @code{system_microseconds}. On systems which do not support reporting | |
165 | process times, all the fields will be set to @code{0}. | |
5a17353c | 166 | |
b109e79a ILT |
167 | @end deftypefn |
168 | ||
169 | @deftypefn Extension void pex_free (struct pex_obj @var{obj}) | |
5a17353c | 170 | |
b109e79a | 171 | Clean up and free all data associated with @var{obj}. |
5a17353c DD |
172 | |
173 | @end deftypefn | |
174 | ||
f13c9bea | 175 | @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 | 176 | |
f13c9bea | 177 | An interface to permit the easy execution of a |
b109e79a ILT |
178 | single program. The return value and most of the parameters are as |
179 | for a call to @code{pex_run}. @var{flags} is restricted to a | |
180 | combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and | |
181 | @code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if | |
f13c9bea | 182 | @code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will |
b109e79a ILT |
183 | be set to the exit status of the program. |
184 | ||
185 | @end deftypefn | |
186 | ||
187 | @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 flags) | |
5a17353c | 188 | |
b109e79a ILT |
189 | This is the old interface to execute one or more programs. It is |
190 | still supported for compatibility purposes, but is no longer | |
191 | documented. | |
5a17353c | 192 | |
b109e79a ILT |
193 | @end deftypefn |
194 | ||
195 | @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) | |
196 | ||
197 | Another part of the old execution interface. | |
198 | ||
199 | @end deftypefn |