cfl.texi

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

* Debugging and Tracing Functions::
* Dynamic Linker Functions::
* Error Handling Functions::
* Process Control Functions::
* Filesystem Functions::
* Mandatory File Locking Functions::
* I/O Functions::
* Logging Functions::
* Memory Management Functions::
* Memory Mapped Files::
* System Information Functions::
@end menu
@chapter System Functions

This chapter describes functions involving system facilities such as
I/O, subprocess execution, error handling, and memory management. They
are divided into several groups; the functions in a group share a common
name prefix for that group; e.g., all filesystem-related functions have
names that begin with @samp{C_file_}. All of the constants, macros, and
functions described in this chapter are defined in the header
@file{cfl/system.h}.

The following sections describe each group in detail.

@node Byte Order Conversion Functions, Debugging and Tracing Functions, , System Functions
@comment  node-name,  next,  previous,  up
@section Byte Order Conversion Functions

The following functions convert various numeric types between host and
network byte order.

@deftypefun uint16_t C_byteord_htons (@w{uint16_t @var{val}})
@deftypefunx uint16_t C_byteord_ntohs (@w{uint16_t @var{val}})

These functions convert an unsigned 16-bit ``short'' integer @var{val}
to and from network byte order, respectively. The functions return the
converted value.

@end deftypefun

@deftypefun uint32_t C_byteord_htonl (@w{uint32_t @var{val}})
@deftypefunx uint32_t C_byteord_ntohl (@w{uint32_t @var{val}})

These functions convert an unsigned 32-bit ``long'' integer @var{val} to
and from network byte order, respectively. The functions return the
converted value.

@end deftypefun

@deftypefun uint64_t C_byteord_htonll (@w{uint64_t @var{val}})
@deftypefunx uint64_t C_byteord_ntohll (@w{uint64_t @var{val}})

These functions convert an unsigned 64-bit ``long long'' integer
@var{val} to and from network byte order, respectively. The functions
return the converted value.

@end deftypefun

@deftypefun float C_byteord_htonf (@w{float @var{val}})
@deftypefunx float C_byteord_ntohf (@w{float @var{val}})

These functions convert an 32-bit floating point value @var{val} to and
from network byte order, respectively. The functions return the
converted value.

@end deftypefun

@deftypefun double C_byteord_htond (@w{double @var{val}})
@deftypefunx double C_byteord_ntohd (@w{double @var{val}})

These functions convert an 64-bit double-precision floating point value
@var{val} to and from network byte order, respectively. The functions
return the converted value.

@end deftypefun

@node Debugging and Tracing Functions, Dynamic Linker Functions, Byte Order Conversion Functions, System Functions
@comment  node-name,  next,  previous,  up
@section Debugging and Tracing Functions

The following functions are provided to aid in the debugging and tracing
of code.

@deftypefun void C_debug_printf (@w{const char *@var{format}}, ...)

This function is similar to @code{printf()}, and is intended for use in
generating debug output. The function is actually implemented as a macro
which evaluates to a call to an internal library function if the
@code{DEBUG} macro is defined; otherwise, it is defined as a no-op,
which essentially prevents the debug call from being compiled into the
calling code.

Debug messages are written to the debugging stream (@code{stderr} by
default). The stream is explicitly flushed after the message is written.

If tracing is enabled, the message will be preceded by the source file
name and line number of the @code{C_debug_printf()} call. In the
multi-threaded version of the library, the message will be preceded by
the calling thread's ID as well.

@end deftypefun

@deftypefun void C_debug_set_trace (@w{c_bool_t @var{flag}})
@deftypefunx void C_debug_set_stream (@w{FILE * @var{stream}})

These functions alter the behavior of the @code{C_debug_printf()}
function described above.

@code{C_debug_set_trace()} enables or disables tracing based on the
value of @var{flag}. If tracing is enabled, the filename and line number
of the @code{C_debug_printf()} call will be prepended to each line of
debug output.

@code{C_debug_set_stream()} sets the output stream for debug messages to
@var{stream}; the default stream is @code{stderr}.

@end deftypefun

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

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

@end deftypefun

@defmac C_assert (@var{expr})

This macro evaluates an assertion; it is provided as a replacement for
the more rudimentary @code{assert()} C library function. The macro works
as follows.

