cfl.texi

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

\input texinfo.tex    @c -*-texinfo-*-
@c 
@c %**start of header

@c All text is ignored before the setfilename.
@setfilename cfl.info
@settitle CFL @value{edition}

@set edition 1.1
@set update-month June 2003
@set update-date 14 @value{update-month}

@comment %**end of header

@tex
\global\emergencystretch = .3\hsize
@end tex

@setchapternewpage odd

@titlepage

@title CFL
@subtitle A C Foundation Library
@subtitle Version @value{edition}
@subtitle @value{update-date}

@author Mark A.@: Lindner

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1994-2003  Mark A Lindner

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

@end titlepage

@contents

@ifnottex
@node Top
@comment  node-name,  next,  previous,  up
@top cfl
@end ifnottex

@menu
* Overview of CFL::
* Types Macros and Constants::
* System Functions::
* Utility Functions::
* Data Structure Functions::
* XML Data Manipulation Functions::
* Real-Time Scheduler Functions::
* IPC Functions::
* Networking Functions::
* Miscellaneous Functions::
* References::
* License::
* Function Index::
* Type Index::
@end menu

@node Overview of CFL, Types Macros and Constants, Top, Top
@comment  node-name,  next,  previous,  up
@menu
* Using CFL::
* API Conventions::
* Reentrancy and Threading::
* Portability Notes::
* Historical Notes::
@end menu
@chapter Overview of CFL

@dfn{CFL} is a library that aims to simplify systems software
development under UNIX. The library consists of several groups of
functions and macros that simplify such common tasks as memory
allocation, string parsing, subprocess execution, filesystem traversal,
and so on.

In addition, the library includes efficient implementations of some
common data structures, such as linked lists, queues, and hash tables,
as well as other less common data structures. Many of these types of
tasks involve tricky pointer arithmetic and memory management and are
inherently error-prone. Moving this common logic into a library frees
the developer from having to recode and debug this functionality each
time it is needed.

Finally, the library provides a simple, high-level interface to several
UNIX IPC mechanisms, including semaphores, shared memory, and Berkeley
sockets.

The following chapters describe all of the datatypes, constants, macros,
and functions in the library in detail. Function and datatype indices
are provided at the end of the manual.

@node Using CFL, API Conventions, , Overview of CFL
@comment  node-name,  next,  previous,  up
@section Using CFL

The @i{CFL} library exists in two forms: the multi-threaded version and
the single-threaded version. The single-threaded version is named
@file{libcfl.a} or @file{libcfl.so} and the multi-threaded version is
named @file{libcfl_mt.a} or @file{libcfl_mt.so}.

Therefore, to link with the single-threaded version of the @i{CFL}
library, issue a command such as:

@example
gcc file1.o file2.o -o myprogram -lcfl
@end example

And similarly, to link with the multi-threaded version:

@example
gcc file1.o file2.o -o myprogram -lcfl_mt
@end example

If your code uses the XML functions, it will also need to be linked with
the @i{expat} library, e.g.:

@example
gcc file1.o file2.o -o myprogram -lcfl -lexpat
@end example

Finally, if your code uses the networking functions, you may need to
link with additional libraries. No additional libraries are required
under Linux. Under Solaris, the @i{socket} and @i{nsl} libraries are
required, e.g.:

@example
gcc file1.o file2.o -o myprogram -lcfl -lsocket -lnsl
@end example

It is extremely important that multi-threaded programs @i{only} be
linked with the multi-threaded version of the library, and that
single-threaded programs @i{only} be linked with the single-threaded
version. Other combinations will produce undefined behavior in your
programs.

All of the definitions in the library can be made available by including
the master header file @file{cfl/cfl.h}.

@node API Conventions, Reentrancy and Threading, Using CFL, Overview of CFL
@comment  node-name,  next,  previous,  up
@section API Conventions

This section describes the naming and calling conventions for constants,
macros, datatypes, and functions in the @i{CFL} library.

All functions and macros begin with the prefix @samp{C_}.

All constants begin with the prefix @samp{C_}, with the following
exception: @code{TRUE}, @code{FALSE}, @code{NUL}, and @code{CRLF}.

All datatypes begin with the prefix @samp{c_} and end with the suffix
@samp{_t}, with the following exceptions: @i{uint_t}.

Unless their fields are expressly documented, all datatypes which begin
with the prefix @samp{c_} should be considered @dfn{opaque}. This means
that pointers to these datatypes serve only as ``handles'' which are
passed to and returned by the functions which operate on those
datatypes. The caller should never directly modify these datatypes or
the fields of the data structures that they represent. The internal
layout of these data structures may change in future versions of the
library; manipulating them only through API calls will ensure that your
code will continue to compile and function properly.

Most functions which return a pointer will by convention return
@code{NULL} on failure.

Functions which return a boolean (@i{c_bool_t}) or an integer will by
convention return @code{TRUE} or a nonzero value to indicate success and
@code{FALSE} or 0 to indicate failure. Note that this is different
from the typical UNIX convention of returning @code{0} on success and a
nonzero value (typically @code{-1}) on failure. Since @code{TRUE} is
defined as a nonzero value and @code{FALSE} is defined as @code{0}, the
following forms are equivalent:

@example
if(C_system_cdhome() == FALSE)
  puts("Failed.");
@end example

@sp 1

@example
if(! C_system_cdhome())
  puts("Failed.");
@end example

@node Reentrancy and Threading, Portability Notes, API Conventions, Overview of CFL
@comment  node-name,  next,  previous,  up
@section Reentrancy and Threading

