functions.texi

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

@c Automatically generated from *.c and others (the comments before
@c each entry tell you which file and where in that file).  DO NOT EDIT!
@c Edit the *.c files, configure with --enable-maintainer-mode,
@c and let gather-docs build you a new copy.

@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
preprocessor @samp{#if} statements (the C "execution character set").
It is defined by @file{safe-ctype.h}, and will be an integer constant
with one of the following values:

@ftable @code
@item HOST_CHARSET_UNKNOWN
The host character set is unknown - that is, not one of the next two
possibilities.

@item HOST_CHARSET_ASCII
The host character set is ASCII.

@item HOST_CHARSET_EBCDIC
The host character set is some variant of EBCDIC.  (Only one of the
nineteen EBCDIC varying characters is tested; exercise caution.)
@end ftable
@end defvr

@c alloca.c:26
@deftypefn Replacement void* alloca (size_t @var{size})

This function allocates memory which will be automatically reclaimed
after the procedure exits.  The @libib{} implementation does not free
the memory immediately but will do so eventually during subsequent
calls to this function.  Memory is allocated using @code{xmalloc} under
normal circumstances.

The header file @file{alloca-conf.h} can be used in conjunction with the
GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
available this function.  The @code{AC_FUNC_ALLOCA} test requires that
client code use a block of preprocessor code to be safe (see the Autoconf
manual for more); this header incorporates that logic and more, including
the possibility of a GCC built-in function.

@end deftypefn

@c asprintf.c:32
@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...)

Like @code{sprintf}, but instead of passing a pointer to a buffer, you
pass a pointer to a pointer.  This function will compute the size of
the buffer needed, allocate memory with @code{malloc}, and store a
pointer to the allocated memory in @code{*@var{resptr}}.  The value
returned is the same as @code{sprintf} would return.  If memory could
not be allocated, minus one is returned and @code{NULL} is stored in
@code{*@var{resptr}}.

@end deftypefn

@c atexit.c:6
@deftypefn Supplemental int atexit (void (*@var{f})())

Causes function @var{f} to be called at exit.  Returns 0.

@end deftypefn

@c basename.c:6
@deftypefn Supplemental char* basename (const char *@var{name})

Returns a pointer to the last component of pathname @var{name}.
Behavior is undefined if the pathname ends in a directory separator.

@end deftypefn

@c bcmp.c:6
@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})

Compares the first @var{count} bytes of two areas of memory.  Returns
zero if they are the same, nonzero otherwise.  Returns zero if
@var{count} is zero.  A nonzero result only indicates a difference,
it does not indicate any sorting order (say, by having a positive
result mean @var{x} sorts before @var{y}).

@end deftypefn

@c bcopy.c:3
@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})

Copies @var{length} bytes from memory region @var{in} to region
@var{out}.  The use of @code{bcopy} is deprecated in new programs.

@end deftypefn

@c bsearch.c:33
@deftypefn Supplemental void* bsearch (const void *@var{key}, const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, int (*@var{compar})(const void *, const void *))

Performs a search over an array of @var{nmemb} elements pointed to by
@var{base} for a member that matches the object pointed to by @var{key}.
The size of each member is specified by @var{size}.  The array contents
should be sorted in ascending order according to the @var{compar}
comparison function.  This routine should take two arguments pointing to
the @var{key} and to an array member, in that order, and should return an
integer less than, equal to, or greater than zero if the @var{key} object
is respectively less than, matching, or greater than the array member.

@end deftypefn

@c argv.c:124
@deftypefn Extension char** buildargv (char *@var{sp})

Given a pointer to a string, parse the string extracting fields
separated by whitespace and optionally enclosed within either single
or double quotes (which are stripped off), and build a vector of
pointers to copies of the string for each field.  The input string
remains unchanged.  The last element of the vector is followed by a
@code{NULL} element.

All of the memory for the pointer array and copies of the string
is obtained from @code{malloc}.  All of the memory can be returned to the
system with the single function call @code{freeargv}, which takes the
returned result of @code{buildargv}, as it's argument.

