merge from gcc
[binutils.git] / libiberty / pexecute.txh
blob461ff33d018c7ea52ce94933ad81a4fc28f24412
1 @deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
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.
7 @var{flags} is a bitwise combination of the following:
9 @table @code
11 @vindex PEX_RECORD_TIMES
12 @item PEX_RECORD_TIMES
13 Record subprocess times if possible.
15 @vindex PEX_USE_PIPES
16 @item PEX_USE_PIPES
17 Use pipes for communication between processes, if possible.
19 @vindex PEX_SAVE_TEMPS
20 @item PEX_SAVE_TEMPS
21 Don't delete temporary files used for communication between
22 processes.
24 @end table
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.
30 @end deftypefn
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})
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.
38 @var{obj} is returned by a previous call to @code{pex_init}.
40 @var{flags} is a bitwise combination of the following:
42 @table @code
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.  Do @emph{not}
50 set this bit 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}.
54 @vindex PEX_SEARCH
55 @item PEX_SEARCH
56 Search for the program using the user's executable search path.
58 @vindex PEX_SUFFIX
59 @item PEX_SUFFIX
60 @var{outname} is a suffix.  See the description of @var{outname},
61 below.
63 @vindex PEX_STDERR_TO_STDOUT
64 @item PEX_STDERR_TO_STDOUT
65 Send the program's standard error to standard output, if possible.
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
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}.
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:
86 @enumerate
87 @item
88 if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
89 was set in the call to @code{pex_init}, and the system supports pipes
91 @item
92 if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
93 @code{NULL}
94 @end enumerate
96 @noindent
97 Otherwise the code will use a file to hold standard
98 output.  If @code{PEX_LAST} is not set, this file is considered to be
99 a temporary file, and it will be removed when no longer needed, unless
100 @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
102 There are two cases to consider when setting the name of the file to
103 hold standard output.
105 @enumerate
106 @item
107 @code{PEX_SUFFIX} is set in @var{flags}.  In this case
108 @var{outname} may not be @code{NULL}.  If the @var{tempbase} parameter
109 to @code{pex_init} was not @code{NULL}, then the output file name is
110 the concatenation of @var{tempbase} and @var{outname}.  If
111 @var{tempbase} was @code{NULL}, then the output file name is a random
112 file name ending in @var{outname}.
114 @item
115 @code{PEX_SUFFIX} was not set in @var{flags}.  In this
116 case, if @var{outname} is not @code{NULL}, it is used as the output
117 file name.  If @var{outname} is @code{NULL}, and @var{tempbase} was
118 not NULL, the output file name is randomly chosen using
119 @var{tempbase}.  Otherwise the output file name is chosen completely
120 at random.
121 @end enumerate
123 @var{errname} is the file name to use for standard error output.  If
124 it is @code{NULL}, standard error is the same as the caller's.
125 Otherwise, standard error is written to the named file.
127 On an error return, the code sets @code{*@var{err}} to an @code{errno}
128 value, or to 0 if there is no relevant @code{errno}.
130 @end deftypefn
132 @deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
134 Returns a @code{FILE} pointer which may be used to read the standard
135 output of the last program in the pipeline.  When this is used,
136 @code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
137 this is called, @code{pex_run} may no longer be called with the same
138 @var{obj}.  @var{binary} should be non-zero if the file should be
139 opened in binary mode.  Don't call @code{fclose} on the returned file;
140 it will be closed by @code{pex_free}.
142 @end deftypefn
144 @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector})
146 Returns the exit status of all programs run using @var{obj}.
147 @var{count} is the number of results expected.  The results will be
148 placed into @var{vector}.  The results are in the order of the calls
149 to @code{pex_run}.  Returns 0 on error, 1 on success.
151 @end deftypefn
153 @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector})
155 Returns the process execution times of all programs run using
156 @var{obj}.  @var{count} is the number of results expected.  The
157 results will be placed into @var{vector}.  The results are in the
158 order of the calls to @code{pex_run}.  Returns 0 on error, 1 on
159 success.
161 @code{struct pex_time} has the following fields of the type
162 @code{unsigned long}: @code{user_seconds},
163 @code{user_microseconds}, @code{system_seconds},
164 @code{system_microseconds}.  On systems which do not support reporting
165 process times, all the fields will be set to @code{0}.
167 @end deftypefn
169 @deftypefn Extension void pex_free (struct pex_obj @var{obj})
171 Clean up and free all data associated with @var{obj}.
173 @end deftypefn
175 @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})
177 An interface to permit the easy execution of a
178 single program.  The return value and most of the parameters are as
179 for a call to @code{pex_run}.  @var{flags} is restricted to a
180 combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
181 @code{PEX_BINARY_OUTPUT}.  @var{outname} is interpreted as if
182 @code{PEX_LAST} were set.  On a successful return, @code{*@var{status}} will
183 be set to the exit status of the program.
185 @end deftypefn
187 @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)
189 This is the old interface to execute one or more programs.  It is
190 still supported for compatibility purposes, but is no longer
191 documented.
193 @end deftypefn
195 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
197 Another part of the old execution interface.
199 @end deftypefn