Insert missing `NAME' section. Use a pleasant `>=' sign when doing good

[mLib] / man / mLib.3

.\" -*-nroff-*-
.TH mLib 3 "7 July 1999" mLib
.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 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 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's used by the symbol table
manager as a hash function.
.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 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.
.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.
.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 on a file.  It's
useful when reading text from a network connection.
.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.
.PP
The
.BR bres (3)
module does background hostname and address resolution.
.SH "SEE ALSO"
.BR alloc (3),
.BR base64 (3),
.BR bits (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 hash (3),
.BR ident (3),
.BR lbuf (3),
.BR lock (3),
.BR mdwopt (3),
.BR quis (3),
.BR report (3),
.BR sel (3),
.BR selbuf (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@nsict.org>