2 .TH mLib 3 "7 July 1999" "Straylight/Edgeware" "mLib utilities library"
4 mLib \- library of miscellaneous utilities
9 library is a mixed bag of things which the author finds useful in large
10 numbers of programs. As a result, its structure is somewhat arbitrary,
11 and it's accreted extra bits over time rather than actually being
12 designed as a whole. In the author's opinion this isn't too much of a
15 At the most granular level,
17 is split into `modules', each of which has its own header file and
18 manual page. Sometimes there are identifiable `chunks' of several
19 modules which fit together as a whole. Modules and chunks fit into
20 `layers', each depending on the ones below it. The header file for
28 This description is a bit abstract, and
30 as a result of its history, doesn't fit it as well as I might like.
31 Even so, it's not too bad a model really.
33 The rest of this section describes the various chunks and layers.
34 .SS "Exception handling"
35 Right at the bottom, there's a fairly primitive exception handling
36 system. It's provided by the
38 module, and stands alone. It's used mainly by the memory allocation
39 modules to raise exceptions when there's no more memory to be had.
40 .SS "Memory allocation"
43 module provides an abstraction of memory allocation. By writing
44 appropriate arena implementations, a client program can control where
45 and how memory is allocated for various structures.
49 module provides simple veneers onto traditional memory allocation
56 doesn't actually depend on
58 being defined in the library) which raise exceptions when there's not
59 enough memory left. These work through the
61 layer, so that the caller can control memory allocation.
65 module handles efficient allocation of small blocks. It allocates
66 memory in relatively big chunks and divides the chunks up into small
67 blocks before returning them. It keeps lists of differently-sized
68 blocks so allocation and freeing is fast. The downside is that your
69 code must know how big a block is when it's being freed.
73 module (not yet documented) is a simple memory allocation tracker. It
74 can be handy when trying to fix memory leaks.
78 module maintains resource pools which can manage memory and other
79 resources, all of the resources held in a pool being destroyed along
84 module provides some trivial string-manipulation functions which tend to
85 be useful quite often.
89 module implements a dynamic string data type. It works quite quickly
90 and well, and is handy in security-sensitive programs, to prevent
91 buffer-overflows. Dynamic strings are used occasionally through the
92 rest of the library, mainly as output arguments.
96 module implements a `pool' of dynamic strings which saves lots of
97 allocation and deallocation when a piece of code has high string
99 .SS "Program identification and error reporting"
102 module remembers the name of the program and supplies it when asked.
103 It's used in error messages and similar things.
107 module emits standard Unixy error messages. It provides functions
111 which the author uses rather a lot.
115 module provides an interface for emitting tracing information with
116 configurable verbosity levels. It needs improving to be able to cope
117 with outputting to the system log.
118 .SS "Other data types"
121 module provides the basics for an extending hashtable implementation.
122 Many different hashtable-based data structures can be constructed with
127 module implements a rather good general-purpose extending hash table.
128 Keys and values can be arbitrary data. It is implemented using
135 which are essentially strings with the property that two atoms have the
136 same address if and only if they have the same text, so they can be used
137 for rapid string comparisons. The
139 module implements a hash table which uses atoms as keys, thus saving
140 time spent hashing and comparing hash keys, and the space used for the
145 module implements dynamically resizing arrays which support Perl-like
146 stack operations efficiently.
147 .SS "Miscellaneous utilities"
150 module calculates CRC values for strings. It's used by the symbol table
151 manager as a hash function.
157 locking with a timeout.
161 module manipulates environment variables stored in a hashtable, and
162 converts between the hashtable and the standard array representation of
163 a process environment.
167 module manipulates file descriptor flags in a fairly painless way.
171 module allows you to easily find out whether a file has changed since
172 the last time you looked at it.
176 module implements a `line buffer', which is an object that emits
177 completed lines of text from an incoming asynchronous data stream. It's
178 remarkably handy in programs that want to read lines from pipes and
179 sockets can't block while waiting for a line-end to arrive. Similarly,
182 module implements a `packet buffer', which waits for packets of given
183 lengths to arrive before dispatching them to a handler.
187 module provides some macros and functions for playing with
188 .BR "struct timeval" .
192 module defines some types and macros for playing with words as chunks of
193 bits. There are portable rotate and shift macros (harder than you'd
194 think), and macros to do loading and storing in known-endian formats.
199 module implements a fairly serious options parser compatible with the
204 module provides a generic structure for reading test vectors from files
205 and running them through functions. I mainly use it for testing
206 cryptographic transformations of various kinds.
207 .SS "Encoding and decoding"
210 module does base64 encoding and decoding, as defined in RFC2045. Base64
211 encodes arbitrary binary data in a reliable way which is resistant to
212 character-set transformations and other mail transport bogosity.
216 module does urlencoding and decoding, as defined in RFC1866.
217 Urlencoding encodes arbitrary (but mostly text-like) name/value pairs as
218 a text string containing no whitespace.
219 .SS "Multiplexed I/O"
222 module provides a basis for doing nonblocking I/O in Unix systems. It
223 provides types and functions for receiving events when files are ready
224 for reading or writing, and when timers expire.
228 module implements nonblocking network connections in a way which fits in
231 system. It makes nonblocking connects pretty much trivial.
235 module attaches to the
237 system and sends an event when lines of text arrive from a file. It's
238 useful when reading text from a network connection. Similarly,
240 sents events when packets of given sizes arrive from a file.
244 module introduces signal handling into the multiplexed I/O world.
245 Signals are queued until dispatched through the normal
251 module provides a nonblocking ident (RFC931) client. The
253 module does background hostname and address resolution.
289 Mark Wooding, <mdw@nsict.org>
~mdw / mLib / blob