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