2 .TH mLib 3 "7 July 1999" mLib
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 simple veneers onto traditional memory allocation
50 doesn't actually depend on
52 being defined in the library) which raise exceptions when there's not
57 module handles efficient allocation of small blocks. It allocates
58 memory in relatively big chunks and divides the chunks up into small
59 blocks before returning them. It keeps lists of differently-sized
60 blocks so allocation and freeing is fast. The downside is that your
61 code must know how big a block is when it's being freed.
65 module (not yet documented) is a simple memory allocation tracker. It
66 can be handy when trying to fix memory leaks.
70 module provides some trivial string-manipulation functions which tend to
71 be useful quite often.
75 module implements a dynamic string data type. It works quite quickly
76 and well, and is handy in security-sensitive programs, to prevent
77 buffer-overflows. Dynamic strings are used occasionally through the
78 rest of the library, mainly as output arguments.
82 module implements a `pool' of dynamic strings which saves lots of
83 allocation and deallocation when a piece of code has high string
85 .SS "Program identification and error reporting"
88 module remembers the name of the program and supplies it when asked.
89 It's used in error messages and similar things.
93 module emits standard Unixy error messages. It provides functions
97 which the author uses rather a lot.
101 module (not yet documented)
102 provides an interface for emitting tracing information with configurable
103 verbosity levels. It needs improving to be able to cope with outputting
105 .SS "Other data types"
108 module implements a rather good extending hash table. Keys and values can
113 module (not yet documented) implements unbounded sparse arrays. It
115 .SS "Miscellaneous utilities"
118 module calculates CRC values for strings. It's used by the symbol table
119 manager as a hash function.
125 locking with a timeout.
129 module manipulates environment variables stored in a hashtable, and
130 converts between the hashtable and the standard array representation of
131 a process environment.
135 module manipulates file descriptor flags in a fairly painless way.
139 module implements a `line buffer', which is an object that emits
140 completed lines of text from an incoming asynchronous data stream. It's
141 remarkably handy in programs that want to read lines from pipes and
142 sockets can't block while waiting for a line-end to arrive.
146 module provides some macros and functions for playing with
147 .BR "struct timeval" .
151 module defines some types and macros for playing with words as chunks of
152 bits. There are portable rotate and shift macros (harder than you'd
153 think), and macros to do loading and storing in known-endian formats.
158 module implements a fairly serious options parser compatible with the
163 module provides a generic structure for reading test vectors from files
164 and running them through functions. I mainly use it for testing
165 cryptographic transformations of various kinds.
166 .SS "Encoding and decoding"
169 module does base64 encoding and decoding, as defined in RFC2045. Base64
170 encodes arbitrary binary data in a reliable way which is resistant to
171 character-set transformations and other mail transport bogosity.
175 module does urlencoding and decoding, as defined in RFC1866.
176 Urlencoding encodes arbitrary (but mostly text-like) name/value pairs as
177 a text string containing no whitespace.
178 .SS "Multiplexed I/O"
181 module provides a basis for doing nonblocking I/O in Unix systems. It
182 provides types and functions for receiving events when files are ready
183 for reading or writing, and when timers expire.
187 module implements nonblocking network connections in a way which fits in
190 system. It makes nonblocking connects pretty much trivial.
194 module attaches to the
196 system and sends an event when lines of text arrive on a file. It's
197 useful when reading text from a network connection.
201 module introduces signal handling into the multiplexed I/O world.
202 Signals are queued until dispatched through the normal
230 Mark Wooding, <mdw@nsict.org>
~mdw / mLib / blob