From 8eff378c612e592a3cc9e161e382c57e105be6f5 Mon Sep 17 00:00:00 2001 From: Jim Blandy Date: Wed, 12 Apr 2006 06:29:21 +0000 Subject: pex-common.c (pex_input_file, [...]): New functions. src/libiberty/ChangeLog: 2006-03-29 Jim Blandy * pex-common.c (pex_input_file, pex_input_pipe): New functions. (pex_init_common): Initialize obj->input_file. (pex_run): Close any file opened by pex_input_file. * pexecute.txh (pex_input_file, pex_input_pipe): New docs. * pex-common.h (struct pex_obj): New field input_file. (struct pex_funcs): New function ptr fdopenw. * pex-unix.c (pex_unix_fdopenw): New function. (funcs): List it as our fdopenw function. * pex-win32.c (pex_win32_fdopenw): New function. (funcs): List it as our fdopenw function. * pex-djgpp.c (funcs): Leave fdopenw null. * pex-msdos (funcs): Same. * functions.texi: Regenerated. src/include/ChangeLog: 2006-04-10 Jim Blandy * libiberty.h (pex_input_file, pex_input_pipe): New declarations. From-SVN: r112883 --- libiberty/pexecute.txh | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) (limited to 'libiberty/pexecute.txh') diff --git a/libiberty/pexecute.txh b/libiberty/pexecute.txh index 461ff33..7d45576 100644 --- a/libiberty/pexecute.txh +++ b/libiberty/pexecute.txh @@ -1,3 +1,4 @@ +@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 @@ -129,6 +130,67 @@ value, or to 0 if there is no relevant @code{errno}. @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 -- cgit v1.1