| 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 | |
| 5 | Prepare to execute one or more programs, with standard output of each |
| 6 | program fed to standard input of the next. This is a system |
| 7 | independent 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 |
| 15 | Record subprocess times if possible. |
| 16 | |
| 17 | @vindex PEX_USE_PIPES |
| 18 | @item PEX_USE_PIPES |
| 19 | Use pipes for communication between processes, if possible. |
| 20 | |
| 21 | @vindex PEX_SAVE_TEMPS |
| 22 | @item PEX_SAVE_TEMPS |
| 23 | Don't delete temporary files used for communication between |
| 24 | processes. |
| 25 | |
| 26 | @end table |
| 27 | |
| 28 | @var{pname} is the name of program to be executed, used in error |
| 29 | messages. @var{tempbase} is a base name to use for any required |
| 30 | temporary 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 | |
| 38 | Execute one program in a pipeline. On success this returns |
| 39 | @code{NULL}. On failure it returns an error message, a statically |
| 40 | allocated 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 |
| 50 | This must be set on the last program in the pipeline. In particular, |
| 51 | it should be set when executing a single program. The standard output |
| 52 | of 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} |
| 54 | set 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 |
| 60 | Search 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}, |
| 65 | below. |
| 66 | |
| 67 | @vindex PEX_STDERR_TO_STDOUT |
| 68 | @item PEX_STDERR_TO_STDOUT |
| 69 | Send 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 |
| 77 | The standard input (output or error) of the program should be read (written) in |
| 78 | binary mode rather than text mode. These flags are ignored on systems |
| 79 | which do not distinguish binary mode and text mode, such as Unix. For |
| 80 | proper behavior these flags should match appropriately---a call to |
| 81 | @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a |
| 82 | call using @code{PEX_BINARY_INPUT}. |
| 83 | |
| 84 | @vindex PEX_STDERR_TO_PIPE |
| 85 | @item PEX_STDERR_TO_PIPE |
| 86 | Send the program's standard error to a pipe, if possible. This flag |
| 87 | cannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This |
| 88 | flag 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 |
| 93 | arguments to pass to the program; normally @code{@var{argv}[0]} will |
| 94 | be a copy of @var{executable}. |
| 95 | |
| 96 | @var{outname} is used to set the name of the file to use for standard |
| 97 | output. There are two cases in which no output file will be used: |
| 98 | |
| 99 | @enumerate |
| 100 | @item |
| 101 | if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} |
| 102 | was set in the call to @code{pex_init}, and the system supports pipes |
| 103 | |
| 104 | @item |
| 105 | if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is |
| 106 | @code{NULL} |
| 107 | @end enumerate |
| 108 | |
| 109 | @noindent |
| 110 | Otherwise the code will use a file to hold standard |
| 111 | output. If @code{PEX_LAST} is not set, this file is considered to be |
| 112 | a 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 | |
| 115 | There are two cases to consider when setting the name of the file to |
| 116 | hold 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 |
| 122 | to @code{pex_init} was not @code{NULL}, then the output file name is |
| 123 | the concatenation of @var{tempbase} and @var{outname}. If |
| 124 | @var{tempbase} was @code{NULL}, then the output file name is a random |
| 125 | file name ending in @var{outname}. |
| 126 | |
| 127 | @item |
| 128 | @code{PEX_SUFFIX} was not set in @var{flags}. In this |
| 129 | case, if @var{outname} is not @code{NULL}, it is used as the output |
| 130 | file name. If @var{outname} is @code{NULL}, and @var{tempbase} was |
| 131 | not NULL, the output file name is randomly chosen using |
| 132 | @var{tempbase}. Otherwise the output file name is chosen completely |
| 133 | at random. |
| 134 | @end enumerate |
| 135 | |
| 136 | @var{errname} is the file name to use for standard error output. If |
| 137 | it is @code{NULL}, standard error is the same as the caller's. |
| 138 | Otherwise, standard error is written to the named file. |
| 139 | |
| 140 | On an error return, the code sets @code{*@var{err}} to an @code{errno} |
| 141 | value, 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 | |
| 150 | Execute one program in a pipeline, permitting the environment for the |
| 151 | program to be specified. Behaviour and parameters not listed below are |
| 152 | as for @code{pex_run}. |
| 153 | |
| 154 | @var{env} is the environment for the child process, specified as an array of |
| 155 | character pointers. Each element of the array should point to a string of the |
| 156 | form @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 | |
| 164 | Return a stream for a temporary file to pass to the first program in |
| 165 | the pipeline as input. |
| 166 | |
| 167 | The 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 | |
| 171 | Don't call @code{fclose} on the returned stream; the first call to |
| 172 | @code{pex_run} closes it automatically. |
| 173 | |
| 174 | If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in |
| 175 | binary 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 | |
| 182 | Return a stream @var{fp} for a pipe connected to the standard input of |
| 183 | the first program in the pipeline; @var{fp} is opened for writing. |
| 184 | You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call |
| 185 | that returned @var{obj}. |
| 186 | |
| 187 | You must close @var{fp} using @code{fclose} yourself when you have |
| 188 | finished writing data to the pipeline. |
| 189 | |
| 190 | The file descriptor underlying @var{fp} is marked not to be inherited |
| 191 | by child processes. |
| 192 | |
| 193 | On systems that do not support pipes, this function returns |
| 194 | @code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would |
| 195 | like to write code that is portable to all systems the @code{pex} |
| 196 | functions support, consider using @code{pex_input_file} instead. |
| 197 | |
| 198 | There are two opportunities for deadlock using |
| 199 | @code{pex_input_pipe}: |
| 200 | |
| 201 | @itemize @bullet |
| 202 | @item |
| 203 | Most systems' pipes can buffer only a fixed amount of data; a process |
| 204 | that writes to a full pipe blocks. Thus, if you write to @file{fp} |
| 205 | before starting the first process, you run the risk of blocking when |
| 206 | there is no child process yet to read the data and allow you to |
| 207 | continue. @code{pex_input_pipe} makes no promises about the |
| 208 | size of the pipe's buffer, so if you need to write any data at all |
| 209 | before starting the first process in the pipeline, consider using |
| 210 | @code{pex_input_file} instead. |
| 211 | |
| 212 | @item |
| 213 | Using @code{pex_input_pipe} and @code{pex_read_output} together |
| 214 | may also cause deadlock. If the output pipe fills up, so that each |
| 215 | program in the pipeline is waiting for the next to read more data, and |
| 216 | you fill the input pipe by writing more data to @var{fp}, then there |
| 217 | is no way to make progress: the only process that could read data from |
| 218 | the 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 | |
| 227 | Returns a @code{FILE} pointer which may be used to read the standard |
| 228 | output 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 |
| 230 | this 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 |
| 232 | opened in binary mode. Don't call @code{fclose} on the returned file; |
| 233 | it 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 | |
| 240 | Returns a @code{FILE} pointer which may be used to read the standard |
| 241 | error 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 |
| 243 | this 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 |
| 245 | opened in binary mode. Don't call @code{fclose} on the returned file; |
| 246 | it 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 | |
| 254 | Returns the exit status of all programs run using @var{obj}. |
| 255 | @var{count} is the number of results expected. The results will be |
| 256 | placed into @var{vector}. The results are in the order of the calls |
| 257 | to @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 | |
| 264 | Returns the process execution times of all programs run using |
| 265 | @var{obj}. @var{count} is the number of results expected. The |
| 266 | results will be placed into @var{vector}. The results are in the |
| 267 | order of the calls to @code{pex_run}. Returns 0 on error, 1 on |
| 268 | success. |
| 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 |
| 274 | process 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 | |
| 280 | Clean up and free all data associated with @var{obj}. If you have not |
| 281 | yet called @code{pex_get_times} or @code{pex_get_status}, this will |
| 282 | try 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 | |
| 291 | An interface to permit the easy execution of a |
| 292 | single program. The return value and most of the parameters are as |
| 293 | for a call to @code{pex_run}. @var{flags} is restricted to a |
| 294 | combination 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 |
| 297 | be 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 | |
| 306 | This is the old interface to execute one or more programs. It is |
| 307 | still supported for compatibility purposes, but is no longer |
| 308 | documented. |
| 309 | |
| 310 | @end deftypefn |
| 311 | |
| 312 | @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) |
| 313 | |
| 314 | Another part of the old execution interface. |
| 315 | |
| 316 | @end deftypefn |