chiark / gitweb /
codec/{base32,hex}.h: Include `codec.h'.
[mLib] / mLib.3
05fbeb03 1.\" -*-nroff-*-
fbf20b5b 2.TH mLib 3 "7 July 1999" "Straylight/Edgeware" "mLib utilities library"
05fbeb03 3.SH NAME
4mLib \- library of miscellaneous utilities
5.\" @mLib
8.B mLib
484eed5d 9library is a mixed bag of things which the author finds useful in large
05fbeb03 10numbers of programs. As a result, its structure is somewhat arbitrary,
11and it's accreted extra bits over time rather than actually being
12designed as a whole. In the author's opinion this isn't too much of a
15At the most granular level,
16.B mLib
17is split into `modules', each of which has its own header file and
18manual page. Sometimes there are identifiable `chunks' of several
19modules which fit together as a whole. Modules and chunks fit into
20`layers', each depending on the ones below it. The header file for
22.I foo
23would be put in
24.BR <mLib/ \c
25.IR foo \c
484eed5d 26.BR .h> .
05fbeb03 27.PP
28This description is a bit abstract, and
29.BR mLib ,
30as a result of its history, doesn't fit it as well as I might like.
31Even so, it's not too bad a model really.
33The rest of this section describes the various chunks and layers.
34.SS "Exception handling"
35Right at the bottom, there's a fairly primitive exception handling
36system. It's provided by the
484eed5d 37.BR exc (3)
05fbeb03 38module, and stands alone. It's used mainly by the memory allocation
39modules to raise exceptions when there's no more memory to be had.
40.SS "Memory allocation"
9787c8a8 42.BR arena (3)
43module provides an abstraction of memory allocation. By writing
44appropriate arena implementations, a client program can control where
45and how memory is allocated for various structures.
484eed5d 48.BR alloc (3)
05fbeb03 49module provides simple veneers onto traditional memory allocation
50functions like
51.BR malloc (3)
53.BR strdup (3)
55.B mLib
56doesn't actually depend on
57.B strdup
58being defined in the library) which raise exceptions when there's not
9787c8a8 59enough memory left. These work through the
60.B arena
61layer, so that the caller can control memory allocation.
05fbeb03 62.PP
484eed5d 64.BR sub (3)
05fbeb03 65module handles efficient allocation of small blocks. It allocates
66memory in relatively big chunks and divides the chunks up into small
67blocks before returning them. It keeps lists of differently-sized
68blocks so allocation and freeing is fast. The downside is that your
69code must know how big a block is when it's being freed.
72.B track
73module (not yet documented) is a simple memory allocation tracker. It
74can be handy when trying to fix memory leaks.
9787c8a8 75.PP
77.BR pool (3)
78module maintains resource pools which can manage memory and other
79resources, all of the resources held in a pool being destroyed along
80with the pool itself.
05fbeb03 81.SS "String handling"
484eed5d 83.BR str (3)
05fbeb03 84module provides some trivial string-manipulation functions which tend to
85be useful quite often.
484eed5d 88.BR dstr (3)
05fbeb03 89module implements a dynamic string data type. It works quite quickly
90and well, and is handy in security-sensitive programs, to prevent
91buffer-overflows. Dynamic strings are used occasionally through the
92rest of the library, mainly as output arguments.
9b5ac6ff 95.BR buf (3)
96module provides simple functions for reading and writing binary data to
97or from fixed-sized buffers.
484eed5d 100.BR dspool (3)
05fbeb03 101module implements a `pool' of dynamic strings which saves lots of
102allocation and deallocation when a piece of code has high string
104.SS "Program identification and error reporting"
484eed5d 106.BR quis (3)
05fbeb03 107module remembers the name of the program and supplies it when asked.
108It's used in error messages and similar things.
484eed5d 111.BR report (3)
05fbeb03 112module emits standard Unixy error messages. It provides functions
113.B moan
115.B die
116which the author uses rather a lot.
53e76188 119.BR trace (3)
120module provides an interface for emitting tracing information with
121configurable verbosity levels. It needs improving to be able to cope
122with outputting to the system log.
05fbeb03 123.SS "Other data types"
7eb5aec5 125.BR hash (3)
126module provides the basics for an extending hashtable implementation.
127Many different hashtable-based data structures can be constructed with
128little effort.
484eed5d 131.BR sym (3)
7eb5aec5 132module implements a rather good general-purpose extending hash table.
133Keys and values can be arbitrary data. It is implemented using
134.BR hash (3).
05fbeb03 135.PP
1025598e 137.BR atom (3)
138module implements
139.IR atoms ,
140which are essentially strings with the property that two atoms have the
141same address if and only if they have the same text, so they can be used
142for rapid string comparisons. The
143.BR assoc (3)
144module implements a hash table which uses atoms as keys, thus saving
145time spent hashing and comparing hash keys, and the space used for the
53e76188 149.BR darray (3)
150module implements dynamically resizing arrays which support Perl-like
151stack operations efficiently.
05fbeb03 152.SS "Miscellaneous utilities"
484eed5d 154.BR crc32 (3)
6f444bda 155module calculates CRC values for strings. It used to be used by the
156symbol table manager as a hash function.
159.BR unihash (3)
160module implements a simple but efficient universal hashing family. This
161is a keyed hash function which provides security against an adversary
162choosing input to a hash table deliberately to cause collisions.
05fbeb03 163.PP
484eed5d 165.BR lock (3)
05fbeb03 166module does POSIX
167.BR fcntl (2)-style
168locking with a timeout.
484eed5d 171.BR env (3)
3fecac47 172module manipulates environment variables stored in a hashtable, and
173converts between the hashtable and the standard array representation of
174a process environment.
484eed5d 177.BR fdflags (3)
3fecac47 178module manipulates file descriptor flags in a fairly painless way.
32e1147e 181.BR fwatch (3)
182module allows you to easily find out whether a file has changed since
183the last time you looked at it.
484eed5d 186.BR lbuf (3)
05fbeb03 187module implements a `line buffer', which is an object that emits
188completed lines of text from an incoming asynchronous data stream. It's
189remarkably handy in programs that want to read lines from pipes and
1025598e 190sockets can't block while waiting for a line-end to arrive. Similarly,
192.BR pkbuf (3)
193module implements a `packet buffer', which waits for packets of given
194lengths to arrive before dispatching them to a handler.
05fbeb03 195.PP
484eed5d 197.BR tv (3)
05fbeb03 198module provides some macros and functions for playing with
484eed5d 199.BR "struct timeval" .
05fbeb03 200.PP
484eed5d 202.BR bits (3)
05fbeb03 203module defines some types and macros for playing with words as chunks of
204bits. There are portable rotate and shift macros (harder than you'd
205think), and macros to do loading and storing in known-endian formats.
484eed5d 209.BR mdwopt (3)
05fbeb03 210module implements a fairly serious options parser compatible with the
211GNU options parser.
484eed5d 214.BR testrig (3)
05fbeb03 215module provides a generic structure for reading test vectors from files
216and running them through functions. I mainly use it for testing
217cryptographic transformations of various kinds.
218.SS "Encoding and decoding"
484eed5d 220.BR base64 (3)
05fbeb03 221module does base64 encoding and decoding, as defined in RFC2045. Base64
222encodes arbitrary binary data in a reliable way which is resistant to
d4efbcd9 223character-set transformations and other mail transport bogosity. The
9b64ede2 224.BR base32 (3)
225module does base32 encoding and decoding, as defined in RFC2938. This
226is a mad format which is needed for sha1 URNs, for no good reason. The
227.BR hex (3)
228module does hex encoding and decoding.
05fbeb03 229.PP
484eed5d 231.BR url (3)
05fbeb03 232module does urlencoding and decoding, as defined in RFC1866.
233Urlencoding encodes arbitrary (but mostly text-like) name/value pairs as
234a text string containing no whitespace.
235.SS "Multiplexed I/O"
484eed5d 237.BR sel (3)
05fbeb03 238module provides a basis for doing nonblocking I/O in Unix systems. It
239provides types and functions for receiving events when files are ready
240for reading or writing, and when timers expire.
484eed5d 243.BR conn (3)
05fbeb03 244module implements nonblocking network connections in a way which fits in
245with the
246.B sel
247system. It makes nonblocking connects pretty much trivial.
484eed5d 250.BR selbuf (3)
05fbeb03 251module attaches to the
252.B sel
1025598e 253system and sends an event when lines of text arrive from a file. It's
254useful when reading text from a network connection. Similarly,
255.BR selpk (3)
256sents events when packets of given sizes arrive from a file.
484eed5d 257.PP
259.BR sig (3)
260module introduces signal handling into the multiplexed I/O world.
261Signals are queued until dispatched through the normal
262.B sel
83856dde 264.PP
266.BR ident (3)
1025598e 267module provides a nonblocking ident (RFC931) client. The
83856dde 268.BR bres (3)
269module does background hostname and address resolution.
05fbeb03 270.SH "SEE ALSO"
271.BR alloc (3),
1025598e 272.BR assoc (3),
273.BR atom (3),
05fbeb03 274.BR base64 (3),
275.BR bits (3),
9b5ac6ff 276.BR buf (3),
83856dde 277.BR bres (3),
05fbeb03 278.BR conn (3),
279.BR crc32 (3),
53e76188 280.BR darray (3),
05fbeb03 281.BR dspool (3),
282.BR dstr (3),
3fecac47 283.BR env (3),
05fbeb03 284.BR exc (3),
3fecac47 285.BR fdflags (3),
32e1147e 286.BR fwatch (3),
7eb5aec5 287.BR hash (3),
83856dde 288.BR ident (3),
05fbeb03 289.BR lbuf (3),
290.BR lock (3),
291.BR mdwopt (3),
1025598e 292.BR pkbuf (3),
05fbeb03 293.BR quis (3),
294.BR report (3),
295.BR sel (3),
296.BR selbuf (3),
1025598e 297.BR selpk (3),
484eed5d 298.BR sig (3),
05fbeb03 299.BR str (3),
300.BR sub (3),
301.BR sym (3),
53e76188 302.BR trace (3),
05fbeb03 303.BR tv (3),
304.BR url (3).
9b5ac6ff 306Mark Wooding, <>