libiberty/pexecute.txh

   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