-@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
+@c -*- mode: texinfo -*-
+@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @
+ const char *@var{pname}, const char *@var{tempbase})
Prepare to execute one or more programs, with standard output of each
program fed to standard input of the next. This is a system
@end deftypefn
-@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})
+@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})
Execute one program in a pipeline. On success this returns
@code{NULL}. On failure it returns an error message, a statically
@vindex PEX_BINARY_INPUT
@vindex PEX_BINARY_OUTPUT
+@vindex PEX_BINARY_ERROR
@item PEX_BINARY_INPUT
@itemx PEX_BINARY_OUTPUT
-The standard input (output) of the program should be read (written) in
+@itemx PEX_BINARY_ERROR
+The standard input (output or error) of the program should be read (written) in
binary mode rather than text mode. These flags are ignored on systems
which do not distinguish binary mode and text mode, such as Unix. For
proper behavior these flags should match appropriately---a call to
@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
call using @code{PEX_BINARY_INPUT}.
+
+@vindex PEX_STDERR_TO_PIPE
+@item PEX_STDERR_TO_PIPE
+Send the program's standard error to a pipe, if possible. This flag
+cannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This
+flag can be specified only on the last program in pipeline.
+
@end table
@var{executable} is the program to execute. @var{argv} is the set of
@end deftypefn
-@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
+@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})
+
+Execute one program in a pipeline, permitting the environment for the
+program to be specified. Behaviour and parameters not listed below are
+as for @code{pex_run}.
+
+@var{env} is the environment for the child process, specified as an array of
+character pointers. Each element of the array should point to a string of the
+form @code{VAR=VALUE}, with the exception of the last element that must be
+@code{NULL}.
+
+@end deftypefn
+
+@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @
+ int @var{flags}, const char *@var{in_name})
+
+Return a stream for a temporary file to pass to the first program in
+the pipeline as input.
+
+The name of the input file is chosen according to the same rules
+@code{pex_run} uses to choose output file names, based on
+@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.
+
+Don't call @code{fclose} on the returned stream; the first call to
+@code{pex_run} closes it automatically.
+
+If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
+binary mode; otherwise, open it in the default mode. Including
+@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
+@end deftypefn
+
+@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @
+ int @var{binary})
+
+Return a stream @var{fp} for a pipe connected to the standard input of
+the first program in the pipeline; @var{fp} is opened for writing.
+You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
+that returned @var{obj}.
+
+You must close @var{fp} using @code{fclose} yourself when you have
+finished writing data to the pipeline.
+
+The file descriptor underlying @var{fp} is marked not to be inherited
+by child processes.
+
+On systems that do not support pipes, this function returns
+@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would
+like to write code that is portable to all systems the @code{pex}
+functions support, consider using @code{pex_input_file} instead.
+
+There are two opportunities for deadlock using
+@code{pex_input_pipe}:
+
+@itemize @bullet
+@item
+Most systems' pipes can buffer only a fixed amount of data; a process
+that writes to a full pipe blocks. Thus, if you write to @file{fp}
+before starting the first process, you run the risk of blocking when
+there is no child process yet to read the data and allow you to
+continue. @code{pex_input_pipe} makes no promises about the
+size of the pipe's buffer, so if you need to write any data at all
+before starting the first process in the pipeline, consider using
+@code{pex_input_file} instead.
+
+@item
+Using @code{pex_input_pipe} and @code{pex_read_output} together
+may also cause deadlock. If the output pipe fills up, so that each
+program in the pipeline is waiting for the next to read more data, and
+you fill the input pipe by writing more data to @var{fp}, then there
+is no way to make progress: the only process that could read data from
+the output pipe is you, but you are blocked on the input pipe.
+
+@end itemize
+
+@end deftypefn
+
+@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @
+ int @var{binary})
Returns a @code{FILE} pointer which may be used to read the standard
output of the last program in the pipeline. When this is used,
@end deftypefn
-@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector})
+@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @
+ int @var{binary})
+
+Returns a @code{FILE} pointer which may be used to read the standard
+error of the last program in the pipeline. When this is used,
+@code{PEX_LAST} should not be used in a call to @code{pex_run}. After
+this is called, @code{pex_run} may no longer be called with the same
+@var{obj}. @var{binary} should be non-zero if the file should be
+opened in binary mode. Don't call @code{fclose} on the returned file;
+it will be closed by @code{pex_free}.
+
+@end deftypefn
+
+
+@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @
+ int @var{count}, int *@var{vector})
Returns the exit status of all programs run using @var{obj}.
@var{count} is the number of results expected. The results will be
@end deftypefn
-@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector})
+@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @
+ int @var{count}, struct pex_time *@var{vector})
Returns the process execution times of all programs run using
@var{obj}. @var{count} is the number of results expected. The
@deftypefn Extension void pex_free (struct pex_obj @var{obj})
-Clean up and free all data associated with @var{obj}.
+Clean up and free all data associated with @var{obj}. If you have not
+yet called @code{pex_get_times} or @code{pex_get_status}, this will
+try to kill the subprocesses.
@end deftypefn
-@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})
+@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})
An interface to permit the easy execution of a
single program. The return value and most of the parameters are as
@end deftypefn
-@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)
+@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})
This is the old interface to execute one or more programs. It is
still supported for compatibility purposes, but is no longer
projects / deliverable / binutils-gdb.git / blobdiff