functions.texi

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

external variables @code{sys_nerr} and @code{sys_errlist}, these
strings will be the same as the ones used by @code{perror}.

If the supplied error number is within the valid range of indices for
the @code{sys_errlist}, but no message 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 a valid index into
@code{sys_errlist}, returns @code{NULL}.

The returned string is only guaranteed to be valid only until the
next call to @code{strerror}.

@end deftypefn

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

A case-insensitive @code{strncmp}.

@end deftypefn

@c strncmp.c:6
@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})

Compares the first @var{n} bytes of two strings, returning a value as
@code{strcmp}.

@end deftypefn

@c strndup.c:23
@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n})

Returns a pointer to a copy of @var{s} with at most @var{n} characters
in memory obtained from @code{malloc}, or @code{NULL} if insufficient
memory was available.  The result is always NUL terminated.

@end deftypefn

@c strrchr.c:6
@deftypefn Supplemental char* strrchr (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.  If @var{c} is itself the
null character, the results are undefined.

@end deftypefn

@c strsignal.c:383
@deftypefn Supplemental {const char *} strsignal (int @var{signo})

Maps an signal number to an signal message string, the contents of
which are implementation defined.  On systems which have the external
variable @code{sys_siglist}, these strings will be the same as the
ones used by @code{psignal()}.

If the supplied signal number is within the valid range of indices for
the @code{sys_siglist}, but no message is available for the particular
signal number, then returns the string @samp{Signal @var{num}}, where
@var{num} is the signal number.

If the supplied signal number is not a valid index into
@code{sys_siglist}, returns @code{NULL}.

The returned string is only guaranteed to be valid only until the next
call to @code{strsignal}.

@end deftypefn

@c strsignal.c:446
@deftypefn Extension {const char*} strsigno (int @var{signo})

Given an signal number, returns a pointer to a string containing the
symbolic name of that signal number, as found in @code{<signal.h>}.

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

If the supplied signal 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{strsigno}.

@end deftypefn

@c strstr.c:6
@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})

This function searches for the substring @var{sub} in the string
@var{string}, not including the terminating null characters.  A pointer
to the first occurrence of @var{sub} is returned, or @code{NULL} if the
substring is absent.  If @var{sub} points to a string with zero
length, the function returns @var{string}.

@end deftypefn

@c strtod.c:27
@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})

This ISO C function converts the initial portion of @var{string} to a
@code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
character after the last character used in the conversion is stored in
the location referenced by @var{endptr}.  If no conversion is
performed, zero is returned and the value of @var{string} is stored in
the location referenced by @var{endptr}.

@end deftypefn

@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
to an errno value.  If no translation is found, returns 0.

@end deftypefn

@c strtol.c:33
@deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})

The @code{strtol} function converts the string in @var{string} to a
long integer value according to the given @var{base}, which must be
between 2 and 36 inclusive, or be the special value 0.  If @var{base}
is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
to indicate bases 8 and 16, respectively, else default to base 10.
When the base is 16 (either explicitly or implicitly), a prefix of
@code{0x} is allowed.  The handling of @var{endptr} is as that of
@code{strtod} above.  The @code{strtoul} function is the same, except
that the converted value is unsigned.

@end deftypefn

@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
translation is found, returns 0.

@end deftypefn

@c strverscmp.c:25
@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
The @code{strverscmp} function compares the string @var{s1} against
@var{s2}, considering them as holding indices/version numbers.  Return
value follows the same conventions as found in the @code{strverscmp}
function.  In fact, if @var{s1} and @var{s2} contain no digits,
@code{strverscmp} behaves like @code{strcmp}.

Basically, we compare strings normally (character by character), until
we find a digit in each string - then we enter a special comparison
mode, where each sequence of digits is taken as a whole.  If we reach the
end of these two parts without noticing a difference, we return to the
standard comparison mode.  There are two types of numeric parts:
"integral" and "fractional" (those  begin with a '0'). The types
of the numeric parts affect the way we sort them:

@itemize @bullet
@item
integral/integral: we compare values as you would expect.

@item
fractional/integral: the fractional part is less than the integral one.
Again, no surprise.

@item
fractional/fractional: the things become a bit more complex.
If the common prefix contains only leading zeroes, the longest part is less
than the other one; else the comparison behaves normally.
@end itemize

@smallexample
strverscmp ("no digit", "no digit")
    @result{} 0    // @r{same behavior as strcmp.}
strverscmp ("item#99", "item#100")
    @result{} <0   // @r{same prefix, but 99 < 100.}
strverscmp ("alpha1", "alpha001")
    @result{} >0   // @r{fractional part inferior to integral one.}
strverscmp ("part1_f012", "part1_f01")
    @result{} >0   // @r{two fractional parts.}
strverscmp ("foo.009", "foo.0")
    @result{} <0   // @r{idem, but with leading zeroes only.}
@end smallexample

This function is especially useful when dealing with filename sorting,
because filenames frequently hold indices/version numbers.
@end deftypefun

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

