diff options
Diffstat (limited to 'libiberty/functions.texi')
| -rw-r--r-- | libiberty/functions.texi | 258 |
1 files changed, 197 insertions, 61 deletions
diff --git a/libiberty/functions.texi b/libiberty/functions.texi index 79c8a35b3ca..a886b885704 100644 --- a/libiberty/functions.texi +++ b/libiberty/functions.texi @@ -3,7 +3,7 @@ @c Edit the *.c files, configure with --enable-maintainer-mode, @c and let gather-docs build you a new copy. -@c safe-ctype.c:24 +@c safe-ctype.c:25 @defvr Extension HOST_CHARSET This macro indicates the basic character set and encoding used by the host: more precisely, the encoding used for character constants in @@ -25,6 +25,139 @@ 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}) @@ -43,7 +176,7 @@ the possibility of a GCC built-in function. @end deftypefn -@c asprintf.c:33 +@c asprintf.c:29 @deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...) Like @code{sprintf}, but instead of passing a pointer to a buffer, you @@ -104,7 +237,7 @@ is respectively less than, matching, or greater than the array member. @end deftypefn -@c argv.c:139 +@c argv.c:121 @deftypefn Extension char** buildargv (char *@var{sp}) Given a pointer to a string, parse the string extracting fields @@ -158,7 +291,7 @@ not recommended. @end deftypefn -@c make-temp-file.c:88 +@c make-temp-file.c:87 @deftypefn Replacement char* choose_tmpdir () Returns a pointer to a directory path suitable for creating temporary @@ -185,7 +318,7 @@ pointer encountered. Pointers to empty strings are ignored. @end deftypefn -@c argv.c:65 +@c argv.c:49 @deftypefn Extension char** dupargv (char **@var{vector}) Duplicate an argument vector. Simply scans through @var{vector}, @@ -288,7 +421,7 @@ Ignores case when performing the comparison. @end deftypefn -@c argv.c:111 +@c argv.c:94 @deftypefn Extension void freeargv (char **@var{vector}) Free an argument vector that was built using @code{buildargv}. Simply @@ -412,7 +545,7 @@ struct qelem @{ @end deftypefn -@c safe-ctype.c:45 +@c safe-ctype.c:46 @deffn Extension ISALPHA (@var{c}) @deffnx Extension ISALNUM (@var{c}) @deffnx Extension ISBLANK (@var{c}) @@ -462,7 +595,7 @@ false for characters with numeric values from 128 to 255. @end itemize @end deffn -@c safe-ctype.c:94 +@c safe-ctype.c:95 @deffn Extension ISIDNUM (@var{c}) @deffnx Extension ISIDST (@var{c}) @deffnx Extension IS_VSPACE (@var{c}) @@ -535,7 +668,7 @@ relative prefix can be found, return @code{NULL}. @end deftypefn -@c make-temp-file.c:138 +@c make-temp-file.c:137 @deftypefn Replacement char* make_temp_file (const char *@var{suffix}) Return a temporary file name (as a string) or @code{NULL} if unable to @@ -618,46 +751,62 @@ reading and writing. @end deftypefn -@c pexecute.txh:1 -@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) +@c pexecute.txh:155 +@deftypefn Extension void pex_free (struct pex_obj @var{obj}) -Executes a program. +Clean up and free all data associated with @var{obj}. -@var{program} and @var{argv} are the arguments to -@code{execv}/@code{execvp}. +@end deftypefn -@var{this_pname} is name of the calling program (i.e., @code{argv[0]}). +@c pexecute.txh:131 +@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector}) -@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}. +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. -(@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. +@end deftypefn -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. +@c pexecute.txh:140 +@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector}) -The result is the @code{WEXITSTATUS} on systems like MS-DOS where we -@code{spawn} and wait for the child here. +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. -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. +@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}. @end deftypefn -@c strsignal.c:546 +@c pexecute.txh:119 +@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 + +@c pexecute.txh:173 +@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 +still supported for compatibility purposes, but is no longer +documented. + +@end deftypefn + +@c strsignal.c:539 @deftypefn Supplemental void psignal (unsigned @var{signo}, char *@var{message}) Print @var{message} to the standard error, followed by a colon, @@ -676,23 +825,10 @@ name is unset/removed. @end deftypefn -@c pexecute.txh:39 +@c pexecute.txh:181 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) -Waits for a program started by @code{pexecute} to finish. - -@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. - -The result is the pid of the child reaped, or -1 for failure -(@code{errno} says why). - -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. +Another part of the old execution interface. @end deftypefn @@ -711,7 +847,7 @@ control over the state of the random number generator. @end deftypefn -@c concat.c:177 +@c concat.c:167 @deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL}) Same as @code{concat}, except that if @var{optr} is not @code{NULL} it @@ -754,7 +890,7 @@ environment. This implementation is not safe for multithreaded code. @end deftypefn -@c strsignal.c:352 +@c strsignal.c:348 @deftypefn Extension int signo_max (void) Returns the maximum signal value for which a corresponding symbolic @@ -845,7 +981,7 @@ Returns a pointer to a copy of @var{s} in memory obtained from @end deftypefn -@c strerror.c:671 +@c strerror.c:670 @deftypefn Replacement {const char*} strerrno (int @var{errnum}) Given an error number returned from a system call (typically returned @@ -919,7 +1055,7 @@ null character, the results are undefined. @end deftypefn -@c strsignal.c:387 +@c strsignal.c:383 @deftypefn Supplemental {const char *} strsignal (int @var{signo}) Maps an signal number to an signal message string, the contents of @@ -940,7 +1076,7 @@ call to @code{strsignal}. @end deftypefn -@c strsignal.c:451 +@c strsignal.c:446 @deftypefn Extension {const char*} strsigno (int @var{signo}) Given an signal number, returns a pointer to a string containing the @@ -982,7 +1118,7 @@ the location referenced by @var{endptr}. @end deftypefn -@c strerror.c:731 +@c strerror.c:729 @deftypefn Extension int strtoerrno (const char *@var{name}) Given the symbolic name of a error number (e.g., @code{EACCES}), map it @@ -1006,7 +1142,7 @@ that the converted value is unsigned. @end deftypefn -@c strsignal.c:506 +@c strsignal.c:500 @deftypefn Extension int strtosigno (const char *@var{name}) Given the symbolic name of a signal, map it to a signal number. If no @@ -1035,7 +1171,7 @@ was made to unlink the file because it is special. @end deftypefn -@c vasprintf.c:51 +@c vasprintf.c:47 @deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args}) Like @code{vsprintf}, but instead of passing a pointer to a buffer, |