cutils - Some Useful C-Utilities

Object

Libcutils provides a self-contained set of fundamental routines which are
essential to basically any Unix utility or daemon application written in C. The
library provides fundamental data structures such as lists, hash-maps, strings
and parsing functions for JSON or the typical dot-file based configuration data.
The following list summarizes the currently supported functionality:

• length delimited instead of NULL terminated strings
• memory management based on reference counting
• several list processing functions like iterators and map-reduce
• support of Ideal Hash Tries
  for highly efficient hash map data structures
• parsers for JSON data and the text configuration files found
  in Unix system
• doubly linked circular lists for reliable event queues
• support for test and debugging of memory management problems such as memory leaks

This library is the result of several years of practical experience in
C-programming and the rediscovery of a (more) functional programming style
mainly driven by extremly positive experiences with the relatively new
Programming Language Clojure.

How to build and use the library.

In the following we give a very brief overview how to get things up and running.
For a more detailed explanation about underlying concepts refer to the complete
API description.

Most of the functions within libcutils exclusively require the prencense of
a C compiler compliant to ANSI-C or C99. The event processing functions
currently refer to the pthread library and the configure script of the
build system requires a Unix shell and make. In case the source code
is fetched from a git repository you will furthermore need to have git
and autotools consisted out of
autoconf,
automake and
libtool installed on your build machine.

Download, Build and Installation

On Unix, that is any Linux variant, Mac OS X or cygwin /
mingw under the Windows platform, the download and build
process is done with the following shell commands:

git clone git://github.com/linneman/libcutils.git
cd libcutils

autoreconf -i # generate configure script

./configure
make
make install # as root

In case you download an official release as gzipped tarball you exclusively will
need the last three commands since the configure script is already delivered
with stable releases.

Pay attention to the fact that the library is per default installed under
/usr/local/lib which is not in the library path on many linux distributions.
Thus you will need to put /usr/local/lib to your library path e.g. by defining
the enviroment variable

export LD_LIBRARY_PATH=/usr/local/lib.

Alternatively, you can edit /etc/ld.so.conf which contains the default
directories searched. Note that you may also need to update the cache
/etc/ld.so.cache by running ldconfig (as root, or with sudo).

Testing the library

The library comes with the console based test application test_cutilslib which
will check all functions to execute appropriately. The test program can be
exectuded also by make with the command:

make check

The source files for all corresponding module tests follow the naming convention
test\_<module>.c and serve as sample application at the same time. We strictly
recommend to study these sample files for a better understanding how to make
best use of the provided functionality.

Integrating the libcutils within your own project

The interation of the libctutils within your own FSF compliant application is a
nobrainer. Just put the following line within your configure.ac file:

PKG_CHECK_MODULES(libcutils, libcutils >= 0.1 )

Refer to libcutils/example for a small sample project which provide a complete
example about a minimum version of configure.ac and Makefile.am as the input
for the autoconf and automake.

Licence

This implementation code stands under the terms of the
GNU LESSER GENERAL PUBLIC LICENSE, Version 2.1.

April 2014, Otto Linnemann