libiberty/pexecute.txh

   1 @deftypefn Extension struct pex_obj *pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
   2
   3 Prepare to execute one or more programs, with standard output of each
   4 program fed to standard input of the next.  This is a system
   5 independent interface to execute a pipeline.
   6
   7 @var{flags} is a bitwise combination of the following:
   8
   9 @table @code
  10
  11 @vindex PEX_RECORD_TIMES
  12 @item PEX_RECORD_TIMES
  13 Record subprocess times if possible.
  14
  15 @vindex PEX_USE_PIPES
  16 @item PEX_USE_PIPES
  17 Use pipes for communication between processes, if possible.
  18
  19 @vindex PEX_SAVE_TEMPS
  20 @item PEX_SAVE_TEMPS
  21 Don't delete temporary files used for communication between
  22 processes.
  23
  24 @end table
  25
  26 @var{pname} is the name of program to be executed, used in error
  27 messages.  @var{tempbase} is a base name to use for any required
  28 temporary files; it may be @code{NULL} to use a randomly chosen name.
  29
  30 @end deftypefn
  31
  32 @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})
  33
  34 Execute one program in a pipeline.  On success this returns
  35 @code{NULL}.  On failure it returns an error message, a statically
  36 allocated string.
  37
  38 @var{obj} is returned by a previous call to @code{pex_init}.
  39
  40 @var{flags} is a bitwise combination of the following:
  41
  42 @table @code
  43
  44 @vindex PEX_LAST
  45 @item PEX_LAST
  46 This must be set on the last program in the pipeline.  In particular,
  47 it should be set when executing a single program.  The standard output
  48 of the program will be sent to @var{outname}, or, if @var{outname} is
  49 @code{NULL}, to the standard output of the calling program.  This
  50 should not be set if you want to call @code{pex_read_output}
  51 (described below).  After a call to @code{pex_run} with this bit set,
  52 @var{pex_run} may no longer be called with the same @var{obj}.
  53
  54 @vindex PEX_SEARCH
  55 @item PEX_SEARCH
  56 Search for the program using the user's executable search path.
  57
  58 @vindex PEX_SUFFIX
  59 @item PEX_SUFFIX
  60 @var{outname} is a suffix.  See the description of @var{outname},
  61 below.
  62
  63 @vindex PEX_STDERR_TO_STDOUT
  64 @item PEX_STDERR_TO_STDOUT
  65 Send the program's standard error to standard output, if possible.
  66
  67 @vindex PEX_BINARY_INPUT
  68 @vindex PEX_BINARY_OUTPUT
  69 @item PEX_BINARY_INPUT
  70 @itemx PEX_BINARY_OUTPUT
  71 The standard input (output) of the program should be read (written) in
  72 binary mode rather than text mode.  These flags are ignored on systems
  73 which do not distinguish binary mode and text mode, such as Unix.  For
  74 proper behavior these flags should match appropriately--a call to
  75 @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
  76 call using @code{PEX_BINARY_INPUT}.
  77 @end table
  78
  79 @var{executable} is the program to execute.  @var{argv} is the set of
  80 arguments to pass to the program; normally @code{@var{argv}[0]} will
  81 be a copy of @var{executable}.
  82
  83 @var{outname} is used to set the name of the file to use for standard
  84 output.  There are two cases in which no output file will be used: 1)
  85 if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
  86 was set in the call to @code{pex_init}, and the system supports pipes;
  87 2) if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
  88 @code{NULL}.  Otherwise the code will use a file to hold standard
  89 output.  If @code{PEX_LAST} is not set, this file is considered to be
  90 a temporary file, and it will be removed when no longer needed, unless
  91 @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
  92
  93 There are two cases to consider when setting the name of the file to
  94 hold standard output.
  95
  96 First case: @code{PEX_SUFFIX} is set in @var{flags}.  In this case
  97 @var{outname} may not be @code{NULL}.  If the @var{tempbase} parameter
  98 to @code{pex_init} was not @code{NULL}, then the output file name is
  99 the concatenation of @var{tempbase} and @var{outname}.  If
 100 @var{tempbase} was @code{NULL}, then the output file name is a random
 101 file name ending in @var{outname}.
 102
 103 Second case: @code{PEX_SUFFIX} was not set in @var{flags}.  In this
 104 case, if @var{outname} is not @code{NULL}, it is used as the output
 105 file name.  If @var{outname} is @code{NULL}, and @var{tempbase} was
 106 not NULL, the output file name is randomly chosen using
 107 @var{tempbase}.  Otherwise the output file name is chosen completely
 108 at random.
 109
 110 @var{errname} is the file name to use for standard error output.  If
 111 it is @code{NULL}, standard error is the same as the caller.
 112 Otherwise, standard error is written to the named file.
 113
 114 On an error return, the code sets @code{*@var{err}} to an @code{errno}
 115 value, or to 0 if there is no relevant @code{errno}.
 116
 117 @end deftypefn
 118
 119 @deftypefn Extension FILE * pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
 120
 121 Returns a @code{FILE} pointer which may be used to read the standard
 122 output of the last program in the pipeline.  When this is used,
 123 @code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
 124 this is called, @code{pex_run} may no longer be called with the same
 125 @var{obj}.  @var{binary} should be non-zero if the file should be
 126 opened in binary mode.  Don't call @code{fclose} on the returned file;
 127 it will be closed by @code{pex_free}.
 128
 129 @end deftypefn
 130
 131 @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector})
 132
 133 Returns the exit status of all programs run using @var{obj}.
 134 @var{count} is the number of results expected.  The results will be
 135 placed into @var{vector}.  The results are in the order of the calls
 136 to @code{pex_run}.  Returns 0 on error, 1 on success.
 137
 138 @end deftypefn
 139
 140 @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector})
 141
 142 Returns the process execution times of all programs run using
 143 @var{obj}.  @var{count} is the number of results expected.  The
 144 results will be placed into @var{vector}.  The results are in the
 145 order of the calls to @code{pex_run}.  Returns 0 on error, 1 on
 146 success.
 147
 148 @code{struct pex_time} has the following fields: @code{user_seconds},
 149 @code{user_microseconds}, @code{system_seconds},
 150 @code{system_microseconds}.  On systems which do not support reporting
 151 process times, all the fields will be set to @code{0}.
 152
 153 @end deftypefn
 154
 155 @deftypefn Extension void pex_free (struct pex_obj @var{obj})
 156
 157 Clean up and free all data associated with @var{obj}.
 158
 159 @end deftypefn
 160
 161 @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})
 162
 163 An interface to @code{pex_init} to permit the easy execution of a
 164 single program.  The return value and most of the parameters are as
 165 for a call to @code{pex_run}.  @var{flags} is restricted to a
 166 combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
 167 @code{PEX_BINARY_OUTPUT}.  @var{outname} is interpreted as if
 168 @code{PEX_LAST} were set.  On a successful return, *@var{status} will
 169 be set to the exit status of the program.
 170
 171 @end deftypefn
 172
 173 @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)
 174
 175 This is the old interface to execute one or more programs.  It is
 176 still supported for compatibility purposes, but is no longer
 177 documented.
 178
 179 @end deftypefn
 180
 181 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
 182
 183 Another part of the old execution interface.
 184
 185 @end deftypefn