With some exceptions (as documented), the functions in the @i{CFL}
library are reentrant. This means that they can be safely accessed from
concurrent threads without the need for explicit synchronization.

However, calls to functions which manipulate data structures (such as
linked lists, hash tables, and XML documents) must be synchronized by
the caller in such a way that only one thread is modifying the data
structure at any given time. For example, an insert into a linked list
by one thread with a concurrent insert (or some other operation) on the
same linked list by another thread might result in corruption of the
data structure.

In most cases, it is necessary to use reader/writer locks to ensure that
a reader (a thread that is accessing but not modifying the data
structure) does not access the data structure while another thread is
modifying it.

@node Portability Notes, Historical Notes, Reentrancy and Threading, Overview of CFL
@comment  node-name,  next,  previous,  up
@section Portability Notes

This version of the library has been ported to Sun Solaris 2.8, Linux
(kernel 2.x), and Mac OS X 10.2.

The @code{dlsym()} family of functions are not available on Mac OS X;
however, an add-on library, @i{dlcompat}, is available that provides
these functions; it may be obtained at
@url{http://www.opendarwin.org/projects/dlcompat/}. This add-on library
must be installed in order to use CFL on Mac OS X.

The real-time scheduler is based on the POSIX.4 real-time signal
facility. As of this writing, this facility is only available
on Solaris; it is broken on Linux and is not available at all on OS
X. On the latter platforms, the event loop in the multi-threaded version
of the library is implemented using @code{nanosleep()} instead---this
workaround is suboptimal since it produces clock drift over time, which may
result in missed events.

@node Historical Notes, , Portability Notes, Overview of CFL
@comment  node-name,  next,  previous,  up
@section Historical Notes

@i{CFL} was previously known as @i{pingutil}, the @i{PING Utility
Library}. Unfortunately, this name caused the library to be frequently
confused with the ICMP ``ping'' utility program, with which it has
absolutely nothing in common. When the library was renamed, all of the
functions, types, and some of the header files were renamed as well.

The final version of @i{pingutil} was 2.3, so version 1.0 of @i{CFL} is
equivalent to what would have been version 2.4 of @i{pingutil}. The
initial version of @i{CFL} constitutes a significant update of the
library API over @i{pingutil}; therefore it was not feasible to provide
compatibility headers to map the old API onto the new one.

@node Types Macros and Constants, System Functions, Overview of CFL, Top
@comment  node-name,  next,  previous,  up
@menu
* Basic Types::
* Convenience Macros::
* Miscellaneous Constants::
@end menu
@chapter Types, Macros and Constants

This chapter describes convenience types, macros, and constants. These are
defined in the header @file{cfl/defs.h}.

@node Basic Types, Convenience Macros, , Types Macros and Constants
@comment  node-name,  next,  previous,  up
@section Basic Types

@tindex c_bool_t
The type @i{c_bool_t} represents a boolean value that (by convention)
can take on the values @code{TRUE} or @code{FALSE}; these are macros
defined to be @code{(1)} and @code{(0)}, respectively.

@tindex c_byte_t
The type @i{c_byte_t} represents an unsigned 8-bit value (0 - 255).

@tindex uint_t
The type @i{uint_t} represents an unsigned integer.

@node Convenience Macros, Miscellaneous Constants, Basic Types, Types Macros and Constants
@comment  node-name,  next,  previous,  up
@section Convenience Macros

The following convenience macros are provided:

@defmac C_max (a, b)
@defmacx C_min (a, b)
@defmacx C_sgn (a)

The first two macros correspond to the mathematical @i{max} and @i{min}
functions. @code{C_max()} returns @var{a} if @var{a} > @var{b} and
@var{b} otherwise. @code{C_min()} returns @var{a} if @var{a} < @var{b}
and @var{b} otherwise. The third macro corresponds to the mathematical
@i{sgn} function. It returns @code{-1} if @var{a} < 0, @code{1} if
@var{a} > 0, or @code{0} if @var{a} == 0.  Note that these macros may
evaluate their arguments more than once, so they should not be applied
to expressions that have side-effects (e.g., ``@code{b++}'').

@end defmac

@defmac C_bit_set (i, b)
@defmacx C_bit_clear (i, b)
@defmacx C_bit_isset (i, b)

These macros set, clear, and test the @var{b}'th bit of @var{i} (which
is presumably an integer) using bitwise operators. Each evaluates its
arguments only once.

@end defmac

@defmac C_offsetof (type, element)

This macro returns the offset, in bytes, of the element named
@var{element} in the aggregate type @var{type} (which is presumably a
@i{struct}). It works similarly to the X11 macro @code{XtOffsetOf()}.

@end defmac

@defmac C_lengthof (array)

This macro returns the length of (the number of elements in) the array
@var{array}, which is assumed to be a stack-allocated array. If
@var{array} is a pointer, the results are undefined.

@end defmac

@node Miscellaneous Constants, , Convenience Macros, Types Macros and Constants
@comment  node-name,  next,  previous,  up
@section Miscellaneous Constants

The header file also defines the following constants:

@table @code
@item NUL
The @b{NUL} character (ASCII value 0); not to be confused with
@code{NULL}, the @i{NULL} pointer, a constant that is defined in
@file{stdio.h}.

@item CRLF
The string @code{"\r\n"}, or carriage return and line feed.

@end table

@node System Functions, Utility Functions, Types Macros and Constants, Top
@comment  node-name,  next,  previous,  up
@menu
* Byte Order Conversion Functions::