1*818008ffSmiod@c -*- mode: texinfo -*- 2*818008ffSmiod@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase}) 332d62142Sespie 4*818008ffSmiodPrepare to execute one or more programs, with standard output of each 5*818008ffSmiodprogram fed to standard input of the next. This is a system 6*818008ffSmiodindependent interface to execute a pipeline. 7150b7e42Smiod 8*818008ffSmiod@var{flags} is a bitwise combination of the following: 9150b7e42Smiod 10*818008ffSmiod@table @code 11150b7e42Smiod 12*818008ffSmiod@vindex PEX_RECORD_TIMES 13*818008ffSmiod@item PEX_RECORD_TIMES 14*818008ffSmiodRecord subprocess times if possible. 15150b7e42Smiod 16*818008ffSmiod@vindex PEX_USE_PIPES 17*818008ffSmiod@item PEX_USE_PIPES 18*818008ffSmiodUse pipes for communication between processes, if possible. 19150b7e42Smiod 20*818008ffSmiod@vindex PEX_SAVE_TEMPS 21*818008ffSmiod@item PEX_SAVE_TEMPS 22*818008ffSmiodDon't delete temporary files used for communication between 23*818008ffSmiodprocesses. 24150b7e42Smiod 25*818008ffSmiod@end table 26150b7e42Smiod 27*818008ffSmiod@var{pname} is the name of program to be executed, used in error 28*818008ffSmiodmessages. @var{tempbase} is a base name to use for any required 29*818008ffSmiodtemporary files; it may be @code{NULL} to use a randomly chosen name. 30*818008ffSmiod 31*818008ffSmiod@end deftypefn 32*818008ffSmiod 33*818008ffSmiod@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*818008ffSmiod 35*818008ffSmiodExecute one program in a pipeline. On success this returns 36*818008ffSmiod@code{NULL}. On failure it returns an error message, a statically 37*818008ffSmiodallocated string. 38*818008ffSmiod 39*818008ffSmiod@var{obj} is returned by a previous call to @code{pex_init}. 40*818008ffSmiod 41*818008ffSmiod@var{flags} is a bitwise combination of the following: 42*818008ffSmiod 43*818008ffSmiod@table @code 44*818008ffSmiod 45*818008ffSmiod@vindex PEX_LAST 46*818008ffSmiod@item PEX_LAST 47*818008ffSmiodThis must be set on the last program in the pipeline. In particular, 48*818008ffSmiodit should be set when executing a single program. The standard output 49*818008ffSmiodof the program will be sent to @var{outname}, or, if @var{outname} is 50*818008ffSmiod@code{NULL}, to the standard output of the calling program. Do @emph{not} 51*818008ffSmiodset this bit if you want to call @code{pex_read_output} 52*818008ffSmiod(described below). After a call to @code{pex_run} with this bit set, 53*818008ffSmiod@var{pex_run} may no longer be called with the same @var{obj}. 54*818008ffSmiod 55*818008ffSmiod@vindex PEX_SEARCH 56*818008ffSmiod@item PEX_SEARCH 57*818008ffSmiodSearch for the program using the user's executable search path. 58*818008ffSmiod 59*818008ffSmiod@vindex PEX_SUFFIX 60*818008ffSmiod@item PEX_SUFFIX 61*818008ffSmiod@var{outname} is a suffix. See the description of @var{outname}, 62*818008ffSmiodbelow. 63*818008ffSmiod 64*818008ffSmiod@vindex PEX_STDERR_TO_STDOUT 65*818008ffSmiod@item PEX_STDERR_TO_STDOUT 66*818008ffSmiodSend the program's standard error to standard output, if possible. 67*818008ffSmiod 68*818008ffSmiod@vindex PEX_BINARY_INPUT 69*818008ffSmiod@vindex PEX_BINARY_OUTPUT 70*818008ffSmiod@vindex PEX_BINARY_ERROR 71*818008ffSmiod@item PEX_BINARY_INPUT 72*818008ffSmiod@itemx PEX_BINARY_OUTPUT 73*818008ffSmiod@itemx PEX_BINARY_ERROR 74*818008ffSmiodThe standard input (output or error) of the program should be read (written) in 75*818008ffSmiodbinary mode rather than text mode. These flags are ignored on systems 76*818008ffSmiodwhich do not distinguish binary mode and text mode, such as Unix. For 77*818008ffSmiodproper behavior these flags should match appropriately---a call to 78*818008ffSmiod@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a 79*818008ffSmiodcall using @code{PEX_BINARY_INPUT}. 80*818008ffSmiod 81*818008ffSmiod@vindex PEX_STDERR_TO_PIPE 82*818008ffSmiod@item PEX_STDERR_TO_PIPE 83*818008ffSmiodSend the program's standard error to a pipe, if possible. This flag 84*818008ffSmiodcannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This 85*818008ffSmiodflag can be specified only on the last program in pipeline. 86*818008ffSmiod 87*818008ffSmiod@end table 88*818008ffSmiod 89*818008ffSmiod@var{executable} is the program to execute. @var{argv} is the set of 90*818008ffSmiodarguments to pass to the program; normally @code{@var{argv}[0]} will 91*818008ffSmiodbe a copy of @var{executable}. 92*818008ffSmiod 93*818008ffSmiod@var{outname} is used to set the name of the file to use for standard 94*818008ffSmiodoutput. There are two cases in which no output file will be used: 95*818008ffSmiod 96*818008ffSmiod@enumerate 97*818008ffSmiod@item 98*818008ffSmiodif @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} 99*818008ffSmiodwas set in the call to @code{pex_init}, and the system supports pipes 100*818008ffSmiod 101*818008ffSmiod@item 102*818008ffSmiodif @code{PEX_LAST} is set in @var{flags}, and @var{outname} is 103*818008ffSmiod@code{NULL} 104*818008ffSmiod@end enumerate 105*818008ffSmiod 106*818008ffSmiod@noindent 107*818008ffSmiodOtherwise the code will use a file to hold standard 108*818008ffSmiodoutput. If @code{PEX_LAST} is not set, this file is considered to be 109*818008ffSmioda temporary file, and it will be removed when no longer needed, unless 110*818008ffSmiod@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. 111*818008ffSmiod 112*818008ffSmiodThere are two cases to consider when setting the name of the file to 113*818008ffSmiodhold standard output. 114*818008ffSmiod 115*818008ffSmiod@enumerate 116*818008ffSmiod@item 117*818008ffSmiod@code{PEX_SUFFIX} is set in @var{flags}. In this case 118*818008ffSmiod@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter 119*818008ffSmiodto @code{pex_init} was not @code{NULL}, then the output file name is 120*818008ffSmiodthe concatenation of @var{tempbase} and @var{outname}. If 121*818008ffSmiod@var{tempbase} was @code{NULL}, then the output file name is a random 122*818008ffSmiodfile name ending in @var{outname}. 123*818008ffSmiod 124*818008ffSmiod@item 125*818008ffSmiod@code{PEX_SUFFIX} was not set in @var{flags}. In this 126*818008ffSmiodcase, if @var{outname} is not @code{NULL}, it is used as the output 127*818008ffSmiodfile name. If @var{outname} is @code{NULL}, and @var{tempbase} was 128*818008ffSmiodnot NULL, the output file name is randomly chosen using 129*818008ffSmiod@var{tempbase}. Otherwise the output file name is chosen completely 130*818008ffSmiodat random. 131*818008ffSmiod@end enumerate 132*818008ffSmiod 133*818008ffSmiod@var{errname} is the file name to use for standard error output. If 134*818008ffSmiodit is @code{NULL}, standard error is the same as the caller's. 135*818008ffSmiodOtherwise, standard error is written to the named file. 136*818008ffSmiod 137*818008ffSmiodOn an error return, the code sets @code{*@var{err}} to an @code{errno} 138*818008ffSmiodvalue, or to 0 if there is no relevant @code{errno}. 139*818008ffSmiod 140*818008ffSmiod@end deftypefn 141*818008ffSmiod 142*818008ffSmiod@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}) 143*818008ffSmiod 144*818008ffSmiodExecute one program in a pipeline, permitting the environment for the 145*818008ffSmiodprogram to be specified. Behaviour and parameters not listed below are 146*818008ffSmiodas for @code{pex_run}. 147*818008ffSmiod 148*818008ffSmiod@var{env} is the environment for the child process, specified as an array of 149*818008ffSmiodcharacter pointers. Each element of the array should point to a string of the 150*818008ffSmiodform @code{VAR=VALUE}, with the exception of the last element that must be 151*818008ffSmiod@code{NULL}. 152*818008ffSmiod 153*818008ffSmiod@end deftypefn 154*818008ffSmiod 155*818008ffSmiod@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name}) 156*818008ffSmiod 157*818008ffSmiodReturn a stream for a temporary file to pass to the first program in 158*818008ffSmiodthe pipeline as input. 159*818008ffSmiod 160*818008ffSmiodThe name of the input file is chosen according to the same rules 161*818008ffSmiod@code{pex_run} uses to choose output file names, based on 162*818008ffSmiod@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}. 163*818008ffSmiod 164*818008ffSmiodDon't call @code{fclose} on the returned stream; the first call to 165*818008ffSmiod@code{pex_run} closes it automatically. 166*818008ffSmiod 167*818008ffSmiodIf @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in 168*818008ffSmiodbinary mode; otherwise, open it in the default mode. Including 169*818008ffSmiod@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. 170*818008ffSmiod@end deftypefn 171*818008ffSmiod 172*818008ffSmiod@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary}) 173*818008ffSmiod 174*818008ffSmiodReturn a stream @var{fp} for a pipe connected to the standard input of 175*818008ffSmiodthe first program in the pipeline; @var{fp} is opened for writing. 176*818008ffSmiodYou must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call 177*818008ffSmiodthat returned @var{obj}. 178*818008ffSmiod 179*818008ffSmiodYou must close @var{fp} using @code{fclose} yourself when you have 180*818008ffSmiodfinished writing data to the pipeline. 181*818008ffSmiod 182*818008ffSmiodThe file descriptor underlying @var{fp} is marked not to be inherited 183*818008ffSmiodby child processes. 184*818008ffSmiod 185*818008ffSmiodOn systems that do not support pipes, this function returns 186*818008ffSmiod@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would 187*818008ffSmiodlike to write code that is portable to all systems the @code{pex} 188*818008ffSmiodfunctions support, consider using @code{pex_input_file} instead. 189*818008ffSmiod 190*818008ffSmiodThere are two opportunities for deadlock using 191*818008ffSmiod@code{pex_input_pipe}: 192*818008ffSmiod 193*818008ffSmiod@itemize @bullet 194*818008ffSmiod@item 195*818008ffSmiodMost systems' pipes can buffer only a fixed amount of data; a process 196*818008ffSmiodthat writes to a full pipe blocks. Thus, if you write to @file{fp} 197*818008ffSmiodbefore starting the first process, you run the risk of blocking when 198*818008ffSmiodthere is no child process yet to read the data and allow you to 199*818008ffSmiodcontinue. @code{pex_input_pipe} makes no promises about the 200*818008ffSmiodsize of the pipe's buffer, so if you need to write any data at all 201*818008ffSmiodbefore starting the first process in the pipeline, consider using 202*818008ffSmiod@code{pex_input_file} instead. 203*818008ffSmiod 204*818008ffSmiod@item 205*818008ffSmiodUsing @code{pex_input_pipe} and @code{pex_read_output} together 206*818008ffSmiodmay also cause deadlock. If the output pipe fills up, so that each 207*818008ffSmiodprogram in the pipeline is waiting for the next to read more data, and 208*818008ffSmiodyou fill the input pipe by writing more data to @var{fp}, then there 209*818008ffSmiodis no way to make progress: the only process that could read data from 210*818008ffSmiodthe output pipe is you, but you are blocked on the input pipe. 211*818008ffSmiod 212*818008ffSmiod@end itemize 213*818008ffSmiod 214*818008ffSmiod@end deftypefn 215*818008ffSmiod 216*818008ffSmiod@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary}) 217*818008ffSmiod 218*818008ffSmiodReturns a @code{FILE} pointer which may be used to read the standard 219*818008ffSmiodoutput of the last program in the pipeline. When this is used, 220*818008ffSmiod@code{PEX_LAST} should not be used in a call to @code{pex_run}. After 221*818008ffSmiodthis is called, @code{pex_run} may no longer be called with the same 222*818008ffSmiod@var{obj}. @var{binary} should be non-zero if the file should be 223*818008ffSmiodopened in binary mode. Don't call @code{fclose} on the returned file; 224*818008ffSmiodit will be closed by @code{pex_free}. 225*818008ffSmiod 226*818008ffSmiod@end deftypefn 227*818008ffSmiod 228*818008ffSmiod 229*818008ffSmiod@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector}) 230*818008ffSmiod 231*818008ffSmiodReturns the exit status of all programs run using @var{obj}. 232*818008ffSmiod@var{count} is the number of results expected. The results will be 233*818008ffSmiodplaced into @var{vector}. The results are in the order of the calls 234*818008ffSmiodto @code{pex_run}. Returns 0 on error, 1 on success. 235*818008ffSmiod 236*818008ffSmiod@end deftypefn 237*818008ffSmiod 238*818008ffSmiod@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector}) 239*818008ffSmiod 240*818008ffSmiodReturns the process execution times of all programs run using 241*818008ffSmiod@var{obj}. @var{count} is the number of results expected. The 242*818008ffSmiodresults will be placed into @var{vector}. The results are in the 243*818008ffSmiodorder of the calls to @code{pex_run}. Returns 0 on error, 1 on 244*818008ffSmiodsuccess. 245*818008ffSmiod 246*818008ffSmiod@code{struct pex_time} has the following fields of the type 247*818008ffSmiod@code{unsigned long}: @code{user_seconds}, 248*818008ffSmiod@code{user_microseconds}, @code{system_seconds}, 249*818008ffSmiod@code{system_microseconds}. On systems which do not support reporting 250*818008ffSmiodprocess times, all the fields will be set to @code{0}. 251*818008ffSmiod 252*818008ffSmiod@end deftypefn 253*818008ffSmiod 254*818008ffSmiod@deftypefn Extension void pex_free (struct pex_obj @var{obj}) 255*818008ffSmiod 256*818008ffSmiodClean up and free all data associated with @var{obj}. 257*818008ffSmiod 258*818008ffSmiod@end deftypefn 259*818008ffSmiod 260*818008ffSmiod@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}) 261*818008ffSmiod 262*818008ffSmiodAn interface to permit the easy execution of a 263*818008ffSmiodsingle program. The return value and most of the parameters are as 264*818008ffSmiodfor a call to @code{pex_run}. @var{flags} is restricted to a 265*818008ffSmiodcombination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and 266*818008ffSmiod@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if 267*818008ffSmiod@code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will 268*818008ffSmiodbe set to the exit status of the program. 269*818008ffSmiod 270*818008ffSmiod@end deftypefn 271*818008ffSmiod 272*818008ffSmiod@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 @var{flags}) 273*818008ffSmiod 274*818008ffSmiodThis is the old interface to execute one or more programs. It is 275*818008ffSmiodstill supported for compatibility purposes, but is no longer 276*818008ffSmioddocumented. 27732d62142Sespie 27832d62142Sespie@end deftypefn 27932d62142Sespie 28032d62142Sespie@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) 28132d62142Sespie 282*818008ffSmiodAnother part of the old execution interface. 28332d62142Sespie 28432d62142Sespie@end deftypefn 285