If the expression @var{expr} evaluates to zero (@code{0}), the assertion
fails. A message that indicates the failure and contains the text of the
expression itself is written to the debugging stream in the same manner
as with @code{C_debug_printf()}, and then the process is aborted via a
call to the @code{abort()} C library function. For all other (non-zero)
values, the macro behaves as a no-op.

@end defmac

@node Dynamic Linker Functions, Error Handling Functions, Debugging and Tracing Functions, System Functions
@comment  node-name,  next,  previous,  up
@section Dynamic Linker Functions

@tindex c_dlobject_t

The following functions provide a means to dynamically load and unload
object files at runtime and to obtain pointers to symbols (including
variables and functions) defined in those files. These functions are
based on the @code{dlopen()}, @code{dlsym()}, and @code{dlclose()}
library functions.

The type @i{c_dlobject_t} represents a loadable object.

@deftypefun {c_dlobject_t *} C_dlobject_create (@w{const char *@var{path}})
@deftypefunx c_bool_t C_dlobject_destroy (@w{c_dlobject_t *@var{obj}})

These functions create and destroy loadable objects.
@code{C_dlobject_create()} creates a new loadable object for the object
file specifed by @var{path}. The object will be created in a non-loaded
state. The function returns a pointer to the new loadable object
structure on success, or @code{NULL} on failure.

@code{C_dlobject_destroy()} destroys the loadable object @var{obj}, if
it is not currently loaded. It returns @code{TRUE} on success and
@code{FALSE} on failure.

@end deftypefun

@deftypefun c_bool_t C_dlobject_load (@w{c_dlobject_t *@var{obj}}, @w{c_bool_t @var{lazy}})
@deftypefunx c_bool_t C_dlobject_unload (@w{c_dlobject_t *@var{obj}})

These functions load and unload the loadable object
@var{obj}. @code{C_dlobject_load()} loads the object @var{obj} into
memory. The flag @var{lazy} specifies whether symbols will be resolved
as they are accessed (lazy relocation), or all at once when the object
is loaded. The function will fail if @var{obj} is already loaded.

@code{C_dlobject_unload()} unloads the loadable object @var{obj}. The
function will fail if @var{obj} is not currently loaded.

The functions return @code{TRUE} on success and @code{FALSE} on
failure. In the event of a load/unload failure, a linker-specific error
is stored in @var{obj} and may be accessed via
@code{C_dlobject_error()}, which is described below.

@end deftypefun

@deftypefun {void *} C_dlobject_lookup (@w{c_dlobject_t *@var{obj}}, @w{const char *@var{symbol}})

This function looks up the symbol named @var{symbol} in the loadable
object @var{obj}. It returns a pointer to the symbol on success, or
@code{NULL} on failure. In the event of a lookup failure, a
linker-specific error is stored in @var{obj} and may be accessed via
@code{C_dlobject_error()}, which is described below.

@end deftypefun

@deftypefun c_bool_t C_dlobject_isloaded (@w{c_dlobject_t *@var{obj}})

This function (which is implemented as a macro) returns @code{TRUE} if
the loadable object @var{obj} is currently loaded, and @code{FALSE}
otherwise.

@end deftypefun

@deftypefun {const char *} C_dlobject_error (@w{c_dlobject_t *@var{obj}})

In the case of a failed call to one of the dynamic linker library
functions, an error message is stored in @var{obj}; this function (which
is implemented as a macro) returns that message.

@end deftypefun

@deftypefun {const char *} C_dlobject_path (@w{c_dlobject_t *@var{obj}})

This function (which is implemented as a macro) returns the file path of
the loadable object @var{obj}.

@end deftypefun

@node Error Handling Functions, Process Control Functions, Dynamic Linker Functions, System Functions
@comment  node-name,  next,  previous,  up
@section Error Handling Functions

The following functions are provided to simplify the reporting of user-
and system-level error messages to the console.

@deftypefun void C_error_init (const char *@var{progname})

A call to this function initializes the error handling routines. The
argument @var{progname} is the name of the currently executing program,
which can be obtained from the argument list as @code{argv[0]}. The
function internally stores a copy of this pointer.

@end deftypefun

@deftypefun void C_error_printf (const char *@var{format}, ...)

This function receives arguments in the same manner as the
@code{printf()} library function. It writes the program name to standard
error, then passes its arguments to the @code{vfprintf()} library
function for formatted output to standard error. It then flushes the
standard error stream.

@end deftypefun

@deftypefun void C_error_usage (const char *@var{usage})

