functions.texi

理解和实践操作系统的一本好书

@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

@c pexecute.txh:272
@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:228
@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, int @var{binary})

Returns a @code{FILE} pointer which may be used to read the standard
error 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:216
@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:33
@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
@vindex PEX_BINARY_ERROR
@item PEX_BINARY_INPUT
@itemx PEX_BINARY_OUTPUT
@itemx PEX_BINARY_ERROR
The standard input (output or error) 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}.

@vindex PEX_STDERR_TO_PIPE
@item PEX_STDERR_TO_PIPE
Send the program's standard error to a pipe, if possible.  This flag
cannot be specified together with @code{PEX_STDERR_TO_STDOUT}.  This
flag can be specified only on the last program in pipeline.

@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:142
@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, char * const *@var{env}, int @var{env_size}, const char *@var{outname}, const char *@var{errname}, int *@var{err})

Execute one program in a pipeline, permitting the environment for the
program to be specified.  Behaviour and parameters not listed below are
as for @code{pex_run}.

@var{env} is the environment for the child process, specified as an array of
character pointers.  Each element of the array should point to a string of the
form @code{VAR=VALUE}, with the exception of the last element that must be
@code{NULL}.

@end deftypefn

@c pexecute.txh:284
@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 @var{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 (int @var{signo}, char *@var{message})

Print @var{message} to the standard error, followed by a colon,
followed by the description of the signal specified by @var{signo},
followed by a newline.

@end deftypefn

@c putenv.c:21
@deftypefn Supplemental int putenv (const char *@var{string})

Uses @code{setenv} or @code{unsetenv} to put @var{string} into
the environment or remove it.  If @var{string} is of the form
@samp{name=value} the string is added; if no @samp{=} is present the
name is unset/removed.

@end deftypefn

@c pexecute.txh:292
@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})

Another part of the old execution interface.

@end deftypefn

@c random.c:39
@deftypefn Supplement {long int} random (void)
@deftypefnx Supplement void srandom (unsigned int @var{seed})
@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
@deftypefnx Supplement void* setstate (void *@var{arg_state})

Random number functions.  @code{random} returns a random number in the
range 0 to @code{LONG_MAX}.  @code{srandom} initializes the random
number generator to some starting point determined by @var{seed}
(else, the values returned by @code{random} are always the same for each
run of the program).  @code{initstate} and @code{setstate} allow fine-grained
control over the state of the random number generator.

@end deftypefn

@c concat.c:173
@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
is freed after the string is created.  This is intended to be useful
when you're extending an existing string or building up a string in a
loop:

@example
  str = reconcat (str, "pre-", str, NULL);
@end example

@end deftypefn

@c rename.c:6
@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})

Renames a file from @var{old} to @var{new}.  If @var{new} already
exists, it is removed.

@end deftypefn

@c rindex.c:5
@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})

Returns a pointer to the last occurrence of the character @var{c} in
the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
deprecated in new programs in favor of @code{strrchr}.

@end deftypefn

@c setenv.c:22
@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
@deftypefnx Supplemental void unsetenv (const char *@var{name})

@code{setenv} adds @var{name} to the environment with value
@var{value}.  If the name was already present in the environment,
the new value will be stored only if @var{overwrite} is nonzero.
The companion @code{unsetenv} function removes @var{name} from the
environment.  This implementation is not safe for multithreaded code.

@end deftypefn

@c strsignal.c:348
@deftypefn Extension int signo_max (void)

Returns the maximum signal value for which a corresponding symbolic
name or message is available.  Note that in the case where we use the
@code{sys_siglist} supplied by the system, it is possible for there to
be more symbolic names than messages, or vice versa.  In fact, the
manual page for @code{psignal(3b)} explicitly warns that one should
check the size of the table (@code{NSIG}) before indexing it, since
new signal codes may be added to the system before they are added to
the table.  Thus @code{NSIG} might be smaller than value implied by
the largest signo value defined in @code{<signal.h>}.

We return the maximum value that can be used to obtain a meaningful
symbolic name or message.

@end deftypefn

@c sigsetmask.c:8
@deftypefn Supplemental int sigsetmask (int @var{set})

Sets the signal mask to the one provided in @var{set} and returns
the old mask (which, for libiberty's implementation, will always
be the value @code{1}).

@end deftypefn

@c snprintf.c:28
@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...)

This function is similar to sprintf, but it will print at most @var{n}
characters.  On error the return value is -1, otherwise it returns the
number of characters that would have been printed had @var{n} been
sufficiently large, regardless of the actual value of @var{n}.  Note
some pre-C99 system libraries do not implement this correctly so users
cannot generally rely on the return value if the system version of
this function is used.

@end deftypefn

@c spaces.c:22
@deftypefn Extension char* spaces (int @var{count})

Returns a pointer to a memory region filled with the specified
number of spaces and null terminated.  The returned pointer is
valid until at least the next call.

@end deftypefn

@c stpcpy.c:23
@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src})

Copies the string @var{src} into @var{dst}.  Returns a pointer to
@var{dst} + strlen(@var{src}).

@end deftypefn

@c stpncpy.c:23
@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len})

Copies the string @var{src} into @var{dst}, copying exactly @var{len}
and padding with zeros if necessary.  If @var{len} < strlen(@var{src})
then return @var{dst} + @var{len}, otherwise returns @var{dst} +
strlen(@var{src}).

@end deftypefn

@c strcasecmp.c:15
@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})

A case-insensitive @code{strcmp}.

@end deftypefn

@c strchr.c:6
@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})

Returns a pointer to the first occurrence of the character @var{c} in
the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
null character, the results are undefined.

@end deftypefn

@c strdup.c:3
@deftypefn Supplemental char* strdup (const char *@var{s})

Returns a pointer to a copy of @var{s} in memory obtained from
@code{malloc}, or @code{NULL} if insufficient memory was available.

@end deftypefn

@c strerror.c:670
@deftypefn Replacement {const char*} strerrno (int @var{errnum})

Given an error number returned from a system call (typically returned
in @code{errno}), returns a pointer to a string containing the
symbolic name of that error number, as found in @code{<errno.h>}.

If the supplied error number is within the valid range of indices for
symbolic names, but no name is available for the particular error
number, then returns the string @samp{Error @var{num}}, where @var{num}
is the error number.

If the supplied error number is not within the range of valid
indices, then returns @code{NULL}.

The contents of the location pointed to are only guaranteed to be
valid until the next call to @code{strerrno}.

@end deftypefn

@c strerror.c:603
@deftypefn Supplemental char* strerror (int @var{errnoval})

Maps an @code{errno} number to an error message string, the contents
of which are implementation defined.  On systems which have the