Commit | Line | Data |
---|---|---|
b109e79a | 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 | ||
b109e79a ILT |
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}) |
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 | |
49 | @code{NULL}, to the standard output of the calling program. This | |
50 | should not be set if you want to call @code{pex_read_output} | |
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 | |
74 | proper behavior these flags should match appropriately--a call to | |
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 | |
84 | output. There are two cases in which no output file will be used: 1) | |
85 | if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} | |
86 | was set in the call to @code{pex_init}, and the system supports pipes; | |
87 | 2) if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is | |
88 | @code{NULL}. Otherwise the code will use a file to hold standard | |
89 | output. If @code{PEX_LAST} is not set, this file is considered to be | |
90 | a temporary file, and it will be removed when no longer needed, unless | |
91 | @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. | |
92 | ||
93 | There are two cases to consider when setting the name of the file to | |
94 | hold standard output. | |
95 | ||
96 | First case: @code{PEX_SUFFIX} is set in @var{flags}. In this case | |
97 | @var{outname} may not be @code{NULL}. If the @var{tempbase} parameter | |
98 | to @code{pex_init} was not @code{NULL}, then the output file name is | |
99 | the concatenation of @var{tempbase} and @var{outname}. If | |
100 | @var{tempbase} was @code{NULL}, then the output file name is a random | |
101 | file name ending in @var{outname}. | |
102 | ||
103 | Second case: @code{PEX_SUFFIX} was not set in @var{flags}. In this | |
104 | case, if @var{outname} is not @code{NULL}, it is used as the output | |
105 | file name. If @var{outname} is @code{NULL}, and @var{tempbase} was | |
106 | not NULL, the output file name is randomly chosen using | |
107 | @var{tempbase}. Otherwise the output file name is chosen completely | |
108 | at random. | |
109 | ||
110 | @var{errname} is the file name to use for standard error output. If | |
111 | it is @code{NULL}, standard error is the same as the caller. | |
112 | Otherwise, standard error is written to the named file. | |
113 | ||
114 | On an error return, the code sets @code{*@var{err}} to an @code{errno} | |
115 | value, or to 0 if there is no relevant @code{errno}. | |
116 | ||
117 | @end deftypefn | |
118 | ||
119 | @deftypefn Extension FILE * pex_read_output (struct pex_obj *@var{obj}, int @var{binary}) | |
120 | ||
121 | Returns a @code{FILE} pointer which may be used to read the standard | |
122 | output of the last program in the pipeline. When this is used, | |
123 | @code{PEX_LAST} should not be used in a call to @code{pex_run}. After | |
124 | this is called, @code{pex_run} may no longer be called with the same | |
125 | @var{obj}. @var{binary} should be non-zero if the file should be | |
126 | opened in binary mode. Don't call @code{fclose} on the returned file; | |
127 | it will be closed by @code{pex_free}. | |
128 | ||
129 | @end deftypefn | |
130 | ||
131 | @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector}) | |
132 | ||
133 | Returns the exit status of all programs run using @var{obj}. | |
134 | @var{count} is the number of results expected. The results will be | |
135 | placed into @var{vector}. The results are in the order of the calls | |
136 | to @code{pex_run}. Returns 0 on error, 1 on success. | |
137 | ||
138 | @end deftypefn | |
139 | ||
140 | @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector}) | |
5a17353c | 141 | |
b109e79a ILT |
142 | Returns the process execution times of all programs run using |
143 | @var{obj}. @var{count} is the number of results expected. The | |
144 | results will be placed into @var{vector}. The results are in the | |
145 | order of the calls to @code{pex_run}. Returns 0 on error, 1 on | |
146 | success. | |
5a17353c | 147 | |
b109e79a ILT |
148 | @code{struct pex_time} has the following fields: @code{user_seconds}, |
149 | @code{user_microseconds}, @code{system_seconds}, | |
150 | @code{system_microseconds}. On systems which do not support reporting | |
151 | process times, all the fields will be set to @code{0}. | |
5a17353c | 152 | |
b109e79a ILT |
153 | @end deftypefn |
154 | ||
155 | @deftypefn Extension void pex_free (struct pex_obj @var{obj}) | |
5a17353c | 156 | |
b109e79a | 157 | Clean up and free all data associated with @var{obj}. |
5a17353c DD |
158 | |
159 | @end deftypefn | |
160 | ||
b109e79a ILT |
161 | @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}) |
162 | ||
163 | An interface to @code{pex_init} to permit the easy execution of a | |
164 | single program. The return value and most of the parameters are as | |
165 | for a call to @code{pex_run}. @var{flags} is restricted to a | |
166 | combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and | |
167 | @code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if | |
168 | @code{PEX_LAST} were set. On a successful return, *@var{status} will | |
169 | be set to the exit status of the program. | |
170 | ||
171 | @end deftypefn | |
172 | ||
173 | @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 | 174 | |
b109e79a ILT |
175 | This is the old interface to execute one or more programs. It is |
176 | still supported for compatibility purposes, but is no longer | |
177 | documented. | |
5a17353c | 178 | |
b109e79a ILT |
179 | @end deftypefn |
180 | ||
181 | @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) | |
182 | ||
183 | Another part of the old execution interface. | |
184 | ||
185 | @end deftypefn |