ChangeLog
From-SVN: r99736
This commit is contained in:
Andreas Jaeger
parent
d842a495a5
commit
e15bb31bb6
@ -25,139 +25,6 @@ nineteen EBCDIC varying characters is tested; exercise caution.)
|
||||
@end ftable
|
||||
@end defvr
|
||||
|
||||
@c pexecute.txh:1
|
||||
@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
|
||||
independent interface to execute a pipeline.
|
||||
|
||||
@var{flags} is a bitwise combination of the following:
|
||||
|
||||
@table @code
|
||||
|
||||
@vindex PEX_RECORD_TIMES
|
||||
@item PEX_RECORD_TIMES
|
||||
Record subprocess times if possible.
|
||||
|
||||
@vindex PEX_USE_PIPES
|
||||
@item PEX_USE_PIPES
|
||||
Use pipes for communication between processes, if possible.
|
||||
|
||||
@vindex PEX_SAVE_TEMPS
|
||||
@item PEX_SAVE_TEMPS
|
||||
Don't delete temporary files used for communication between
|
||||
processes.
|
||||
|
||||
@end table
|
||||
|
||||
@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
|
||||
|
||||
@c pexecute.txh:161
|
||||
@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
|
||||
|
||||
@c pexecute.txh: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})
|
||||
|
||||
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
|
||||
|
||||
@c alloca.c:26
|
||||
@deftypefn Replacement void* alloca (size_t @var{size})
|
||||
|
||||
@ -363,7 +230,7 @@ and inode numbers.
|
||||
@end deftypefn
|
||||
|
||||
@c fopen_unlocked.c:48
|
||||
@deftypefn Extension FILE * fdopen_unlocked (int @var{fildes}, const char * @var{mode})
|
||||
@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, const char * @var{mode})
|
||||
|
||||
Opens and returns a @code{FILE} pointer via @code{fdopen}. If the
|
||||
operating system supports it, ensure that the stream is setup to avoid
|
||||
@ -432,7 +299,7 @@ Ignores case when performing the comparison.
|
||||
@end deftypefn
|
||||
|
||||
@c fopen_unlocked.c:39
|
||||
@deftypefn Extension FILE * fopen_unlocked (const char *@var{path}, const char * @var{mode})
|
||||
@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, const char * @var{mode})
|
||||
|
||||
Opens and returns a @code{FILE} pointer via @code{fopen}. If the
|
||||
operating system supports it, ensure that the stream is setup to avoid
|
||||
@ -452,7 +319,7 @@ itself.
|
||||
@end deftypefn
|
||||
|
||||
@c fopen_unlocked.c:57
|
||||
@deftypefn Extension FILE * freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream})
|
||||
@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream})
|
||||
|
||||
Opens and returns a @code{FILE} pointer via @code{freopen}. If the
|
||||
operating system supports it, ensure that the stream is setup to avoid
|
||||
@ -781,14 +648,14 @@ reading and writing.
|
||||
|
||||
@end deftypefn
|
||||
|
||||
@c pexecute.txh:155
|
||||
@c pexecute.txh:169
|
||||
@deftypefn Extension void pex_free (struct pex_obj @var{obj})
|
||||
|
||||
Clean up and free all data associated with @var{obj}.
|
||||
|
||||
@end deftypefn
|
||||
|
||||
@c pexecute.txh:131
|
||||
@c pexecute.txh:144
|
||||
@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}.
|
||||
@ -798,7 +665,7 @@ to @code{pex_run}. Returns 0 on error, 1 on success.
|
||||
|
||||
@end deftypefn
|
||||
|
||||
@c pexecute.txh:140
|
||||
@c pexecute.txh:153
|
||||
@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
|
||||
@ -807,15 +674,61 @@ 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.
|
||||
|
||||
@code{struct pex_time} has the following fields: @code{user_seconds},
|
||||
@code{struct pex_time} has the following fields of the type
|
||||
@code{unsigned long}: @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}.
|
||||
|
||||
@end deftypefn
|
||||
|
||||
@c pexecute.txh:119
|
||||
@deftypefn Extension FILE * pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
|
||||
@c pexecute.txh:1
|
||||
@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
|
||||
independent interface to execute a pipeline.
|
||||
|
||||
@var{flags} is a bitwise combination of the following:
|
||||
|
||||
@table @code
|
||||
|
||||
@vindex PEX_RECORD_TIMES
|
||||
@item PEX_RECORD_TIMES
|
||||
Record subprocess times if possible.
|
||||
|
||||
@vindex PEX_USE_PIPES
|
||||
@item PEX_USE_PIPES
|
||||
Use pipes for communication between processes, if possible.
|
||||
|
||||
@vindex PEX_SAVE_TEMPS
|
||||
@item PEX_SAVE_TEMPS
|
||||
Don't delete temporary files used for communication between
|
||||
processes.
|
||||
|
||||
@end table
|
||||
|
||||
@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
|
||||
|
||||
@c pexecute.txh: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})
|
||||
|
||||
An interface 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, @code{*@var{status}} will
|
||||
be set to the exit status of the program.
|
||||
|
||||
@end deftypefn
|
||||
|
||||
@c pexecute.txh:132
|
||||
@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,
|
||||
@ -827,7 +740,108 @@ it will be closed by @code{pex_free}.
|
||||
|
||||
@end deftypefn
|
||||
|
||||
@c pexecute.txh:173
|
||||
@c pexecute.txh: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})
|
||||
|
||||
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. Do @emph{not}
|
||||
set this bit 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:
|
||||
|
||||
@enumerate
|
||||
@item
|
||||
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
|
||||
|
||||
@item
|
||||
if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
|
||||
@code{NULL}
|
||||
@end enumerate
|
||||
|
||||
@noindent
|
||||
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.
|
||||
|
||||
@enumerate
|
||||
@item
|
||||
@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}.
|
||||
|
||||
@item
|
||||
@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.
|
||||
@end enumerate
|
||||
|
||||
@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's.
|
||||
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
|
||||
|
||||
@c pexecute.txh: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)
|
||||
|
||||
This is the old interface to execute one or more programs. It is
|
||||
@ -855,7 +869,7 @@ name is unset/removed.
|
||||
|
||||
@end deftypefn
|
||||
|
||||
@c pexecute.txh:181
|
||||
@c pexecute.txh:195
|
||||
@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
|
||||
|
||||
Another part of the old execution interface.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user