This function attempts to create a name for a temporary file, which
will be a valid file name yet not exist when @code{tmpnam} checks for
it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
or be @code{NULL}.  Use of this function creates a security risk, and it must
not be used in new projects.  Use @code{mkstemp} instead.

@end deftypefn

@c unlink-if-ordinary.c:27
@deftypefn Supplemental int unlink_if_ordinary (const char*)

Unlinks the named file, unless it is special (e.g. a device file).
Returns 0 when the file was unlinked, a negative value (and errno set) when
there was an error deleting the file, and a positive value if no attempt
was made to unlink the file because it is special.

@end deftypefn

@c fopen_unlocked.c:31
@deftypefn Extension void unlock_std_streams (void)

If the OS supports it, ensure that the standard I/O streams,
@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any
multi-threaded locking.  Otherwise do nothing.

@end deftypefn

@c fopen_unlocked.c:23
@deftypefn Extension void unlock_stream (FILE * @var{stream})

If the OS supports it, ensure that the supplied stream is setup to
avoid any multi-threaded locking.  Otherwise leave the @code{FILE}
pointer unchanged.  If the @var{stream} is @code{NULL} do nothing.

@end deftypefn

@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,
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{vsprintf} would return.  If memory could
not be allocated, minus one is returned and @code{NULL} is stored in
@code{*@var{resptr}}.

@end deftypefn

@c vfork.c:6
@deftypefn Supplemental int vfork (void)

Emulates @code{vfork} by calling @code{fork} and returning its value.

@end deftypefn

@c vprintf.c:3
@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})

These functions are the same as @code{printf}, @code{fprintf}, and
@code{sprintf}, respectively, except that they are called with a
@code{va_list} instead of a variable number of arguments.  Note that
they do not call @code{va_end}; this is the application's
responsibility.  In @libib{} they are implemented in terms of the
nonstandard but common function @code{_doprnt}.

@end deftypefn

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

This function is similar to vsprintf, 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 waitpid.c:3
@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)

This is a wrapper around the @code{wait} function.  Any ``special''
values of @var{pid} depend on your implementation of @code{wait}, as
does the return value.  The third argument is unused in @libib{}.

@end deftypefn

@c argv.c:293
@deftypefn Extension int writeargv (const char **@var{argv}, FILE *@var{file})

Write each member of ARGV, handling all necessary quoting, to the file
named by FILE, separated by whitespace.  Return 0 on success, non-zero
if an error occurred while writing to FILE.

@end deftypefn

@c xatexit.c:11
@deftypefun int xatexit (void (*@var{fn}) (void))

Behaves as the standard @code{atexit} function, but with no limit on
the number of registered functions.  Returns 0 on success, or @minus{}1 on
failure.  If you use @code{xatexit} to register functions, you must use
@code{xexit} to terminate your program.

@end deftypefun

@c xmalloc.c:38
@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})

Allocate memory without fail, and set it to zero.  This routine functions
like @code{calloc}, but will behave the same as @code{xmalloc} if memory
cannot be found.

@end deftypefn

@c xexit.c:22
@deftypefn Replacement void xexit (int @var{code})

Terminates the program.  If any functions have been registered with
the @code{xatexit} replacement function, they will be called first.
Termination is handled via the system's normal @code{exit} call.

@end deftypefn

@c xmalloc.c:22
@deftypefn Replacement void* xmalloc (size_t)

Allocate memory without fail.  If @code{malloc} fails, this will print
a message to @code{stderr} (using the name set by
@code{xmalloc_set_program_name},
if any) and then call @code{xexit}.  Note that it is therefore safe for
a program to contain @code{#define malloc xmalloc} in its source.

@end deftypefn

@c xmalloc.c:53
@deftypefn Replacement void xmalloc_failed (size_t)

This function is not meant to be called by client code, and is listed
here for completeness only.  If any of the allocation routines fail, this
function will be called to print an error message and terminate execution.

@end deftypefn

@c xmalloc.c:46
@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})

You can use this to set the name of the program used by
@code{xmalloc_failed} when printing a failure message.

@end deftypefn

@c xmemdup.c:7
@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})

Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
are allocated, then @var{copy_size} bytes from @var{input} are copied into
it, and the new memory is returned.  If fewer bytes are copied than were
allocated, the remaining memory is zeroed.

@end deftypefn

@c xmalloc.c:32
@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
Reallocate memory without fail.  This routine functions like @code{realloc},
but will behave the same as @code{xmalloc} if memory cannot be found.

@end deftypefn

@c xstrdup.c:7
@deftypefn Replacement char* xstrdup (const char *@var{s})

Duplicates a character string without fail, using @code{xmalloc} to
obtain memory.

@end deftypefn

@c xstrerror.c:7
@deftypefn Replacement char* xstrerror (int @var{errnum})

Behaves exactly like the standard @code{strerror} function, but
will never return a @code{NULL} pointer.

@end deftypefn

@c xstrndup.c:23
@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n})

Returns a pointer to a copy of @var{s} with at most @var{n} characters
without fail, using @code{xmalloc} to obtain memory.  The result is
always NUL terminated.

@end deftypefn