functions.texi

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

@end deftypefn

@c getpwd.c:5
@deftypefn Supplemental char* getpwd (void)

Returns the current working directory.  This implementation caches the
result on the assumption that the process will not call @code{chdir}
between calls to @code{getpwd}.

@end deftypefn

@c gettimeofday.c:12
@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz})

Writes the current time to @var{tp}.  This implementation requires
that @var{tz} be NULL.  Returns 0 on success, -1 on failure.

@end deftypefn

@c hex.c:33
@deftypefn Extension void hex_init (void)

Initializes the array mapping the current character set to
corresponding hex values.  This function must be called before any
call to @code{hex_p} or @code{hex_value}.  If you fail to call it, a
default ASCII-based table will normally be used on ASCII systems.

@end deftypefn

@c hex.c:42
@deftypefn Extension int hex_p (int @var{c})

Evaluates to non-zero if the given character is a valid hex character,
or zero if it is not.  Note that the value you pass will be cast to
@code{unsigned char} within the macro.

@end deftypefn

@c hex.c:50
@deftypefn Extension {unsigned int} hex_value (int @var{c})

Returns the numeric equivalent of the given character when interpreted
as a hexadecimal digit.  The result is undefined if you pass an
invalid hex digit.  Note that the value you pass will be cast to
@code{unsigned char} within the macro.

The @code{hex_value} macro returns @code{unsigned int}, rather than
signed @code{int}, to make it easier to use in parsing addresses from
hex dump files: a signed @code{int} would be sign-extended when
converted to a wider unsigned type --- like @code{bfd_vma}, on some
systems.

@end deftypefn

@c index.c:5
@deftypefn Supplemental char* index (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.  The use of @code{index} is
deprecated in new programs in favor of @code{strchr}.

@end deftypefn

@c insque.c:6
@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred})
@deftypefnx Supplemental void remque (struct qelem *@var{elem})

Routines to manipulate queues built from doubly linked lists.  The
@code{insque} routine inserts @var{elem} in the queue immediately
after @var{pred}.  The @code{remque} routine removes @var{elem} from
its containing queue.  These routines expect to be passed pointers to
structures which have as their first members a forward pointer and a
back pointer, like this prototype (although no prototype is provided):

@example
struct qelem @{
  struct qelem *q_forw;
  struct qelem *q_back;
  char q_data[];
@};
@end example

@end deftypefn

@c safe-ctype.c:46
@deffn  Extension ISALPHA  (@var{c})
@deffnx Extension ISALNUM  (@var{c})
@deffnx Extension ISBLANK  (@var{c})
@deffnx Extension ISCNTRL  (@var{c})
@deffnx Extension ISDIGIT  (@var{c})
@deffnx Extension ISGRAPH  (@var{c})
@deffnx Extension ISLOWER  (@var{c})
@deffnx Extension ISPRINT  (@var{c})
@deffnx Extension ISPUNCT  (@var{c})
@deffnx Extension ISSPACE  (@var{c})
@deffnx Extension ISUPPER  (@var{c})
@deffnx Extension ISXDIGIT (@var{c})

These twelve macros are defined by @file{safe-ctype.h}.  Each has the
same meaning as the corresponding macro (with name in lowercase)
defined by the standard header @file{ctype.h}.  For example,
@code{ISALPHA} returns true for alphabetic characters and false for
others.  However, there are two differences between these macros and
those provided by @file{ctype.h}:

@itemize @bullet
@item These macros are guaranteed to have well-defined behavior for all 
values representable by @code{signed char} and @code{unsigned char}, and
for @code{EOF}.

@item These macros ignore the current locale; they are true for these
fixed sets of characters:
@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada}
@item @code{ALPHA}  @tab @kbd{A-Za-z}
@item @code{ALNUM}  @tab @kbd{A-Za-z0-9}
@item @code{BLANK}  @tab @kbd{space tab}
@item @code{CNTRL}  @tab @code{!PRINT}
@item @code{DIGIT}  @tab @kbd{0-9}
@item @code{GRAPH}  @tab @code{ALNUM || PUNCT}
@item @code{LOWER}  @tab @kbd{a-z}
@item @code{PRINT}  @tab @code{GRAPH ||} @kbd{space}
@item @code{PUNCT}  @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?}
@item @code{SPACE}  @tab @kbd{space tab \n \r \f \v}
@item @code{UPPER}  @tab @kbd{A-Z}
@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f}
@end multitable

Note that, if the host character set is ASCII or a superset thereof,
all these macros will return false for all values of @code{char} outside
the range of 7-bit ASCII.  In particular, both ISPRINT and ISCNTRL return
false for characters with numeric values from 128 to 255.
@end itemize
@end deffn

@c safe-ctype.c:95
@deffn  Extension ISIDNUM         (@var{c})
@deffnx Extension ISIDST          (@var{c})
@deffnx Extension IS_VSPACE       (@var{c})
@deffnx Extension IS_NVSPACE      (@var{c})
@deffnx Extension IS_SPACE_OR_NUL (@var{c})
@deffnx Extension IS_ISOBASIC     (@var{c})
These six macros are defined by @file{safe-ctype.h} and provide
additional character classes which are useful when doing lexical
analysis of C or similar languages.  They are true for the following
sets of characters:

