--- /dev/null
+.\" -*-nroff-*-
+.TH mLib 3 "7 July 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+mLib \- library of miscellaneous utilities
+.\" @mLib
+.SH DESCRIPTION
+The
+.B mLib
+library is a mixed bag of things which the author finds useful in large
+numbers of programs. As a result, its structure is somewhat arbitrary,
+and it's accreted extra bits over time rather than actually being
+designed as a whole. In the author's opinion this isn't too much of a
+hardship.
+.PP
+At the most granular level,
+.B mLib
+is split into `modules', each of which has its own header file and
+manual page. Sometimes there are identifiable `chunks' of several
+modules which fit together as a whole. Modules and chunks fit into
+`layers', each depending on the ones below it. The header file for
+module
+.I foo
+would be put in
+.BR <mLib/ \c
+.IR foo \c
+.BR .h> .
+.PP
+This description is a bit abstract, and
+.BR mLib ,
+as a result of its history, doesn't fit it as well as I might like.
+Even so, it's not too bad a model really.
+.PP
+The rest of this section describes the various chunks and layers.
+.SS "Exception handling"
+Right at the bottom, there's a fairly primitive exception handling
+system. It's provided by the
+.BR exc (3)
+module, and stands alone. It's used mainly by the memory allocation
+modules to raise exceptions when there's no more memory to be had.
+.SS "Memory allocation"
+The
+.BR arena (3)
+module provides an abstraction of memory allocation. By writing
+appropriate arena implementations, a client program can control where
+and how memory is allocated for various structures.
+.PP
+The
+.BR alloc (3)
+module provides simple veneers onto traditional memory allocation
+functions like
+.BR malloc (3)
+and
+.BR strdup (3)
+(although
+.B mLib
+doesn't actually depend on
+.B strdup
+being defined in the library) which raise exceptions when there's not
+enough memory left. These work through the
+.B arena
+layer, so that the caller can control memory allocation.
+.PP
+The
+.BR sub (3)
+module handles efficient allocation of small blocks. It allocates
+memory in relatively big chunks and divides the chunks up into small
+blocks before returning them. It keeps lists of differently-sized
+blocks so allocation and freeing is fast. The downside is that your
+code must know how big a block is when it's being freed.
+.PP
+The
+.B track
+module (not yet documented) is a simple memory allocation tracker. It
+can be handy when trying to fix memory leaks.
+.PP
+The
+.BR pool (3)
+module maintains resource pools which can manage memory and other
+resources, all of the resources held in a pool being destroyed along
+with the pool itself.
+.SS "String handling"
+The
+.BR str (3)
+module provides some trivial string-manipulation functions which tend to
+be useful quite often.
+.PP
+The
+.BR dstr (3)
+module implements a dynamic string data type. It works quite quickly
+and well, and is handy in security-sensitive programs, to prevent
+buffer-overflows. Dynamic strings are used occasionally through the
+rest of the library, mainly as output arguments.
+.PP
+The
+.BR buf (3)
+module provides simple functions for reading and writing binary data to
+or from fixed-sized buffers.
+.PP
+The
+.BR dspool (3)
+module implements a `pool' of dynamic strings which saves lots of
+allocation and deallocation when a piece of code has high string
+turnover.
+.SS "Program identification and error reporting"
+The
+.BR quis (3)
+module remembers the name of the program and supplies it when asked.
+It's used in error messages and similar things.
+.PP
+The
+.BR report (3)
+module emits standard Unixy error messages. It provides functions
+.B moan
+and
+.B die
+which the author uses rather a lot.
+.PP
+The
+.BR trace (3)
+module provides an interface for emitting tracing information with
+configurable verbosity levels. It needs improving to be able to cope
+with outputting to the system log.
+.SS "Other data types"
+The
+.BR hash (3)
+module provides the basics for an extending hashtable implementation.
+Many different hashtable-based data structures can be constructed with
+little effort.
+.PP
+The
+.BR sym (3)
+module implements a rather good general-purpose extending hash table.
+Keys and values can be arbitrary data. It is implemented using
+.BR hash (3).
+.PP
+The
+.BR atom (3)
+module implements
+.IR atoms ,
+which are essentially strings with the property that two atoms have the
+same address if and only if they have the same text, so they can be used
+for rapid string comparisons. The
+.BR assoc (3)
+module implements a hash table which uses atoms as keys, thus saving
+time spent hashing and comparing hash keys, and the space used for the
+keys.
+.PP
+The
+.BR darray (3)
+module implements dynamically resizing arrays which support Perl-like
+stack operations efficiently.
+.SS "Miscellaneous utilities"
+The
+.BR crc32 (3)
+module calculates CRC values for strings. It used to be used by the
+symbol table manager as a hash function.
+.PP
+The
+.BR unihash (3)
+module implements a simple but efficient universal hashing family. This
+is a keyed hash function which provides security against an adversary
+choosing input to a hash table deliberately to cause collisions.
+.PP
+The
+.BR lock (3)
+module does POSIX
+.BR fcntl (2)-style
+locking with a timeout.
+.PP
+The
+.BR env (3)
+module manipulates environment variables stored in a hashtable, and
+converts between the hashtable and the standard array representation of
+a process environment.
+.PP
+The
+.BR fdflags (3)
+module manipulates file descriptor flags in a fairly painless way.
+.PP
+The
+.BR fwatch (3)
+module allows you to easily find out whether a file has changed since
+the last time you looked at it.
+.PP
+The
+.BR lbuf (3)
+module implements a `line buffer', which is an object that emits
+completed lines of text from an incoming asynchronous data stream. It's
+remarkably handy in programs that want to read lines from pipes and
+sockets can't block while waiting for a line-end to arrive. Similarly,
+the
+.BR pkbuf (3)
+module implements a `packet buffer', which waits for packets of given
+lengths to arrive before dispatching them to a handler.
+.PP
+The
+.BR tv (3)
+module provides some macros and functions for playing with
+.BR "struct timeval" .
+.PP
+The
+.BR bits (3)
+module defines some types and macros for playing with words as chunks of
+bits. There are portable rotate and shift macros (harder than you'd
+think), and macros to do loading and storing in known-endian formats.
+values.
+.PP
+The
+.BR mdwopt (3)
+module implements a fairly serious options parser compatible with the
+GNU options parser.
+.PP
+The
+.BR testrig (3)
+module provides a generic structure for reading test vectors from files
+and running them through functions. I mainly use it for testing
+cryptographic transformations of various kinds.
+.SS "Encoding and decoding"
+The
+.BR base64 (3)
+module does base64 encoding and decoding, as defined in RFC2045. Base64
+encodes arbitrary binary data in a reliable way which is resistant to
+character-set transformations and other mail transport bogosity. The
+.BR base32 (3)
+module does base32 encoding and decoding, as defined in RFC2938. This
+is a mad format which is needed for sha1 URNs, for no good reason. The
+.BR hex (3)
+module does hex encoding and decoding.
+.PP
+The
+.BR url (3)
+module does urlencoding and decoding, as defined in RFC1866.
+Urlencoding encodes arbitrary (but mostly text-like) name/value pairs as
+a text string containing no whitespace.
+.SS "Multiplexed I/O"
+The
+.BR sel (3)
+module provides a basis for doing nonblocking I/O in Unix systems. It
+provides types and functions for receiving events when files are ready
+for reading or writing, and when timers expire.
+.PP
+The
+.BR conn (3)
+module implements nonblocking network connections in a way which fits in
+with the
+.B sel
+system. It makes nonblocking connects pretty much trivial.
+.PP
+The
+.BR selbuf (3)
+module attaches to the
+.B sel
+system and sends an event when lines of text arrive from a file. It's
+useful when reading text from a network connection. Similarly,
+.BR selpk (3)
+sents events when packets of given sizes arrive from a file.
+.PP
+The
+.BR sig (3)
+module introduces signal handling into the multiplexed I/O world.
+Signals are queued until dispatched through the normal
+.B sel
+mechanism.
+.PP
+The
+.BR ident (3)
+module provides a nonblocking ident (RFC931) client. The
+.BR bres (3)
+module does background hostname and address resolution.
+.SH "SEE ALSO"
+.BR alloc (3),
+.BR assoc (3),
+.BR atom (3),
+.BR base64 (3),
+.BR bits (3),
+.BR buf (3),
+.BR bres (3),
+.BR conn (3),
+.BR crc32 (3),
+.BR darray (3),
+.BR dspool (3),
+.BR dstr (3),
+.BR env (3),
+.BR exc (3),
+.BR fdflags (3),
+.BR fwatch (3),
+.BR hash (3),
+.BR ident (3),
+.BR lbuf (3),
+.BR lock (3),
+.BR mdwopt (3),
+.BR pkbuf (3),
+.BR quis (3),
+.BR report (3),
+.BR sel (3),
+.BR selbuf (3),
+.BR selpk (3),
+.BR sig (3),
+.BR str (3),
+.BR sub (3),
+.BR sym (3),
+.BR trace (3),
+.BR tv (3),
+.BR url (3).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blobdiff