diff options
Diffstat (limited to 'libiberty/functions.texi')
| -rw-r--r-- | libiberty/functions.texi | 302 |
1 files changed, 158 insertions, 144 deletions
diff --git a/libiberty/functions.texi b/libiberty/functions.texi index ac97726..d863779 100644 --- a/libiberty/functions.texi +++ b/libiberty/functions.texi @@ -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. |