Returns a pointer to the argument vector if successful.  Returns
@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient
memory to complete building the argument vector.

If the input is a null string (as opposed to a @code{NULL} pointer),
then buildarg returns an argument vector that has one arg, a null
string.

@end deftypefn

@c bzero.c:6
@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})

Zeros @var{count} bytes starting at @var{mem}.  Use of this function
is deprecated in favor of @code{memset}.

@end deftypefn

@c calloc.c:6
@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})

Uses @code{malloc} to allocate storage for @var{nelem} objects of
@var{elsize} bytes each, then zeros the memory.

@end deftypefn

@c choose-temp.c:42
@deftypefn Extension char* choose_temp_base (void)

Return a prefix for temporary file names or @code{NULL} if unable to
find one.  The current directory is chosen if all else fails so the
program is exited if a temporary directory can't be found (@code{mktemp}
fails).  The buffer for the result is obtained with @code{xmalloc}.

This function is provided for backwards compatibility only.  Its use is
not recommended.

@end deftypefn

@c make-temp-file.c:87
@deftypefn Replacement char* choose_tmpdir ()

Returns a pointer to a directory path suitable for creating temporary
files in.

@end deftypefn

@c clock.c:27
@deftypefn Supplemental long clock (void)

Returns an approximation of the CPU time used by the process as a
@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
number of seconds used.

@end deftypefn

@c concat.c:24
@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL})

Concatenate zero or more of strings and return the result in freshly
@code{xmalloc}ed memory.  Returns @code{NULL} if insufficient memory is
available.  The argument list is terminated by the first @code{NULL}
pointer encountered.  Pointers to empty strings are ignored.

@end deftypefn

@c argv.c:52
@deftypefn Extension char** dupargv (char **@var{vector})

Duplicate an argument vector.  Simply scans through @var{vector},
duplicating each argument until the terminating @code{NULL} is found.
Returns a pointer to the argument vector if successful.  Returns
@code{NULL} if there is insufficient memory to complete building the
argument vector.

@end deftypefn

@c strerror.c:567
@deftypefn Extension int errno_max (void)

Returns the maximum @code{errno} value for which a corresponding
symbolic name or message is available.  Note that in the case where we
use the @code{sys_errlist} 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{perror(3C)} explicitly warns that one
should check the size of the table (@code{sys_nerr}) before indexing
it, since new error codes may be added to the system before they are
added to the table.  Thus @code{sys_nerr} might be smaller than value
implied by the largest @code{errno} value defined in @code{<errno.h>}.

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

@end deftypefn

@c argv.c:348
@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp})

The @var{argcp} and @code{argvp} arguments are pointers to the usual
@code{argc} and @code{argv} arguments to @code{main}.  This function
looks for arguments that begin with the character @samp{@@}.  Any such
arguments are interpreted as ``response files''.  The contents of the
response file are interpreted as additional command line options.  In
particular, the file is separated into whitespace-separated strings;
each such string is taken as a command-line option.  The new options
are inserted in place of the option naming the response file, and
@code{*argcp} and @code{*argvp} will be updated.  If the value of
@code{*argvp} is modified by this function, then the new value has
been dynamically allocated and can be deallocated by the caller with
@code{freeargv}.  However, most callers will simply call
@code{expandargv} near the beginning of @code{main} and allow the
operating system to free the memory when the program exits.

@end deftypefn

@c fdmatch.c:23
@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2})

Check to see if two open file descriptors refer to the same file.
This is useful, for example, when we have an open file descriptor for
an unnamed file, and the name of a file that we believe to correspond
to that fd.  This can happen when we are exec'd with an already open
file (@code{stdout} for example) or from the SVR4 @file{/proc} calls
that return open file descriptors for mapped address spaces.  All we
have to do is open the file by name and check the two file descriptors
for a match, which is done by comparing major and minor device numbers
and inode numbers.

@end deftypefn

@c fopen_unlocked.c:48
@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
any multi-threaded locking.  Otherwise return the @code{FILE} pointer
unchanged.

@end deftypefn

@c ffs.c:3
@deftypefn Supplemental int ffs (int @var{valu})

