cfl.texi

CFL是Unix下的通用抽象库,以简化Unix下的系统软件开发,CFL库中包含几个分组的函数和宏

@deftypefun c_bool_t C_memfile_resize (@w{c_memfile_t *@var{mf}}, @w{off_t @var{length}})

This function resizes the memory mapped file @var{mf} to the new size
@var{length}. The new length must be at least 0. If @var{length} is
smaller than the current length of the file, the file will be truncated
and the excess data will be lost. If @var{length} is larger than the
current length of the file, the file will grow to the new size, and the
extra bytes will be zeroed.

The function returns @code{TRUE} on success, or @code{FALSE} on failure.

@end deftypefun

@deftypefun {void *} C_memfile_base (@w{c_memfile_t *@var{mf}})

This function returns a pointer to the beginning of the memory occupied
by the memory mapped file @var{mf}. It is implemented as a macro.

@end deftypefun

@deftypefun {void *} C_memfile_pointer (@w{c_memfile_t *@var{mf}}, @w{off_t @var{offset}})

This function returns a pointer to the given offset @var{offset} in the
memory mapped file @var{mf}. It is implemented as a macro.

@end deftypefun

@deftypefun off_t C_memfile_length (@w{c_memfile_t *@var{mf}})

This function returns the current length of the memory mapped file
@var{mf}. It is implemented as a macro.

@end deftypefun

@node System Information Functions, , Memory Mapped Files, System Functions
@comment  node-name,  next,  previous,  up
@section System Information Functions

The following functions provide various information about the system and
about users and groups.

@deftypefun c_bool_t C_system_ingroup (@w{const char *@var{login}}, @w{const char *@var{group}})

This function determines if the user whose login name is @var{login}
belongs to the group named @var{group}. It can be used for
authentication purposes.

The function returns @code{TRUE} if the user is a member of the named
group, or @code{FALSE} if not or upon failure (for example, if either
argument is @code{NULL} or an empty string).

@end deftypefun

@deftypefun {c_sysinfo_t *} C_system_getinfo (void)

@tindex c_sysinfo_t

This function obtains various types of information about the system, the
current process and user, the terminal line, and the system time. The
function stores the information in a static data structure, to which it
returns a pointer. The @i{c_sysinfo_t} structure has the following
members:

@multitable @columnfractions .3 .7
@item @code{char *login}
@tab The current user's login name.
@item @code{char *fullname}
@tab The current user's full name.
@item @code{char *homedir}
@tab The current user's home directory.
@item @code{char *shell}
@tab The current user's login shell.
@item @code{uid_t uid}
@tab The process's real user ID.
@item @code{gid_t gid}
@tab The process's real group ID.
@item @code{uid_t euid}
@tab The process's effective user ID.
@item @code{gid_t egid}
@tab The process's effective group ID.
@item @code{char *hostname}
@tab The hostname.
@item @code{char *osname}
@tab The operating system name.
@item @code{char *osver}
@tab The OS version.
@item @code{char *osrel}
@tab The OS release.
@item @code{char *arch}
@tab The system's architecture type.
@item @code{pid_t pid}
@tab The process ID.
@item @code{pid_t ppid}
@tab The parent process ID.
@item @code{time_t stime}
@tab The system time at which this function was first called.
@item @code{char *term}
@tab The terminal line for the current process.
@end multitable

The first time the function is called, it fills the static data
structure with values retrieved from the system. Subsequent calls
immediately return the pointer to this structure.

@end deftypefun

@deftypefun uid_t C_system_get_uid (void)
@deftypefunx gid_t C_system_get_gid (void)
@deftypefunx pid_t C_system_get_pid (void)
@deftypefunx {char *} C_system_get_login (void)
@deftypefunx {char *} C_system_get_fullname (void)
@deftypefunx {char *} C_system_get_homedir (void)
@deftypefunx {char *} C_system_get_hostname (void)
@deftypefunx {char *} C_system_get_term (void)

These are convenience functions that retrieve some of the more
interesting values from the static @i{c_sysinfo_t} structure.

@end deftypefun

@deftypefun c_bool_t C_system_cdhome (void)

This function attempts to set the current working directory to the
current user's home directory. It obtains the home directory path via a
call to @code{C_system_get_homedir()}.

The function returns @code{TRUE} on success, or @code{FALSE} on failure.

@end deftypefun

@deftypefun c_bool_t C_system_passwd_generate (@w{const char *@var{passwd}}, @w{char *@var{buf}}, @w{size_t @var{bufsz}})

