libslack

What is libslack?

Libslack is a library of general utilities designed to make UNIX/C programming a bit easier on the eye. It is a seemingly random collection of modules and functions that I find commonly useful. It was originally implemented as part of the daemon program (although some of the code dates back much further).

It's a small library with lots of functionality, accurately documented and thoroughly tested. Good library naming conventions are not rigorously observed on the principle that common operations should always be easy to write and code should always be easy to read.

Libslack is freely available under the GNU General Public License.

Features

• Program Framework

  The "framework" parts of libslack are bound to be the most objectionable. Nobody likes frameworks. Don't worry, there isn't much to it. If you don't like it, pretend it's not there.

  Libslack provides the ability for programs to identify themselves, perform command line option processing in a single line of code and produce "standard" GNU style --help, --version and usage messages. Debug and verbose messaging is also provided and is enabled by the use of "standard" --debug and --verbose command line options.

  Messages (including error, debug and verbose messages) are provided with clean call syntax and flexible semantics. Messages can be directed to log files, file descriptors, syslog or multiplexed to any of the above (and to anywhere else (e.g. dialog boxes) if you implement your own message handlers) without complicating the call syntax.

  ISO C imposes extreme restrictions on signal handlers. POSIX imposes less extreme but still annoying restrictions. Libslack contains functions that provide a level of abstraction between the signal handlers that you write and the real (ISO C compliant) signal handlers. This allows you to write unrestricted signal handlers.

  Coarse grained persistence of simple configuration information is provided by the use of Java style properties files in "well-known" locations.

• Daemon Services

  Libslack provides functions that make writing daemons trivial. It includes functions to become a daemon and to optionally create a locked pid file to ensure that only a single instance of a named daemon is ever active at the same time. The daemon function behaves appropriately if the client process is started by init(8) or inetd(8). There are also functions to streamline the parsing of simple configuration files (like those commonly found in the /etc directory). There are also functions that help you write more secure daemons (i.e. revoke setuid/setgid privileges, prevent core file generation, change user and group, test the safety of a given file path). There are also functions to check if a named daemon is running and to stop it.

• Network Services

  Libslack provides functions to simplify the implementation of network servers and clients (TCP, UDP, unicast and multicast) and the (text or binary) application protocols that they use. Network servers and clients can be setup in a single line of code. There is transparent support for IPv4, IPv6 and UNIX domain socket addresses. There is support for reliability over UDP. Text protocols are implemented by sequences of expect and send functions. Binary protocol packets can be packed and unpacked (using functions similar to pack() and unpack() in Perl but network/storage friendly). There's also a function to send mail.

• Agent Oriented Programming

  Libslack provides a generic agent oriented programming model in the form of the Agent data type. Like objects, agents can react to external stimuli. Unlike objects, agents can can also take independent actions. This is performed by multiplexing I/O events on arbitrary file descriptors using poll() or select() and also multiplexing timers for scheduling actions. Connecting and disconnecting file descriptors is done in constant time. Scheduling and cancelling actions is done in constant time. Timer maintenance is performed in constant average time. This means that agents are scalable with respect to the number of outstanding timers and can support thousands of scheduled actions. A single agent may be used like a simple event loop, or multiple agents can be connected to each other in arbitrary networks across multiple threads, processes and/or hosts. A single agent isn't scalable with respect to the number of connected file descriptors but multiple agents can be combined to achieve much higher scalability. They're useful for networked applications, distributed systems and simulations.

• Data Types

  Libslack provides a generic growable pointer array data type called List, a generic growable hash table data type called Map and a decent String data type that comes with heaps of functions (many lifted from Perl). There are also abstract singly and doubly linked list data types with optional, "growable" freelists.

• Decoupled Thread Safety

  Libslack provides the Locker data type which decouples thread synchronisation strategies from client code. This allows code to be written that delegates the choice of synchronisation strategy to the client. This enables run time selection of locking strategies which means it's even possible to let the end user specify which locking strategy to use. It supports mutual exclusion locks, readers/writer locks and no locking. There are also debug versions that print messages to standard output to help clients locate deadlocks. See http://raf.org/papers/mt-disciplined.html.

