QCI C Utilities Version 1.0b2 README
------------------------------------

QLUE Consulting, Inc.

-What Is It?
-How Can I Use It?
-What Do You Mean By "Portable"?
-What Documentation Is Available?
-Why Is This Package Being Released?
-How Can I Help?
-OK, Where Can I Get It?
-Who Do I Contact?
-What's In This Release?

What Is It?
-----------

This is a C library that is used in-house at QCI in the development of all
C/C++ programs. It is a portability layer, a collection of frequently used
routines, a collection of data structures (currently only a hash table), and
a set of wrappers over system calls that provide additional safety.

The goal of the library is to reduce the amount of duplicated code in
projects by providing high-quality reusable tools, to reduce
testing/debugging time by providing wrappers over calls that are common
sources of errors, and to reduce porting time by providing portable
replacements for functions that we want to use but know we shouldn't.

Important secondary goals include giving libraries written on top of this
one a consitent and familiar feel, and reducing the amount of time we spend
writing @!^%#&&!! configure scripts for new projects.

How Can I Use It?
-----------------

This package is *not* GPLed, and therefore can be used in commercial
packages. This was very important to us (see LICENSE.txt for info).

The C Utilities Library is meant to be used at the base of every new C/C++
project. The C Utilities package uses GNU autoconf to provide portability
for itself but takes the process one step further. It detects potential
portability problems with the OS it is installed on and packages all
necessary replacement functions in a library so that they can be reused by
other packages without those packages haveing to test for the required
features themselves. This means that most packages based on this library
need only minimal configure scripts.

In addition to elements of platform standards (e.g. POSIX) that may be
missing on a given platform, the utilities library provides replacements for
functions which are non-standard but dreadfully convenient, like asnprintf.
On platforms where vendors provide a function, the native one is used
directly with no overhead. Otherwise, the replacement is used, giving an
application programmer the best of what platforms have to offer with minimal
effort.

We have also added functions to the library that we wish standard
libraries would provide, like string trimming functions, a hash table, and a
demonize function that does everything that a daemon process needs to do at
startup.
Using these functions may reduce your development and testing time
significantly.

Lastly, we have provided the standard wrappers which programmers write for
nearly every project (if they are wise...), like xmalloc, which checks the
return code on malloc and does something about it. Because we have packaged
these wrappers in a library, we don't have to rewrite them continually, they
can be more sophisticated and thorough than most of the one-off wrappers, and
they can be used internally.

What Do You Mean By "Portable"?
-------------------------------

Our portability goal is to have the best functions from all platforms
available on the platforms that we commonly use for development/deployment,
namely Linux, Solaris, OSF, HP/UX, and AIX, roughly in that order. We would
also like porting to be not-too-traumatic when we go to a less common
platform like BSDi, QNX, or NT under a POSIX layer. We are not looking for
universal portability and can therefore trade support for less hospitable,
out-of-date, or severely buggy platforms/compilers for functionality and
cleanliness of implementation.

In particular, the library demands an OS that at least knows about POSIX and
supports ANSI c89 and we don't plan on changing this. On the other hand, we
don't consider a library that only supports versions of OSes deployed since
1996 "portable". We certainly have no objection to adding checks to support
uncommon platforms that do not reduce functionality elsewhere and do not
increase complexity/maintenance requirements outrageously.

In short, we're looking for a the most convenient tradeoff between
portability and programmer coddling ;-).

What Documentation Is Available?
--------------------------------
There is some through and (we think) well-written LaTeX documentation for
the library interfaces. It is also provided pre-formatted in PostScript and
PDF. Installation docs are currently sparse but hopefully adequate and will
improve.

Why Is This Package Being Released?
-----------------------------------

We could say (and would mean) all of the usual things about giving back to
the community, creating goodwill, etc. QCI uses Linux and other open-source
software heavily for internal development (we often can't deliver them to
our clients... yet) and these tools have saved uncounted programmer-hours
and software purchase dollars.

