X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/blobdiff_plain/8f45ff6cb9a269fc6f8f631908f93b4c8123419c..4aee39a18184ae8595936a03ad254c27d149a0eb:/mLib.3 diff --git a/mLib.3 b/mLib.3 new file mode 100644 index 0000000..174a03e --- /dev/null +++ b/mLib.3 @@ -0,0 +1,306 @@ +.\" -*-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 . +.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,