--- /dev/null
+.\" -*-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 back 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 > .
+.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
+.B exc
+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
+.B alloc
+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.
+.PP
+The
+.B sub
+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.
+.SS "String handling"
+The
+.B str
+module provides some trivial string-manipulation functions which tend to
+be useful quite often.
+.PP
+The
+.B dstr
+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
+.B dspool
+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
+.B quis
+module remembers the name of the program and supplies it when asked.
+It's used in error messages and similar things.
+.PP
+The
+.B report
+module emits standard Unixy error messages. It provides functions
+.B moan
+and
+.B die
+which the author uses rather a lot.
+.PP
+The
+.B trace
+module (not yet documented)
+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
+.B sym
+module implements a rather good extending hash table. Keys and values can
+be arbitrary data.
+.PP
+The
+.B dynarray
+module (not yet documented) implements unbounded sparse arrays. It
+needs rewriting.
+.SS "Miscellaneous utilities"
+The
+.B crc32
+module calculates CRC values for strings. It's used by the symbol table
+manager as a hash function.
+.PP
+The
+.B lock
+module does POSIX
+.BR fcntl (2)-style
+locking with a timeout.
+.PP
+The
+.B lbuf
+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
+.B tv
+module provides some macros and functions for playing with
+.B "struct timeval"
+.PP
+The
+.B bits
+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
+.B mdwopt
+module implements a fairly serious options parser compatible with the
+GNU options parser.
+.PP
+The
+.B testrig
+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
+.B base64
+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
+.B url
+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
+.B sel
+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
+.B conn
+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
+.B selbuf
+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.
+.SH "SEE ALSO"
+.BR alloc (3),
+.BR base64 (3),
+.BR bits (3),
+.BR conn (3),
+.BR crc32 (3),
+.BR dspool (3),
+.BR dstr (3),
+.BR exc (3),
+.BR lbuf (3),
+.BR lock (3),
+.BR mdwopt (3),
+.BR quis (3),
+.BR report (3),
+.BR sel (3),
+.BR selbuf (3),
+.BR str (3),
+.BR sub (3),
+.BR sym (3),
+.BR tv (3),
+.BR url (3).
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>
~mdw / mLib / blobdiff