OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [gcc-4.5.1/] [libiberty/] [pexecute.txh] - Blame information for rev 274

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 274 jeremybenn
@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

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.