skalibs: the stddjb library interface
Keywords: skalibs stddjb libstddjb library interface

libskarnet
skalibs
Software
www.skarnet.org

# The `stddjb` library interface

`libstddjb` is the base, and the most important part, of skalibs. It is a set of general-purpose C functions wrapping some system calls, hiding some Unix portability problems, providing some basic low-level buffering functions and string handling, and generally offering a nice API to Unix programming - in many ways nicer and safer than the "standard" Unix APIs like `stdio.h`.

It is mostly based on some excellent code written and placed into the public domain by D. J. Bernstein.

## Compiling

- The libstddjb functions are available under the `skalibs/stddjb.h` header, which includes a lot of lower-level headers. If you know what lower-level headers to use, you might speed up your compilation process by including them directly.

## Programming

- skalibs/alarm.h: sub-second precision alarm()
- skalibs/alloc.h: basic heap memory allocation primitives
- skalibs/allreadwrite.h: safe wrappers around I/O functions, extra I/O functions
- skalibs/bitarray.h: how to handle large arrays of bits
- skalibs/bufalloc.h: bufferized output (with dynamically allocated buffers)
- skalibs/buffer.h: bufferized I/O (with statically allocated buffers)
- skalibs/bytestr.h: basic operations on strings and byte arrays
- skalibs/cdb.h: how to read cdb files
- skalibs/cdbmake.h: how to write cdb files
- skalibs/cspawn.h: child spawning primitives that use posix_spawn instead of fork when supported
- skalibs/direntry.h: portable directory operations
- skalibs/djbtime.h: conversions between date and time formats
- skalibs/djbunix.h: management of basic Unix concepts
- skalibs/envalloc.h: management of dynamically allocated argv and envp
- skalibs/env.h: management of argv and envp
- skalibs/exec.h: execution functions, with or without a newly built environment
- skalibs/fmtscan.h: formatters (printers) and scanners (parsers) for basic C types
- skalibs/genalloc.h: generic advanced management of dynamically allocated structures
- skalibs/genwrite.h: interface to generic writes either to strallocs or to buffers
- skalibs/getpeereid.h: the `getpeereid()` system call
- skalibs/iopause.h: the skalibs event loop selection function
- skalibs/lolstdio.h: printf-like functions writing into buffers or bufallocs
- skalibs/mininetstring.h: a protocol to transmit variable-length messages (limited to 64kB)
- skalibs/netstring.h: a protocol to transmit variable-length messages (limited to 2^32 bytes)
- skalibs/segfault.h: voluntary error generation
- skalibs/selfpipe.h: automated selfpipe trick (i.e. how to safely handle signals in event loops)
- skalibs/sgetopt.h: `getopt()`-style command-line options management
- skalibs/sig.h: safe signal management
- skalibs/siovec.h: scatter/gather IO primitives working with an iovec structure
- skalibs/skamisc.h: general string quoting and parsing; miscellaneous, unclassifiable functions
- skalibs/socket.h: UNIX, INET and INET6 domain sockets
- skalibs/stralloc.h: advanced management of dynamically allocated strings
- skalibs/strerr.h: print error messages
- skalibs/tai.h: time, timers and system clock

The following headers are automatically generated at compile-time, when the headers subsystem is made. The `skalibs/stddjb.h` file also includes them.

- skalibs/uint16.h: operations with 16-bit unsigned integers
- skalibs/uint32.h: operations with 32-bit unsigned integers
- skalibs/uint64.h: operations with 64-bit unsigned integers
- skalibs/types.h: portable helpers for common Unix types: size_t, uid_t, gid_t, pid_t, time_t, dev_t and ino_t.
- skalibs/error.h: portable macros for errno management
- skalibs/setgroups.h: stub for the setgroups() function, for systems that do not define it
- skalibs/ip46.h: IPv4/IPv6 abstraction layer

Additionally, `stddjb.h` also includes the following headers, which are not associated with any code and are mostly self-explanatory:

- skalibs/gccattributes.h: wrappers around a few GCC-specific optimizations
- skalibs/diuint.h: for associative arrays of unsigned integers
- skalibs/diuint32.h: for associative arrays of 32-bit unsigned integers
- skalibs/disize.h: for associative arrays of size_t
- skalibs/nsig.h: the number of system signals, for systems that do not define it
- skalibs/nonposix.h: feature test macros for non-POSIX-compliant systems