However, when it gets down to it, we have three "practical" reasons:

1) We have only intermittent access to most of the platforms we would like
to test this library on. We always have Linux and Solaris(x86) available
in-house but we can only test on other platforms when we rent them for
specific projects or when our clients are kind enough to let us do some
testing on their systems. We want to encourage users to send us bug-reports
(preferably patches) for other platforms.

2) We want to make this library more commonly used so that it will appear more
acceptable to our clients.

3) Marketting. If people use it and like it, people may give us more business
(or so the theory goes...). At the very least, it gives us an example fo our
work that we can readily point to without breaching confidentiality or
intellectual property rights with previous clients.

How Can I Help?
---------------

Download it, try it, send us fixes and improvements. We'll incorporate what
we can and make new releases. Be aware that we (and others) have deployed
software based on this package, so backwards compatibility is a high
concern.

We have a coding standard that is used in this package. It also contains
generic advice for writing good code that was mainly learned the hard way
and therefore may be interesting. Please look through it
(http://www.qlue.com). We won't reject fixes or improvements that don't fit
in with our scheme of things, but they may take longer to incorporate.

When sending in bug reports, fixes, comments, suggestions, *please* tell us
what platform, version, compiler, etc., you are using. We don't have the
resources to track down bugs from incomplete reports.

We would be most appreciative if people could send/lend us hardware for
testing purposes. The hardware does not have to be fast, recent, etc., but
just capable of running relatively recent OS versions (e.g.: cast-off SPARC
IIs). Smaller hardware is better. We would also be interested in shell
accounts on systems available from the 'net for compiling and running tests.

OK, Where Can I Get It?
-----------------------

http://www.qlue.org is the primary site. This site is currently undergoing
renovations.

We also habitually put the package (in source) in
ftp://sunsite.unc.edu/pub/Linux/libs and on some of the major ftp sites
(e.g.: ftp.cdrom.com).

Since there doesn't seem to be a major archive for non-platform-specific
C/C++ development libraries (?), we are looking into hosting one.

Who Do I Contact?
-----------------
This package is currently maintained by Eric Vought, evought@qlue.com.

What's In This Release?
_______________________

This is our second beta release. The first release was tested on several
versions of HP/UX, Solaris, OSF, and Linux and was used in software for
several clients. This release has so far been tested on several linux
flavors with gcc and egcs and under AIX 4.3 (xlc). We will also test it on
Solaris x86 in house. We are looking for people to verify that it still
works on the previous platforms (we anticipate no problems).

The main new features of this release are more wrapper functions, minor
corrections for AIX. We have also added some flexibility to error handling
and added QCI_demonize().

We have not figured out all of the compiler switches for ANSI compatibility
on all platforms. Some compilers won't even recognize basic ANSI constructs
without special switches (e.g.: AIX, HP/UX). The easiest way around this is
to use the alias "c89" that is often provided by the vendor. e.g.:

CC=c89 ./configure

autoconf looks for and uses "gcc" by default, then checks for "cc". In later
releases, we will probably have autoconf look for "gcc", then "egcs", then
"c89", then "cc", to make this process more transparent. Do note that if you
have gcc installed on a system and want this library to use the system
compiler, you have to use CC=cc.

The Makefile has extra targets for using TET, the X/Open test harness. Feel
free to use these as examples for your own Makefiles. "make test" builds and
runs the test suite (requires tet and options to configure). "make
test_report" runs the (ugly) test output through a Perl script to make it
readable (we don't provide this- dig through the TET contributed software).

We have included all of the autoconf input files necessary to maintain the
package. We have a habit of checking third party software packages into our
own CVS repository in order to track patches that we make. If you do this,
you may want to do a "make maintainer-clean" before checking it in to get
rid of generated files like Makefile.in. On check out (assuming you have
autoconf, etc., installed), run the shell script "add-water" to reconstitute
the package. When makeing changes, be sure to modify the bottom level files
or the changes will disappear the next time the files are regenerated.