• Coprocesses and Pseudo Terminals

  Libslack provides functions for creating pseudo terminals portably and for creating coprocesses that use either pipes or a pseudo terminal for communication with the client process.

• Miscellaneous

  Libslack contains convenience/shorthand functions for random things such as reading a line of text with any line ending (UNIX, DOS or Macintosh), fifo and file control, retrieving POSIX.1 limits, parsing syslog facility/priority pairs, dynamic allocation of multi-dimensional arrays, memory pools, secure memory, secure memory pools, There's also a heap sort function. And there are also implementations of GNU getopt_long(), strlcat(), strlcpy(), snprintf(), vsnprintf(), vsscanf(), asprinf() and vasprintf() for systems that don't have them.

• Low-Level API

  Although there is a lot of functionality in libslack, the API itself is as low-level as possible. There are no gratuitous data structures that wrap around perfectly acceptable data structures that are provided by the system. For instance, the networking functions do not return some home grown Socket object. They return file descriptors just like underlying system calls. The coprocess API is similar in spirit to popen(3) and pclose(3). The fgetline(3) function interoperates perfectly with standard I/O. Errors are returned via errno just like system calls and some standard library functions. You may not like errno if you write threaded programs but I figured that until errno goes away, it's best to accept it and find a way to benefit from it. Unavoidably, the string module does wrap an object around perfectly good char pointers but the underlying char pointer is always accessible and many of the string functions have versions that work on ordinary C strings.

  The purpose of this design is Laziness. It means I don't have to wrap every net related system call or standard string function in an extra function and you don't have to learn a load of new identifiers for functionality that you already know how to access. The same goes for error codes. I don't want to re-invent them and you don't need to re-learn them. It also means that libslack functions can be more easily incorporated into existing programs to enhance their functionality without huge code rewrites and without the need for a steep learning curve.

• Accurate Documentation

  Every module has a manpage that explains every function in detail. The function signatures in the manpages are systematically checked against the source code to make sure that they never get out of sync.

  There are plenty of examples in the manpages. Most of them are systematically compiled and executed to make sure that they never get out of sync with the source code.

  The actual text of the manpages can't be systematically checked but it does get proofread regularly. If you find any errors of any kind in the documentation, please let me know.

  All of the documentation takes the form of manpages because manpages are faster and more accessible than anything else.

• Thorough Testing

  Libslack is thoroughly tested. This doesn't mean that there are no bugs but it does mean that there is a large list of bugs that it doesn't have. Excluding the snprintf module, there are nearly 2,800 tests. Including the snprintf module, there are nearly 150,000 tests. These tests also serve as extra examples.

For more information read the manual entries in the Documentation section.

Supported Platforms

Currently, libslack is only known to compile and work on:

• Linux 2.6 (i386, x86_64, debian-5.0.4, ubuntu-10.04, fedora-13)
• Solaris 10 10/09 (i386, amd64)
• OpenSolaris 2009/06 (i386, amd64)
• OpenBSD 4.7 (i386, amd64)
• FreeBSD 8.0 (i386, amd64)
• NetBSD 5.0.2 (i386, amd64)
• MacOSX 10.{4,5,6} (i386, x86_64, ppc)
• kFreeBSD 20090729 (i386)

It is written in ISO C using POSIX almost exclusively except for some BSD functions that appear on most systems (e.g. sockets). So it shouldn't be difficult to get it working on other (recent) systems that support ISO C, POSIX and XPG4.

Documentation

There is a README file, libslack overview manpage, a manpage for each module in libslack and a manpage for the libslack-config utility. There is also the paper MT-Disciplined - decoupling thread safety.

Download

Mailing Lists

If you'd like to be kept up to date with libslack releases or have questions or suggestions, you can join one or more of the following mailing lists (@libslack.org).

To subscribe to any of these mailing lists, send a mail message to listname-request@libslack.org with subscribe as the message body.

Or you can send a mail message to majordomo@libslack.org with subscribe listname in the message body. This way, you can include multiple subscribe commands to subscribe to multiple lists at the same time.

A digest version of each mailing list is also available. Subscribe to digests as above but append -digest to the listname.

Or

Note that these are all extremely low volume mailing lists so there's not much use for the digest lists.