Find the first (least significant) bit set in @var{valu}.  Bits are
numbered from right to left, starting with bit 1 (corresponding to the
value 1).  If @var{valu} is zero, zero is returned.

@end deftypefn

@c filename_cmp.c:32
@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2})

Return zero if the two file names @var{s1} and @var{s2} are equivalent.
If not equivalent, the returned value is similar to what @code{strcmp}
would return.  In other words, it returns a negative value if @var{s1}
is less than @var{s2}, or a positive value if @var{s2} is greater than
@var{s2}.

This function does not normalize file names.  As a result, this function
will treat filenames that are spelled differently as different even in
the case when the two filenames point to the same underlying file.
However, it does handle the fact that on DOS-like file systems, forward
and backward slashes are equal.

@end deftypefn

@c fnmatch.txh:1
@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})

Matches @var{string} against @var{pattern}, returning zero if it
matches, @code{FNM_NOMATCH} if not.  @var{pattern} may contain the
wildcards @code{?} to match any one character, @code{*} to match any
zero or more characters, or a set of alternate characters in square
brackets, like @samp{[a-gt8]}, which match one character (@code{a}
through @code{g}, or @code{t}, or @code{8}, in this example) if that one
character is in the set.  A set may be inverted (i.e., match anything
except what's in the set) by giving @code{^} or @code{!} as the first
character in the set.  To include those characters in the set, list them
as anything other than the first character of the set.  To include a
dash in the set, list it last in the set.  A backslash character makes
the following character not special, so for example you could match
against a literal asterisk with @samp{\*}.  To match a literal
backslash, use @samp{\\}.

@code{flags} controls various aspects of the matching process, and is a
boolean OR of zero or more of the following values (defined in
@code{<fnmatch.h>}):

@table @code

@item FNM_PATHNAME
@itemx FNM_FILE_NAME
@var{string} is assumed to be a path name.  No wildcard will ever match
@code{/}.

@item FNM_NOESCAPE
Do not interpret backslashes as quoting the following special character.

@item FNM_PERIOD
A leading period (at the beginning of @var{string}, or if
@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or
@code{?} but must be matched explicitly.

@item FNM_LEADING_DIR
Means that @var{string} also matches @var{pattern} if some initial part
of @var{string} matches, and is followed by @code{/} and zero or more
characters.  For example, @samp{foo*} would match either @samp{foobar}
or @samp{foobar/grill}.

@item FNM_CASEFOLD
Ignores case when performing the comparison.

@end table

@end deftypefn

@c fopen_unlocked.c:39
@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
any multi-threaded locking.  Otherwise return the @code{FILE} pointer
unchanged.

@end deftypefn

@c argv.c:97
@deftypefn Extension void freeargv (char **@var{vector})

Free an argument vector that was built using @code{buildargv}.  Simply
scans through @var{vector}, freeing the memory for each argument until
the terminating @code{NULL} is found, and then frees @var{vector}
itself.

@end deftypefn

@c fopen_unlocked.c:57
@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
any multi-threaded locking.  Otherwise return the @code{FILE} pointer
unchanged.

@end deftypefn

@c getruntime.c:82
@deftypefn Replacement long get_run_time (void)

Returns the time used so far, in microseconds.  If possible, this is
the time used by this process, else it is the elapsed time since the
process started.

@end deftypefn

@c getcwd.c:6
@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})

Copy the absolute pathname for the current working directory into
@var{pathname}, which is assumed to point to a buffer of at least
@var{len} bytes, and return a pointer to the buffer.  If the current
directory's path doesn't fit in @var{len} characters, the result is
@code{NULL} and @code{errno} is set.  If @var{pathname} is a null pointer,
@code{getcwd} will obtain @var{len} bytes of space using
@code{malloc}.

@end deftypefn

@c getpagesize.c:5
@deftypefn Supplemental int getpagesize (void)

Returns the number of bytes in a page of memory.  This is the
granularity of many of the system memory management routines.  No
guarantee is made as to whether or not it is the same as the basic
memory management hardware page size.