libiberty/pexecute.txh

   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