05fbeb03 |
1 | .\" -*-nroff-*- |
fbf20b5b |
2 | .TH mLib 3 "7 July 1999" "Straylight/Edgeware" "mLib utilities library" |
05fbeb03 |
3 | .SH NAME |
4 | mLib \- library of miscellaneous utilities |
5 | .\" @mLib |
6 | .SH DESCRIPTION |
7 | The |
8 | .B mLib |
484eed5d |
9 | library is a mixed bag of things which the author finds useful in large |
05fbeb03 |
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 |
13 | hardship. |
14 | .PP |
15 | At the most granular level, |
16 | .B mLib |
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 |
21 | module |
22 | .I foo |
23 | would be put in |
24 | .BR <mLib/ \c |
25 | .IR foo \c |
484eed5d |
26 | .BR .h> . |
05fbeb03 |
27 | .PP |
28 | This description is a bit abstract, and |
29 | .BR mLib , |
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. |
32 | .PP |
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 |
484eed5d |
37 | .BR exc (3) |
05fbeb03 |
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" |
41 | The |
9787c8a8 |
42 | .BR arena (3) |
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. |
46 | .PP |
47 | The |
484eed5d |
48 | .BR alloc (3) |
05fbeb03 |
49 | module provides simple veneers onto traditional memory allocation |
50 | functions like |
51 | .BR malloc (3) |
52 | and |
53 | .BR strdup (3) |
54 | (although |
55 | .B mLib |
56 | doesn't actually depend on |
57 | .B strdup |
58 | being defined in the library) which raise exceptions when there's not |
9787c8a8 |
59 | enough memory left. These work through the |
60 | .B arena |
61 | layer, so that the caller can control memory allocation. |
05fbeb03 |
62 | .PP |
63 | The |
484eed5d |
64 | .BR sub (3) |
05fbeb03 |
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. |
70 | .PP |
71 | The |
72 | .B track |
73 | module (not yet documented) is a simple memory allocation tracker. It |
74 | can be handy when trying to fix memory leaks. |
9787c8a8 |
75 | .PP |
76 | The |
77 | .BR pool (3) |
78 | module maintains resource pools which can manage memory and other |
79 | resources, all of the resources held in a pool being destroyed along |
80 | with the pool itself. |
05fbeb03 |
81 | .SS "String handling" |
82 | The |
484eed5d |
83 | .BR str (3) |
05fbeb03 |
84 | module provides some trivial string-manipulation functions which tend to |
85 | be useful quite often. |
86 | .PP |
87 | The |
484eed5d |
88 | .BR dstr (3) |
05fbeb03 |
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. |
93 | .PP |
94 | The |
484eed5d |
95 | .BR dspool (3) |
05fbeb03 |
96 | module implements a `pool' of dynamic strings which saves lots of |
97 | allocation and deallocation when a piece of code has high string |
98 | turnover. |
99 | .SS "Program identification and error reporting" |
100 | The |
484eed5d |
101 | .BR quis (3) |
05fbeb03 |
102 | module remembers the name of the program and supplies it when asked. |
103 | It's used in error messages and similar things. |
104 | .PP |
105 | The |
484eed5d |
106 | .BR report (3) |
05fbeb03 |
107 | module emits standard Unixy error messages. It provides functions |
108 | .B moan |
109 | and |
110 | .B die |
111 | which the author uses rather a lot. |
112 | .PP |
113 | The |
53e76188 |
114 | .BR trace (3) |
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. |
05fbeb03 |
118 | .SS "Other data types" |
119 | The |
7eb5aec5 |
120 | .BR hash (3) |
121 | module provides the basics for an extending hashtable implementation. |
122 | Many different hashtable-based data structures can be constructed with |
123 | little effort. |
124 | .PP |
125 | The |
484eed5d |
126 | .BR sym (3) |
7eb5aec5 |
127 | module implements a rather good general-purpose extending hash table. |
128 | Keys and values can be arbitrary data. It is implemented using |
129 | .BR hash (3). |
05fbeb03 |
130 | .PP |
131 | The |
1025598e |
132 | .BR atom (3) |
133 | module implements |
134 | .IR atoms , |
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 |
138 | .BR assoc (3) |
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 |
141 | keys. |
142 | .PP |
143 | The |
53e76188 |
144 | .BR darray (3) |
145 | module implements dynamically resizing arrays which support Perl-like |
146 | stack operations efficiently. |
05fbeb03 |
147 | .SS "Miscellaneous utilities" |
148 | The |
484eed5d |
149 | .BR crc32 (3) |
05fbeb03 |
150 | module calculates CRC values for strings. It's used by the symbol table |
151 | manager as a hash function. |
152 | .PP |
153 | The |
484eed5d |
154 | .BR lock (3) |
05fbeb03 |
155 | module does POSIX |
156 | .BR fcntl (2)-style |
157 | locking with a timeout. |
158 | .PP |
159 | The |
484eed5d |
160 | .BR env (3) |
3fecac47 |
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. |
164 | .PP |
165 | The |
484eed5d |
166 | .BR fdflags (3) |
3fecac47 |
167 | module manipulates file descriptor flags in a fairly painless way. |
168 | .PP |
169 | The |
32e1147e |
170 | .BR fwatch (3) |
171 | module allows you to easily find out whether a file has changed since |
172 | the last time you looked at it. |
173 | .PP |
174 | The |
484eed5d |
175 | .BR lbuf (3) |
05fbeb03 |
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 |
1025598e |
179 | sockets can't block while waiting for a line-end to arrive. Similarly, |
180 | the |
181 | .BR pkbuf (3) |
182 | module implements a `packet buffer', which waits for packets of given |
183 | lengths to arrive before dispatching them to a handler. |
05fbeb03 |
184 | .PP |
185 | The |
484eed5d |
186 | .BR tv (3) |
05fbeb03 |
187 | module provides some macros and functions for playing with |
484eed5d |
188 | .BR "struct timeval" . |
05fbeb03 |
189 | .PP |
190 | The |
484eed5d |
191 | .BR bits (3) |
05fbeb03 |
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. |
195 | values. |
196 | .PP |
197 | The |
484eed5d |
198 | .BR mdwopt (3) |
05fbeb03 |
199 | module implements a fairly serious options parser compatible with the |
200 | GNU options parser. |
201 | .PP |
202 | The |
484eed5d |
203 | .BR testrig (3) |
05fbeb03 |
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" |
208 | The |
484eed5d |
209 | .BR base64 (3) |
05fbeb03 |
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. |
213 | .PP |
214 | The |
484eed5d |
215 | .BR url (3) |
05fbeb03 |
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" |
220 | The |
484eed5d |
221 | .BR sel (3) |
05fbeb03 |
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. |
225 | .PP |
226 | The |
484eed5d |
227 | .BR conn (3) |
05fbeb03 |
228 | module implements nonblocking network connections in a way which fits in |
229 | with the |
230 | .B sel |
231 | system. It makes nonblocking connects pretty much trivial. |
232 | .PP |
233 | The |
484eed5d |
234 | .BR selbuf (3) |
05fbeb03 |
235 | module attaches to the |
236 | .B sel |
1025598e |
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, |
239 | .BR selpk (3) |
240 | sents events when packets of given sizes arrive from a file. |
484eed5d |
241 | .PP |
242 | The |
243 | .BR sig (3) |
244 | module introduces signal handling into the multiplexed I/O world. |
245 | Signals are queued until dispatched through the normal |
246 | .B sel |
247 | mechanism. |
83856dde |
248 | .PP |
249 | The |
250 | .BR ident (3) |
1025598e |
251 | module provides a nonblocking ident (RFC931) client. The |
83856dde |
252 | .BR bres (3) |
253 | module does background hostname and address resolution. |
05fbeb03 |
254 | .SH "SEE ALSO" |
255 | .BR alloc (3), |
1025598e |
256 | .BR assoc (3), |
257 | .BR atom (3), |
05fbeb03 |
258 | .BR base64 (3), |
259 | .BR bits (3), |
83856dde |
260 | .BR bres (3), |
05fbeb03 |
261 | .BR conn (3), |
262 | .BR crc32 (3), |
53e76188 |
263 | .BR darray (3), |
05fbeb03 |
264 | .BR dspool (3), |
265 | .BR dstr (3), |
3fecac47 |
266 | .BR env (3), |
05fbeb03 |
267 | .BR exc (3), |
3fecac47 |
268 | .BR fdflags (3), |
32e1147e |
269 | .BR fwatch (3), |
7eb5aec5 |
270 | .BR hash (3), |
83856dde |
271 | .BR ident (3), |
05fbeb03 |
272 | .BR lbuf (3), |
273 | .BR lock (3), |
274 | .BR mdwopt (3), |
1025598e |
275 | .BR pkbuf (3), |
05fbeb03 |
276 | .BR quis (3), |
277 | .BR report (3), |
278 | .BR sel (3), |
279 | .BR selbuf (3), |
1025598e |
280 | .BR selpk (3), |
484eed5d |
281 | .BR sig (3), |
05fbeb03 |
282 | .BR str (3), |
283 | .BR sub (3), |
284 | .BR sym (3), |
53e76188 |
285 | .BR trace (3), |
05fbeb03 |
286 | .BR tv (3), |
287 | .BR url (3). |
288 | .SH AUTHOR |
289 | Mark Wooding, <mdw@nsict.org> |