From b109e79adcb0d7e31737de397f97fa41d1d4e528 Mon Sep 17 00:00:00 2001 From: Ian Lance Taylor Date: Tue, 29 Mar 2005 02:15:24 +0000 Subject: libiberty: * pex-common.c: New file. * pex-one.c: New file. * pexecute.c: New file. * pex-common.h: Include . (struct pex_obj): Define. (struct pex_funcs): Define. (pex_init_common): Declare. * pex-unix.c: Rewrite. * pex-win32.c: Rewrite. * pex-djgpp.c: Rewrite. * pex-msdos.c: Rewrite. * testsuite/text-pexecute.c: New file. * pexecute.txh: Rewrite. * configure.ac: Check for wait3 and wait4. Set CHECK to really-check rather than check-cplus-dem. * functions.texi: Rebuild. * Makefile.in: Rebuild dependencies. (CFILES): Add pexecute.c, pex-common.c, pex-one.c. (REQUIRED_OFILES): Add pexecute.o, pex-common.o, pex-one.o. * testsuite/Makefile.in (really-check): New target. (check-pexecute, test-pexecute): New targets. * configure: Rebuild. include: * libiberty.h: Include . (PEX_RECORD_TIMES, PEX_USE_PIPES, PEX_SAVE_TEMPS): Define. (PEX_LAST, PEX_SEARCH, PEX_SUFFIX, PEX_STDERR_TO_STDOUT): Define. (PEX_BINARY_INPUT, PEX_BINARY_OUTPUT): Define. (pex_init, pex_run, pex_read_output): Declare. (pex_get_status, pex_get_times, pex_free, pex_one): Declare. (struct pex_time): Define. --- libiberty/pexecute.txh | 208 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 165 insertions(+), 43 deletions(-) (limited to 'libiberty/pexecute.txh') diff --git a/libiberty/pexecute.txh b/libiberty/pexecute.txh index 269f031..c06d55c 100644 --- a/libiberty/pexecute.txh +++ b/libiberty/pexecute.txh @@ -1,63 +1,185 @@ -@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 struct pex_obj *pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase}) -Executes a program. +Prepare to execute one or more programs, with standard output of each +program fed to standard input of the next. This is a system +independent interface to execute a pipeline. -@var{program} and @var{argv} are the arguments to -@code{execv}/@code{execvp}. +@var{flags} is a bitwise combination of the following: -@var{this_pname} is name of the calling program (i.e., @code{argv[0]}). +@table @code -@var{temp_base} is the path name, sans suffix, of a temporary file to -use if needed. This is currently only needed for MS-DOS ports that -don't use @code{go32} (do any still exist?). Ports that don't need it -can pass @code{NULL}. +@vindex PEX_RECORD_TIMES +@item PEX_RECORD_TIMES +Record subprocess times if possible. -(@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH} -should be searched (??? It's not clear that GCC passes this flag -correctly). (@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the -first process in chain. (@code{@var{flags} & PEXECUTE_FIRST}) is -nonzero for the last process in chain. The first/last flags could be -simplified to only mark the last of a chain of processes but that -requires the caller to always mark the last one (and not give up -early if some error occurs). It's more robust to require the caller -to mark both ends of the chain. +@vindex PEX_USE_PIPES +@item PEX_USE_PIPES +Use pipes for communication between processes, if possible. -The result is the pid on systems like Unix where we -@code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we -use @code{spawn}. It is up to the caller to wait for the child. +@vindex PEX_SAVE_TEMPS +@item PEX_SAVE_TEMPS +Don't delete temporary files used for communication between +processes. -The result is the @code{WEXITSTATUS} on systems like MS-DOS where we -@code{spawn} and wait for the child here. +@end table -Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the -text of the error message with an optional argument (if not needed, -@var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned. -@code{errno} is available to the caller to use. +@var{pname} is the name of program to be executed, used in error +messages. @var{tempbase} is a base name to use for any required +temporary files; it may be @code{NULL} to use a randomly chosen name. @end deftypefn -@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) +@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 +allocated string. + +@var{obj} is returned by a previous call to @code{pex_init}. + +@var{flags} is a bitwise combination of the following: + +@table @code + +@vindex PEX_LAST +@item PEX_LAST +This must be set on the last program in the pipeline. In particular, +it should be set when executing a single program. The standard output +of the program will be sent to @var{outname}, or, if @var{outname} is +@code{NULL}, to the standard output of the calling program. This +should not be set if you want to call @code{pex_read_output} +(described below). After a call to @code{pex_run} with this bit set, +@var{pex_run} may no longer be called with the same @var{obj}. + +@vindex PEX_SEARCH +@item PEX_SEARCH +Search for the program using the user's executable search path. + +@vindex PEX_SUFFIX +@item PEX_SUFFIX +@var{outname} is a suffix. See the description of @var{outname}, +below. + +@vindex PEX_STDERR_TO_STDOUT +@item PEX_STDERR_TO_STDOUT +Send the program's standard error to standard output, if possible. + +@vindex PEX_BINARY_INPUT +@vindex PEX_BINARY_OUTPUT +@item PEX_BINARY_INPUT +@itemx PEX_BINARY_OUTPUT +The standard input (output) 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}. +@end table + +@var{executable} is the program to execute. @var{argv} is the set of +arguments to pass to the program; normally @code{@var{argv}[0]} will +be a copy of @var{executable}. + +@var{outname} is used to set the name of the file to use for standard +output. There are two cases in which no output file will be used: 1) +if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} +was set in the call to @code{pex_init}, and the system supports pipes; +2) if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is +@code{NULL}. Otherwise the code will use a file to hold standard +output. If @code{PEX_LAST} is not set, this file is considered to be +a temporary file, and it will be removed when no longer needed, unless +@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. + +There are two cases to consider when setting the name of the file to +hold standard output. + +First case: @code{PEX_SUFFIX} is set in @var{flags}. In this case +@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter +to @code{pex_init} was not @code{NULL}, then the output file name is +the concatenation of @var{tempbase} and @var{outname}. If +@var{tempbase} was @code{NULL}, then the output file name is a random +file name ending in @var{outname}. + +Second case: @code{PEX_SUFFIX} was not set in @var{flags}. In this +case, if @var{outname} is not @code{NULL}, it is used as the output +file name. If @var{outname} is @code{NULL}, and @var{tempbase} was +not NULL, the output file name is randomly chosen using +@var{tempbase}. Otherwise the output file name is chosen completely +at random. + +@var{errname} is the file name to use for standard error output. If +it is @code{NULL}, standard error is the same as the caller. +Otherwise, standard error is written to the named file. + +On an error return, the code sets @code{*@var{err}} to an @code{errno} +value, or to 0 if there is no relevant @code{errno}. + +@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, +@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 +placed into @var{vector}. The results are in the order of the calls +to @code{pex_run}. Returns 0 on error, 1 on success. + +@end deftypefn + +@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector}) -Waits for a program started by @code{pexecute} to finish. +Returns the process execution times of all programs run using +@var{obj}. @var{count} is the number of results expected. The +results will be placed into @var{vector}. The results are in the +order of the calls to @code{pex_run}. Returns 0 on error, 1 on +success. -@var{pid} is the process id of the task to wait for. @var{status} is -the `status' argument to wait. @var{flags} is currently unused -(allows future enhancement without breaking upward compatibility). -Pass 0 for now. +@code{struct pex_time} has the following fields: @code{user_seconds}, +@code{user_microseconds}, @code{system_seconds}, +@code{system_microseconds}. On systems which do not support reporting +process times, all the fields will be set to @code{0}. -The result is the pid of the child reaped, or -1 for failure -(@code{errno} says why). +@end deftypefn + +@deftypefn Extension void pex_free (struct pex_obj @var{obj}) -On systems that don't support waiting for a particular child, -@var{pid} is ignored. On systems like MS-DOS that don't really -multitask @code{pwait} is just a mechanism to provide a consistent -interface for the caller. +Clean up and free all data associated with @var{obj}. @end deftypefn -@undocumented pfinish +@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 @code{pex_init} to permit the easy execution of a +single program. The return value and most of the parameters are as +for a call to @code{pex_run}. @var{flags} is restricted to a +combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and +@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if +@code{PEX_LAST} were set. On a successful return, *@var{status} will +be set to the exit status of the program. + +@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) -pfinish: finish generation of script +This is the old interface to execute one or more programs. It is +still supported for compatibility purposes, but is no longer +documented. -pfinish is necessary for systems like MPW where a script is generated -that runs the requested programs. +@end deftypefn + +@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) + +Another part of the old execution interface. + +@end deftypefn -- cgit v1.1