This function generates an encrypted password using the standard UNIX
@code{crypt()} function. The string @var{passwd} is encrypted using a
randomly generated salt, and up to @var{bufsz} - 1 bytes of the
resulting ciphertext (the first two bytes of which are the salt) are
written to the buffer @var{buf}, which is unconditionally
@code{NUL}-terminated.

The function returns @code{TRUE} on success. On failure (for example, if
@var{passwd} or @var{buf} is @code{NULL}, or if @var{bufsz} is 0) the
function returns @code{FALSE}.

@end deftypefun

@deftypefun c_bool_t C_system_passwd_validate (@w{const char *@var{plaintext}}, @w{const char *@var{ciphertext}})

This function validates a plaintext password against the encrypted form
of the password using the standard UNIX @code{crypt()} routine. The
string @var{plaintext} is encrypted using the first two bytes of
@var{ciphertext} as the salt. If the resulting ciphertext matches
@var{ciphertext}, the function returns @code{TRUE}. If the ciphertext
strings do not match, or upon failure (for example, if either of the
arguments is @code{NULL}) it returns @code{FALSE}.

@end deftypefun

@node Utility Functions, Data Structure Functions, System Functions, Top
@comment  node-name,  next,  previous,  up
@menu
* Bitstring Functions::
* Data Buffer Functions::
* Hexadecimal Encoding Functions::
* Random Number Functions::
* String Manipulation and Parsing Functions::
* String Buffer Functions::
* Time Functions::
* CPU Timer Functions::
* String Vector Functions::
@end menu
@chapter Utility Functions

This chapter describes various utility functions. They are divided into
several groups; the functions in a group share a common name prefix for
that group; e.g., all string-related functions have names that begin
with @samp{C_string_}. All of the constants, macros, and functions
described in this chapter are defined in the header
@file{cfl/util.h}.

The following sections describe each group in detail.

@node Bitstring Functions, Data Buffer Functions, , Utility Functions
@comment  node-name,  next,  previous,  up
@section Bitstring Functions

@tindex c_bitstring_t

The following functions provide for the manipulation of @dfn{bit
strings} of arbitrary length. Bit strings may be used to efficiently
store groups of related boolean (on/off) flags; each 8-bit byte can
represent 8 such flags.

The type @i{c_bitstring_t} represents a bit string.

@deftypefun {c_bitstring_t *} C_bitstring_create (uint_t @var{nbits})
@deftypefunx c_bool_t C_bitstring_destroy (c_bitstring_t *@var{bs})

These functions create and destroy bit strings.
@w{@code{C_bitstring_create}} creates a new bit string @var{nbits} in
length. The function returns a pointer to the newly created bit string
on success. On failure, it returns @code{NULL} (for example, if
@var{nbits} < 1).

@code{C_bitstring_destroy()} destroys the bit string @var{bs}, freeing
all memory associated with the bit string. It returns @code{TRUE} on
success, or @code{FALSE} on failure (for example, if @var{bs} is
@code{NULL}.)

@end deftypefun

@deftypefun c_bool_t C_bitstring_set (c_bitstring_t *@var{bs}, @w{uint_t @var{bit}})
@deftypefunx c_bool_t C_bitstring_clear (c_bitstring_t *@var{bs}, @w{uint_t @var{bit}})

These functions set and clear the bit at offset @var{bit} in the bit
string @var{bs}. @w{@code{C_bitstring_set()}} sets the specified @var{bit},
and @w{@code{C_bitstring_clear()}} clears it.

The functions return @code{TRUE} on success, or @code{FALSE} on failure
(for example, if @var{bs} is @code{NULL} or @var{bit} is out of range).

@end deftypefun

@deftypefun c_bool_t C_bitstring_set_range (c_bitstring_t *@var{bs}, @w{uint_t @var{sbit}}, @w{uint_t @var{ebit}})
@deftypefunx c_bool_t C_bitstring_clear_range (c_bitstring_t *@var{bs}, @w{uint_t @var{sbit}}, @w{uint_t @var{ebit}})

These functions set or clear a range of bits in the bit string
@var{bs}. @code{C_bitstring_set_range()} sets all of the bits from
offsets @var{sbit} to @var{ebit},
inclusive. @code{C_bitstring_clear_range()} clears all of the bits from
offsets @var{sbit} to @var{ebit}, inclusive.

The functions return @code{TRUE} on success, or @code{FALSE} on failure
(for example, if @var{bs} is @code{NULL}, if @var{sbit} or @var{ebit} is
out of range, or if @var{ebit} < @var{sbit}).

