cfl.texi

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

@deftypefun {char *} C_io_getline (FILE *@var{fp}, char @var{termin}, int *@var{len})

This function is a dynamic line input routine. It reads a line of
unlimited length from the stream @var{fp}, stopping once the terminator
character @var{termin} is encountered. It allocates memory as needed to
store the data being read from the stream.

Once the terminator character is encountered, it is discarded and the
string is @code{NUL}-terminated. The number of characters read
(not including the terminator) is stored at @var{len} if it is
non-@code{NULL}.

On success, the function returns a pointer to the dynamically allocated
buffer, which is exactly large enough to hold the @code{NUL}-terminated
string. On failure (for example, on end-of-file), it returns
@code{NULL}.

@end deftypefun

@defmac C_getchar ()

This is a convenience macro. It evaluates to an expression involving a
call to @code{C_io_getchar()}, passing @code{C_IO_GETCHAR_DELAY} as an
argument.

@end defmac

@defmac C_gets (buf, bufsz)

This is a convenience macro. It evaluates to an expression involving a
call to @code{C_io_gets()}, passing @code{stdin} as the stream and
`@code{\n}' (newline) as the terminator character. It may be used as a
direct replacement for the @code{gets()} library function.

@end defmac

@defmac C_getline (fp, len)

This is a convenience macro. It evaluates to an expression involving a
call to @code{C_io_getline()}, passing @samp{\n} (newline) as the
terminator character.

@end defmac

@deftypefun int C_io_fprintf (@w{FILE * @var{stream}}, @w{const char *@var{format}}, @w{...})

This is a thread-safe wrapper for the @code{fprintf()} library
function. It locks @var{stream} via a call to @code{flockfile()} before
proceeding to call @code{fprintf()}, and then unlocks the stream after
that function completes. This ensures that only one thread at a time
can write to the stream.

The function returns the value returned by @code{fprintf()}. In the
single-threaded version of the library, this function simply invokes
@code{fprintf()}.

@end deftypefun

@deftypefun int C_printf (@w{const char *@var{format}}, @w{...})

This function (which is implemented as a macro) calls
@code{C_io_fprintf()}, described above, passing @code{stdout} as the
stream.

@end deftypefun

@node Logging Functions, Memory Management Functions, I/O Functions, System Functions
@comment  node-name,  next,  previous,  up
@section Logging Functions

The following functions provide a simple, minimal API for writing log
messages to the console and/or a log file.

@deftypefun void C_log_set_console (c_bool_t @var{flag})

This function enables or disables the writing of log messages to the
console (that is, the standard error stream) based on the value of
@var{flag}. By default, log messages are written to the console.

@end deftypefun

@deftypefun void C_log_set_stream (FILE *@var{stream})

This function specifies the @var{stream} for log messages. If
@var{stream} is @code{NULL}, logging to a stream will be disabled.

@end deftypefun

@deftypefun void C_log_set_termattr (@w{c_bool_t @var{flag}})

This function enables or disables the use of ANSI color and text style
terminal attributes for log messages. This feature is enabled by
default, and causes all log messages (when written to a tty) to be
printed in a bold font, and to be color coded according to severity.

@end deftypefun

@deftypefun void C_log_info (@w{const char *@var{fmt}}, ...)
@deftypefunx void C_log_warning (@w{const char *@var{fmt}}, ...)
@deftypefunx void C_log_error (@w{const char *@var{fmt}}, ...)

These @code{printf()}-style functions write informational, warning, and
error messages, respectively, to the console and/or the logging stream.

Each message will be prefixed by the current date and time.

Messages written to the console (the standard error stream) will be
written in a bold font and color-coded to reflect the severity of the
error, assuming that the stream is a tty and that terminal attributes
are enabled.

@end deftypefun

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

The following functions and macros simplify memory management in
C. These routines provide more convenient interfaces to the standard
@code{malloc()} family of library functions.

@deftypefun {void *} C_mem_manage (void *@var{p}, size_t @var{elemsz}, @w{c_bool_t @var{clearf}})

This is a general-purpose memory management function. It is a
higher-level interface to the @code{realloc()} library function. The
argument @var{p} is a pointer to the memory to be managed in the case of
a reallocation request, or @code{NULL} for an initial allocation
request. The new or initial size of the memory, in bytes, is specified
by @var{elemsz}. If @var{clearf} is @code{TRUE}, the newly allocated
memory is zeroed; if this is a reallocation request that increases the
size of a memory segment, the existing data is preserved and only the
additional memory is zeroed.

If the memory allocation fails, the allocation error handler (if one has
been installed) will be called. If the error handler returns
@code{TRUE}, another attempt will be made to allocate the requested
memory; otherwise, it will be assumed that the allocation request cannot
be satisfied.

The function returns a pointer to the newly allocated memory on success,
or @code{NULL} on failure.

Some of the memory management macros described below evaluate to calls
to this function.

@end deftypefun

@deftypefun void C_mem_set_errorfunc (c_bool_t (*@var{func})(void))

This function allows the user to specify a memory allocation request
failure handler. @var{func} will be called each time
@code{C_mem_manage()} fails to allocate memory. This function may return
@code{TRUE} to indicate that another attempt should be made to allocate
the memory, or @code{FALSE} to indicate that no additional memory can be
made available.

If @var{func} is @code{NULL}, any currently-installed handler is
removed. See @code{C_mem_manage()} for a description of the conditions
under which @var{func} will be called.

@end deftypefun

@deftypefun {void *} C_mem_free (void *@var{p})

This function is simply an interface to the @code{free()} library
function. If @var{p} is not @code{NULL}, it is passed to
@code{free()}. The function always returns @code{NULL}.

@end deftypefun

@deftypefun void C_mem_freevec (char **@var{v})

This function frees a @code{NULL}-terminated character string vector
@var{v}, by first dereferencing and freeing each character array in
turn, and then freeing the character pointer array itself.

@end deftypefun

@deftypefun uint_t C_mem_va_free (uint_t @var{n}, ...)

This function is a variable-argument interface to the @code{free()}
library function. The argument @var{n} specifies how many pointers
(which must be of type @i{void *}) are being passed. Each subsequent
non-@code{NULL} argument is passed to @code{free()}.

The function returns the number of non-@code{NULL} arguments that were
processed.

@end deftypefun

@deftypefun size_t C_mem_defrag (void *@var{p} size_t @var{elemsz}, size_t @var{len}, c_bool_t (*@var{isempty})(void *elem))

This is a general-purpose memory defragmentation routine. It interprets
the memory at @var{p} as an array of @var{len} elements, each
@var{elemsz} bytes in size. @var{isempty} is a pointer to a function
which, when passed a pointer to one of the elements in the array,
determines if it is ``used'' or ``empty'' and returns @code{FALSE} or
@code{TRUE}, respectively.

The function iterates through the elements in the array, testing each
element using @var{isempty}(), and moving contiguous blocks of ``used''
elements toward the beginning of the array until all ``free'' space has
been coalesced at the end. The order of the elements within the array is
preserved.

The function returns the number of ``used'' elements in the array. This
return value can be used in a subsequent call to one of the memory
allocation routines to reduce the size of the defragmented array to
allow the unused space to be reclaimed by the system.

@end deftypefun

@defmac C_malloc (n, type)
@defmacx C_calloc (n, type)

These macros are convenient replacements for the @code{malloc()} and
@code{calloc()} library functions. They take as arguments the number of
elements to allocate @var{n}, and the element's @var{type} (such as
@i{int} or @i{struct foobar}). They return a properly cast pointer to
the memory. Hence, the call:

@example
C_malloc(5, char *)
@end example

would have a return value of type @i{char **}, that is, a pointer to 5
contiguous character pointers.

@code{C_calloc()} is similar, except that it additionally zeroes the
newly allocated memory. Both macros evaluate to expressions involving
calls to @code{C_mem_manage()}.

@end defmac

@defmac C_realloc (p, n, type)

This macro is a convenient replacement for the @code{realloc()} library
function. It takes as arguments a pointer @var{p} (of any type), the
number of elements to allocate @var{n} (which is presumed to be of type
@i{size_t}), and the element's @var{type} (such as @i{int} or @i{struct
foobar}). It reallocates the memory beginning at @var{p} to the new
size, returning a properly cast pointer to the resized memory. The macro
evaluates to an expression involving a call to @code{C_mem_manage()}.

@end defmac

@defmac C_zero (p, type)
@defmacx C_zeroa (p, n, type)

These macros zero the specified memory. @code{C_zero()} zeroes the
element of type @var{type} at location @var{p}. @code{C_zeroa()} zeroes
the @var{n}-element array of type @var{type} at location @var{p}.

@end defmac

@defmac C_free (p)
@defmacx C_free_vec (v)
@defmacx C_va_free (n, ...)

These are additional convenience macros for freeing
memory. @code{C_free()} frees the memory at @var{p}, which can be a
pointer of any type. The macro is for use in place of calls to the
@code{free()} library function. It evaluates to an expression involving
a call to @code{C_mem_free()}.

@code{C_free_vec()} and @code{C_va_free()} are identical to
@code{C_mem_free_vec()} and @code{C_mem_va_free()}, respectively.

@end defmac

@defmac C_new (type)
@defmacx C_newa (n, type)
@defmacx C_newb (n)
@defmacx C_newstr (n)

These are additional convenience macros for allocating
memory. @code{C_new()} allocates space for one element of the specified
type. @code{C_newa()} allocates space for an array of @var{n} elements
of the specified type. (These are reminiscent of @code{new} and
@code{new[]} in C++.) @code{C_newb()} allocates space for an
@var{n}-byte segment. @code{C_newstr()} allocates space for a character
array of length @var{n}.  The variable @var{n} is assumed to be of type
@i{size_t}.

These macros all expand to expressions involving the @code{C_calloc()}
macro, hence the returned memory will always be zeroed. All of these
macros return properly-cast pointers to the newly allocated memory, so
an explicit cast is not necessary. For example:

@example
char *s = C_newstr(45);
struct foobar *item = C_new(struct foobar);
int *scores = C_newa(20, int);
@end example

@end defmac

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

@tindex c_memfile_t

The following functions provide a high-level interface to memory mapped
files. A @dfn{memory mapped file} is a disk file that has been mapped
into the calling process's address space; the contents of the file may
be manipulated by modifying memory directly. This mechanism is
especially useful for very large files, as the operating system takes
care of the details of paging portions of the file in and out of memory
as needed, and of keeping the contents of the disk file in sync with the
data that is in memory.

The type @i{c_memfile_t} represents a memory mapped file.

@deftypefun {c_memfile_t *} C_memfile_open (@w{const char *@var{file}}, @w{c_bool_t @var{readonly}})

This function opens the specified @var{file} and maps it into memory. If
@var{readonly} is @code{TRUE}, the file will be mapped as read-only;
otherwise both reading and writing will be allowed.

The function returns a pointer to the new @i{c_memfile_t} structure on
success, or @code{NULL} on failure. The function @code{C_memfile_base()}
may be used to obtain a pointer to the beginning of the file in memory.

@end deftypefun

@deftypefun c_bool_t C_memfile_close (@w{c_memfile_t *@var{mf}})

This function unmaps the memory mapped file @var{mf} and closes the
file. A sync operation is performed just before the file is unmapped to
ensure that any pending updates are persisted to the disk file.

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

@end deftypefun

@deftypefun c_bool_t C_memfile_sync (@w{c_memfile_t *@var{mf}}, @w{c_bool_t @var{async}})

The operating system periodically performs a sync operation to keep the
contents of the disk file up to date with the memory-resident image of
the file. This function forces such an update to take place immediately
on the memory mapped file @var{mf}. If @var{async} is @code{TRUE}, the
update is performed asynchronously, and the function returns
immediately. Otherwise, it is performed synchronously and the function
returns when the update is complete.

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

@end deftypefun