pexecute.txh revision 1.1.1.2
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