@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada}
@item @code{IDNUM}        @tab @kbd{A-Za-z0-9_}
@item @code{IDST}         @tab @kbd{A-Za-z_}
@item @code{VSPACE}       @tab @kbd{\r \n}
@item @code{NVSPACE}      @tab @kbd{space tab \f \v \0}
@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE}
@item @code{ISOBASIC}     @tab @code{VSPACE || NVSPACE || PRINT}
@end multitable
@end deffn

@c lbasename.c:23
@deftypefn Replacement {const char*} lbasename (const char *@var{name})

Given a pointer to a string containing a typical pathname
(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the
last component of the pathname (@samp{ls.c} in this case).  The
returned pointer is guaranteed to lie within the original
string.  This latter fact is not true of many vendor C
libraries, which return special strings or modify the passed
strings for particular input.

In particular, the empty string returns the same empty string,
and a path ending in @code{/} returns the empty string after it.

@end deftypefn

@c lrealpath.c:25
@deftypefn Replacement {const char*} lrealpath (const char *@var{name})

Given a pointer to a string containing a pathname, returns a canonical
version of the filename.  Symlinks will be resolved, and ``.'' and ``..''
components will be simplified.  The returned value will be allocated using
@code{malloc}, or @code{NULL} will be returned on a memory allocation error.

@end deftypefn

@c make-relative-prefix.c:24
@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix})

Given three paths @var{progname}, @var{bin_prefix}, @var{prefix},
return the path that is in the same position relative to
@var{progname}'s directory as @var{prefix} is relative to
@var{bin_prefix}.  That is, a string starting with the directory
portion of @var{progname}, followed by a relative pathname of the
difference between @var{bin_prefix} and @var{prefix}.

If @var{progname} does not contain any directory separators,
@code{make_relative_prefix} will search @env{PATH} to find a program
named @var{progname}.  Also, if @var{progname} is a symbolic link,
the symbolic link will be resolved.

For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta},
@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is
@code{/red/green/blue/gcc}, then this function will return
@code{/red/green/blue/../../omega/}.

The return value is normally allocated via @code{malloc}.  If no
relative prefix can be found, return @code{NULL}.

@end deftypefn

@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
create one.  @var{suffix} is a suffix to append to the file name.  The
string is @code{malloc}ed, and the temporary file has been created.

@end deftypefn

@c memchr.c:3
@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})

This function searches memory starting at @code{*@var{s}} for the
character @var{c}.  The search only ends with the first occurrence of
@var{c}, or after @var{length} characters; in particular, a null
character does not terminate the search.  If the character @var{c} is
found within @var{length} characters of @code{*@var{s}}, a pointer
to the character is returned.  If @var{c} is not found, then @code{NULL} is
returned.

@end deftypefn

@c memcmp.c:6
@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})

Compares the first @var{count} bytes of two areas of memory.  Returns
zero if they are the same, a value less than zero if @var{x} is
lexically less than @var{y}, or a value greater than zero if @var{x}
is lexically greater than @var{y}.  Note that lexical order is determined
as if comparing unsigned char arrays.

@end deftypefn

@c memcpy.c:6
@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})

Copies @var{length} bytes from memory region @var{in} to region
@var{out}.  Returns a pointer to @var{out}.

@end deftypefn

@c memmove.c:6
@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})

Copies @var{count} bytes from memory area @var{from} to memory area
@var{to}, returning a pointer to @var{to}.

@end deftypefn

@c mempcpy.c:23
@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, size_t @var{length})

Copies @var{length} bytes from memory region @var{in} to region
@var{out}.  Returns a pointer to @var{out} + @var{length}.

@end deftypefn

@c memset.c:6
@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})

Sets the first @var{count} bytes of @var{s} to the constant byte
@var{c}, returning a pointer to @var{s}.

@end deftypefn

@c mkstemps.c:58
@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len})

Generate a unique temporary file name from @var{pattern}.
@var{pattern} has the form:

@example
   @var{path}/ccXXXXXX@var{suffix}
@end example

@var{suffix_len} tells us how long @var{suffix} is (it can be zero
length).  The last six characters of @var{pattern} before @var{suffix}
must be @samp{XXXXXX}; they are replaced with a string that makes the
filename unique.  Returns a file descriptor open on the file for
reading and writing.

@end deftypefn

@c pexecute.txh:266
@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:241
@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

@c pexecute.txh:250
@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
@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{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:2
@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:155
@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name})

Return a stream for a temporary file to pass to the first program in
the pipeline as input.

The name of the input file is chosen according to the same rules
@code{pex_run} uses to choose output file names, based on
@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.

Don't call @code{fclose} on the returned stream; the first call to
@code{pex_run} closes it automatically.

If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
binary mode; otherwise, open it in the default mode.  Including
@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
@end deftypefn

@c pexecute.txh:172
@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary})

Return a stream @var{fp} for a pipe connected to the standard input of
the first program in the pipeline; @var{fp} is opened for writing.
You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
that returned @var{obj}.

You must close @var{fp} using @code{fclose} yourself when you have
finished writing data to the pipeline.

The file descriptor underlying @var{fp} is marked not to be inherited
by child processes.

On systems that do not support pipes, this function returns
@code{NULL}, and sets @code{errno} to @code{EINVAL}.  If you would
like to write code that is portable to all systems the @code{pex}
functions support, consider using @code{pex_input_file} instead.

There are two opportunities for deadlock using
@code{pex_input_pipe}: