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