@end deftypefun

@deftypefun c_bool_t C_bitstring_set_all (c_bitstring_t *@var{bs})
@deftypefunx c_bool_t C_bitstring_clear_all (c_bitstring_t *@var{bs})

These functions set or clear all of the bits in the bit string
@var{bs}. @code{C_bitstring_set_all()} sets all bits in the bit string,
and @code{C_bitstring_clear_all()} clears all bits.

The functions return @code{TRUE} on success, or @code{FALSE} on failure
(for example, if @var{bs} is @code{NULL}).

@end deftypefun

@deftypefun c_bool_t C_bitstring_isset (c_bitstring_t *@var{bs}, @w{uint_t @var{bit}})
@deftypefunx c_bool_t C_bitstring_isclear (c_bitstring_t *@var{bs}, @w{uint_t @var{bit}})

These functions test bits in the bit string
@var{bs}. @w{@code{C_bitstring_isset()}} determines if the bit at offset
@var{bit} is set, returning @code{TRUE} if so and @code{FALSE}
otherwise. @w{@code{C_bitstring_isclear()}} determines if the bit at offset
@var{bit} is cleared, returning @code{TRUE} if so and @code{FALSE}
otherwise.

The functions return @code{FALSE} upon failure (for example, if @var{bs}
is @code{NULL} or if @var{bit} is out of range).

@end deftypefun

@deftypefun c_bool_t C_bitstring_compare (@w{c_bitstring_t *@var{bs1}}, @w{c_bitstring_t *@var{bs2}})

This function compares the bit string @var{bs1} to the bit string
@var{bs2}. It returns @code{TRUE} if all of the bits that are set in
@var{bs1} are also set in @var{bs2}, and @code{FALSE} otherwise.

The function returns @code{FALSE} on failure (for example, if @var{bs1}
or @var{bs2} is @code{NULL}).

@end deftypefun

@deftypefun uint_t C_bitstring_size (c_bitstring_t *@var{bs})

This function, which is implemented as a macro, returns the size (in
bits) of the bit string @var{bs}.

@end deftypefun

@node Data Buffer Functions, Hexadecimal Encoding Functions, Bitstring Functions, Utility Functions
@comment  node-name,  next,  previous,  up
@section Data Buffer Functions

@tindex c_buffer_t

The following functions and macros are provided for the manipulation of
dynamically allocated data buffers. The type @i{c_buffer_t} represents a
data buffer. It contains the following members:

@multitable @columnfractions .2 .7
@item @code{char *buf}
@tab A pointer to the buffer.
@item @code{size_t bufsz}
@tab The size of the buffer.
@item @code{void *hook}
@tab A hook for associating arbitrary data.
@end multitable

The @i{c_buffer_t} type can be used as a convenient means of passing
sized buffers. Arbitrary data can also be associated with a buffer via the
@code{hook} pointer.

@deftypefun {c_buffer_t *} C_buffer_create (size_t @var{bufsz})
@deftypefunx void C_buffer_destroy (c_buffer_t *@var{buf})

These functions create and destroy arbitrarily-sized data
buffers. @code{C_buffer_create()} creates a new data buffer @var{bufsz}
bytes in length; the buffer's memory is initially zeroed. The function
returns a pointer to the newly allocated buffer.

@code{C_buffer_destroy()} destroys the buffer @var{buf}, freeing both
the buffer memory and the @i{c_buffer_t} data structure itself.

@end deftypefun

@deftypefun {c_buffer_t *} C_buffer_resize (c_buffer_t *@var{buf}, @w{size_t @var{newsz}})

This function resizes the buffer @var{buf} to a new size of @var{newsz}.
bytes. The semantics are similar to that of @code{C_realloc()}: if the
new size is larger than the previous size, the additional bytes are
zeroed.

The function returns @var{buf} on success. On failure (for example, if @var{newsz} is 0), it returns @code{NULL}.

@end deftypefun

@deftypefun void C_buffer_clear (c_buffer_t *@var{buf})

This function zeroes the buffer @var{buf}.

@end deftypefun

@defmac C_buffer_data (buf)
@defmacx C_buffer_size (buf)

These macros access the corresponding fields in the buffer structure
@var{buf}. The first macro returns a @i{char} pointer to the buffer
memory, while the second returns the current size of the buffer as a
@i{size_t} value.

@end defmac

@node Hexadecimal Encoding Functions, Random Number Functions, Data B