This function prints the command-line usage information message
@var{usage} to standard error. It then flushes the standard error
stream.

@end deftypefun

@deftypefun void C_error_syserr (void)

This function is a higher-level interface to the @code{strerror()}
library function. It obtains the error code from the latest system call
executed, formats it as a string, and writes it to standard error. All
other functionality is identical to @code{C_error_printf()} above.

@end deftypefun

@deftypefun int C_error_get_errno (void)

This function returns the error code from the last-executed CFL library
routine. A return value of @code{0} by convention denotes that the last
call executed successfully (no error); note however, that most library
routines do not modify the error code at all if they complete
successfully.  In the multi-threaded version of the library, this
function returns a thread-specific error value. In the single-threaded
version, it simply returns the value of @code{c_errno}.

Calling this routine is equivalent to evaluating @code{c_errno}, which
is defined as a macro that evaluates to a call to
@code{C_error_get_errno()}.

Therefore in both single-threaded and multi-threaded code, it is safe to
call @code{C_error_get_errno()} or to evaluate @code{c_errno} as if it
were a global variable; either approach will correctly return the error
code for the current thread or process. Note that since @code{c_errno}
evaluates to a function call, it cannot be used as an lvalue; that is,
it is not possible to assign values to it.

@end deftypefun
@deftypefun void C_error_set_errno (int @var{err})

This function sets the error code for the currently executing CFL
library routine to @var{err}. This function is provided for use by CFL
extension libraries and is not intended for use by user code.

In the multi-threaded version of the library, @code{C_error_set_errno}
is defined as a function that sets a thread-specific error
value. Otherwise, it is defined as a function that simply assigns
@var{err} to the global @i{int} variable @code{c_errno}.

@end deftypefun

@node Process Control Functions, Filesystem Functions, Error Handling Functions, System Functions
@comment  node-name,  next,  previous,  up
@section Process Control Functions

The following functions provide subprocess control, including
higher-level interfaces to system calls such as @code{execv()}, and
piping.

@deftypefun int C_exec_run (char **@var{argv}, int @var{fdin}, int @var{fdout}, @w{c_bool_t @var{waitf}})
@deftypefunx int C_exec_run_cwd (char **@var{argv}, int @var{fdin}, int @var{fdout}, @w{c_bool_t @var{waitf}}, @w{const char *@var{cwd}})

@code{C_exec_run()} is a higher-level interface to the @code{execv()}
system call. It executes the command specified by @var{argv} as a
subprocess, connecting its standard input stream to the @var{fdin} file
descriptor (or to @file{/dev/null} if @var{fdin} is negative) and its
standard output and standard error streams to the @var{fdout} file
descriptor (or to @file{/dev/null} if @var{fdout} is negative). If
@var{waitf} is @code{TRUE}, the function additionally performs a
@code{waitpid()} system call to wait for the subprocess to finish
executing.

@code{C_exec_run_cwd()} is identical to @code{C_exec_run()}, except that
the additional argument @var{cwd} specifies a new working directory for
the spawned subprocess. If this path does not exist or is not readable,
the working directory of the subprocess will remain unchanged.

If @var{waitf} is @code{TRUE}, the functions return the exit value from
the subprocess. Otherwise, they return @code{0} on success or @code{-1}
on failure.

@end deftypefun

@deftypefun int C_exec_va_run (@w{int @var{fdin}}, @w{int @var{fdout}}, @w{c_bool_t @var{waitf}}, @w{... /* , NULL */})
@deftypefunx int C_exec_va_run_cwd (@w{int @var{fdin}}, @w{int @var{fdout}}, @w{c_bool_t @var{waitf}}, @w{const char *@var{cwd}}, @w{... /* , NULL */})

These are variable argument list versions of @code{C_exec_run()} and
@code{C_exec_run_cwd()}. The command name and arguments are passed as a
@code{NULL}-terminated list of @i{char *} arguments rather than as a
string vector. The other arguments have the same meaning as in
@code{C_exec_run()} and @code{C_exec_run_cwd()}, and the functionality
is identical.

@end deftypefun

@deftypefun int C_exec_pipefrom (char **@var{argv}, int *@var{fd})
@deftypefunx int C_exec_pipefrom_cwd (char **@var{argv}, int *@var{fd}, @w{const char *@var{cwd}})

@code{C_exec_pipefrom()} executes the command specified by @var{argv} as a