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