Commit | Line | Data |
---|---|---|
05fbeb03 | 1 | .\" -*-nroff-*- |
c4ccbbf9 MW |
2 | .\" |
3 | .\" mLib overview | |
4 | .\" | |
5 | .\" (c) 1999--2001, 2003, 2005, 2007, 2009, 2024 Straylight/Edgeware | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
10 | .\" This file is part of the mLib utilities library. | |
11 | .\" | |
12 | .\" mLib is free software: you can redistribute it and/or modify it under | |
13 | .\" the terms of the GNU Library General Public License as published by | |
14 | .\" the Free Software Foundation; either version 2 of the License, or (at | |
15 | .\" your option) any later version. | |
16 | .\" | |
17 | .\" mLib is distributed in the hope that it will be useful, but WITHOUT | |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public | |
20 | .\" License for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU Library General Public | |
23 | .\" License along with mLib. If not, write to the Free Software | |
24 | .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, | |
25 | .\" USA. | |
26 | . | |
27 | .\"-------------------------------------------------------------------------- | |
28 | .so ../defs.man \" @@@PRE@@@ | |
29 | . | |
30 | .\"-------------------------------------------------------------------------- | |
31 | .TH mLib 3mLib "7 July 1999" "Straylight/Edgeware" "mLib utilities library" | |
32 | .\" @mLib | |
33 | . | |
34 | .\"-------------------------------------------------------------------------- | |
05fbeb03 | 35 | .SH NAME |
36 | mLib \- library of miscellaneous utilities | |
c4ccbbf9 MW |
37 | . |
38 | .\"-------------------------------------------------------------------------- | |
05fbeb03 | 39 | .SH DESCRIPTION |
c4ccbbf9 | 40 | . |
05fbeb03 | 41 | The |
42 | .B mLib | |
484eed5d | 43 | library is a mixed bag of things which the author finds useful in large |
05fbeb03 | 44 | numbers of programs. As a result, its structure is somewhat arbitrary, |
45 | and it's accreted extra bits over time rather than actually being | |
46 | designed as a whole. In the author's opinion this isn't too much of a | |
47 | hardship. | |
48 | .PP | |
49 | At the most granular level, | |
50 | .B mLib | |
51 | is split into `modules', each of which has its own header file and | |
52 | manual page. Sometimes there are identifiable `chunks' of several | |
53 | modules which fit together as a whole. Modules and chunks fit into | |
54 | `layers', each depending on the ones below it. The header file for | |
55 | module | |
56 | .I foo | |
57 | would be put in | |
58 | .BR <mLib/ \c | |
59 | .IR foo \c | |
484eed5d | 60 | .BR .h> . |
05fbeb03 | 61 | .PP |
62 | This description is a bit abstract, and | |
63 | .BR mLib , | |
64 | as a result of its history, doesn't fit it as well as I might like. | |
65 | Even so, it's not too bad a model really. | |
66 | .PP | |
67 | The rest of this section describes the various chunks and layers. | |
c4ccbbf9 | 68 | . |
05fbeb03 | 69 | .SS "Exception handling" |
70 | Right at the bottom, there's a fairly primitive exception handling | |
71 | system. It's provided by the | |
484eed5d | 72 | .BR exc (3) |
05fbeb03 | 73 | module, and stands alone. It's used mainly by the memory allocation |
74 | modules to raise exceptions when there's no more memory to be had. | |
c4ccbbf9 | 75 | . |
05fbeb03 | 76 | .SS "Memory allocation" |
77 | The | |
9787c8a8 | 78 | .BR arena (3) |
79 | module provides an abstraction of memory allocation. By writing | |
80 | appropriate arena implementations, a client program can control where | |
81 | and how memory is allocated for various structures. | |
82 | .PP | |
83 | The | |
484eed5d | 84 | .BR alloc (3) |
05fbeb03 | 85 | module provides simple veneers onto traditional memory allocation |
86 | functions like | |
87 | .BR malloc (3) | |
88 | and | |
89 | .BR strdup (3) | |
90 | (although | |
91 | .B mLib | |
92 | doesn't actually depend on | |
93 | .B strdup | |
94 | being defined in the library) which raise exceptions when there's not | |
9787c8a8 | 95 | enough memory left. These work through the |
96 | .B arena | |
97 | layer, so that the caller can control memory allocation. | |
05fbeb03 | 98 | .PP |
99 | The | |
484eed5d | 100 | .BR sub (3) |
05fbeb03 | 101 | module handles efficient allocation of small blocks. It allocates |
102 | memory in relatively big chunks and divides the chunks up into small | |
103 | blocks before returning them. It keeps lists of differently-sized | |
104 | blocks so allocation and freeing is fast. The downside is that your | |
105 | code must know how big a block is when it's being freed. | |
106 | .PP | |
107 | The | |
108 | .B track | |
109 | module (not yet documented) is a simple memory allocation tracker. It | |
110 | can be handy when trying to fix memory leaks. | |
9787c8a8 | 111 | .PP |
112 | The | |
113 | .BR pool (3) | |
114 | module maintains resource pools which can manage memory and other | |
115 | resources, all of the resources held in a pool being destroyed along | |
116 | with the pool itself. | |
c4ccbbf9 | 117 | . |
05fbeb03 | 118 | .SS "String handling" |
119 | The | |
484eed5d | 120 | .BR str (3) |
05fbeb03 | 121 | module provides some trivial string-manipulation functions which tend to |
122 | be useful quite often. | |
123 | .PP | |
124 | The | |
484eed5d | 125 | .BR dstr (3) |
05fbeb03 | 126 | module implements a dynamic string data type. It works quite quickly |
127 | and well, and is handy in security-sensitive programs, to prevent | |
128 | buffer-overflows. Dynamic strings are used occasionally through the | |
129 | rest of the library, mainly as output arguments. | |
130 | .PP | |
131 | The | |
9b5ac6ff | 132 | .BR buf (3) |
133 | module provides simple functions for reading and writing binary data to | |
134 | or from fixed-sized buffers. | |
135 | .PP | |
136 | The | |
484eed5d | 137 | .BR dspool (3) |
05fbeb03 | 138 | module implements a `pool' of dynamic strings which saves lots of |
139 | allocation and deallocation when a piece of code has high string | |
140 | turnover. | |
c4ccbbf9 | 141 | . |
05fbeb03 | 142 | .SS "Program identification and error reporting" |
143 | The | |
484eed5d | 144 | .BR quis (3) |
05fbeb03 | 145 | module remembers the name of the program and supplies it when asked. |
146 | It's used in error messages and similar things. | |
147 | .PP | |
148 | The | |
484eed5d | 149 | .BR report (3) |
05fbeb03 | 150 | module emits standard Unixy error messages. It provides functions |
151 | .B moan | |
152 | and | |
153 | .B die | |
154 | which the author uses rather a lot. | |
155 | .PP | |
156 | The | |
53e76188 | 157 | .BR trace (3) |
158 | module provides an interface for emitting tracing information with | |
159 | configurable verbosity levels. It needs improving to be able to cope | |
160 | with outputting to the system log. | |
c4ccbbf9 | 161 | . |
05fbeb03 | 162 | .SS "Other data types" |
163 | The | |
7eb5aec5 | 164 | .BR hash (3) |
165 | module provides the basics for an extending hashtable implementation. | |
166 | Many different hashtable-based data structures can be constructed with | |
167 | little effort. | |
168 | .PP | |
169 | The | |
484eed5d | 170 | .BR sym (3) |
7eb5aec5 | 171 | module implements a rather good general-purpose extending hash table. |
172 | Keys and values can be arbitrary data. It is implemented using | |
173 | .BR hash (3). | |
05fbeb03 | 174 | .PP |
175 | The | |
1025598e | 176 | .BR atom (3) |
177 | module implements | |
178 | .IR atoms , | |
179 | which are essentially strings with the property that two atoms have the | |
180 | same address if and only if they have the same text, so they can be used | |
181 | for rapid string comparisons. The | |
182 | .BR assoc (3) | |
183 | module implements a hash table which uses atoms as keys, thus saving | |
184 | time spent hashing and comparing hash keys, and the space used for the | |
185 | keys. | |
186 | .PP | |
187 | The | |
53e76188 | 188 | .BR darray (3) |
189 | module implements dynamically resizing arrays which support Perl-like | |
190 | stack operations efficiently. | |
c4ccbbf9 | 191 | . |
05fbeb03 | 192 | .SS "Miscellaneous utilities" |
193 | The | |
484eed5d | 194 | .BR crc32 (3) |
6f444bda | 195 | module calculates CRC values for strings. It used to be used by the |
196 | symbol table manager as a hash function. | |
197 | .PP | |
198 | The | |
199 | .BR unihash (3) | |
200 | module implements a simple but efficient universal hashing family. This | |
201 | is a keyed hash function which provides security against an adversary | |
202 | choosing input to a hash table deliberately to cause collisions. | |
05fbeb03 | 203 | .PP |
204 | The | |
484eed5d | 205 | .BR lock (3) |
05fbeb03 | 206 | module does POSIX |
207 | .BR fcntl (2)-style | |
208 | locking with a timeout. | |
209 | .PP | |
210 | The | |
484eed5d | 211 | .BR env (3) |
3fecac47 | 212 | module manipulates environment variables stored in a hashtable, and |
213 | converts between the hashtable and the standard array representation of | |
214 | a process environment. | |
215 | .PP | |
216 | The | |
484eed5d | 217 | .BR fdflags (3) |
3fecac47 | 218 | module manipulates file descriptor flags in a fairly painless way. |
219 | .PP | |
220 | The | |
32e1147e | 221 | .BR fwatch (3) |
222 | module allows you to easily find out whether a file has changed since | |
223 | the last time you looked at it. | |
224 | .PP | |
225 | The | |
484eed5d | 226 | .BR lbuf (3) |
05fbeb03 | 227 | module implements a `line buffer', which is an object that emits |
228 | completed lines of text from an incoming asynchronous data stream. It's | |
229 | remarkably handy in programs that want to read lines from pipes and | |
1025598e | 230 | sockets can't block while waiting for a line-end to arrive. Similarly, |
231 | the | |
232 | .BR pkbuf (3) | |
233 | module implements a `packet buffer', which waits for packets of given | |
234 | lengths to arrive before dispatching them to a handler. | |
05fbeb03 | 235 | .PP |
236 | The | |
484eed5d | 237 | .BR tv (3) |
05fbeb03 | 238 | module provides some macros and functions for playing with |
484eed5d | 239 | .BR "struct timeval" . |
05fbeb03 | 240 | .PP |
241 | The | |
484eed5d | 242 | .BR bits (3) |
05fbeb03 | 243 | module defines some types and macros for playing with words as chunks of |
244 | bits. There are portable rotate and shift macros (harder than you'd | |
245 | think), and macros to do loading and storing in known-endian formats. | |
246 | values. | |
247 | .PP | |
248 | The | |
484eed5d | 249 | .BR mdwopt (3) |
05fbeb03 | 250 | module implements a fairly serious options parser compatible with the |
251 | GNU options parser. | |
252 | .PP | |
253 | The | |
484eed5d | 254 | .BR testrig (3) |
05fbeb03 | 255 | module provides a generic structure for reading test vectors from files |
256 | and running them through functions. I mainly use it for testing | |
257 | cryptographic transformations of various kinds. | |
c4ccbbf9 | 258 | . |
05fbeb03 | 259 | .SS "Encoding and decoding" |
260 | The | |
484eed5d | 261 | .BR base64 (3) |
05fbeb03 | 262 | module does base64 encoding and decoding, as defined in RFC2045. Base64 |
263 | encodes arbitrary binary data in a reliable way which is resistant to | |
d4efbcd9 | 264 | character-set transformations and other mail transport bogosity. The |
9b64ede2 | 265 | .BR base32 (3) |
266 | module does base32 encoding and decoding, as defined in RFC2938. This | |
267 | is a mad format which is needed for sha1 URNs, for no good reason. The | |
268 | .BR hex (3) | |
269 | module does hex encoding and decoding. | |
05fbeb03 | 270 | .PP |
271 | The | |
484eed5d | 272 | .BR url (3) |
05fbeb03 | 273 | module does urlencoding and decoding, as defined in RFC1866. |
274 | Urlencoding encodes arbitrary (but mostly text-like) name/value pairs as | |
275 | a text string containing no whitespace. | |
c4ccbbf9 | 276 | . |
05fbeb03 | 277 | .SS "Multiplexed I/O" |
278 | The | |
484eed5d | 279 | .BR sel (3) |
05fbeb03 | 280 | module provides a basis for doing nonblocking I/O in Unix systems. It |
281 | provides types and functions for receiving events when files are ready | |
282 | for reading or writing, and when timers expire. | |
283 | .PP | |
284 | The | |
484eed5d | 285 | .BR conn (3) |
05fbeb03 | 286 | module implements nonblocking network connections in a way which fits in |
287 | with the | |
288 | .B sel | |
289 | system. It makes nonblocking connects pretty much trivial. | |
290 | .PP | |
291 | The | |
484eed5d | 292 | .BR selbuf (3) |
05fbeb03 | 293 | module attaches to the |
294 | .B sel | |
1025598e | 295 | system and sends an event when lines of text arrive from a file. It's |
296 | useful when reading text from a network connection. Similarly, | |
297 | .BR selpk (3) | |
298 | sents events when packets of given sizes arrive from a file. | |
484eed5d | 299 | .PP |
300 | The | |
301 | .BR sig (3) | |
302 | module introduces signal handling into the multiplexed I/O world. | |
303 | Signals are queued until dispatched through the normal | |
304 | .B sel | |
305 | mechanism. | |
83856dde | 306 | .PP |
307 | The | |
308 | .BR ident (3) | |
1025598e | 309 | module provides a nonblocking ident (RFC931) client. The |
83856dde | 310 | .BR bres (3) |
311 | module does background hostname and address resolution. | |
c4ccbbf9 MW |
312 | . |
313 | .\"-------------------------------------------------------------------------- | |
05fbeb03 | 314 | .SH "SEE ALSO" |
c4ccbbf9 | 315 | . |
05fbeb03 | 316 | .BR alloc (3), |
1025598e | 317 | .BR assoc (3), |
318 | .BR atom (3), | |
05fbeb03 | 319 | .BR base64 (3), |
320 | .BR bits (3), | |
9b5ac6ff | 321 | .BR buf (3), |
83856dde | 322 | .BR bres (3), |
05fbeb03 | 323 | .BR conn (3), |
324 | .BR crc32 (3), | |
53e76188 | 325 | .BR darray (3), |
05fbeb03 | 326 | .BR dspool (3), |
327 | .BR dstr (3), | |
3fecac47 | 328 | .BR env (3), |
05fbeb03 | 329 | .BR exc (3), |
3fecac47 | 330 | .BR fdflags (3), |
32e1147e | 331 | .BR fwatch (3), |
7eb5aec5 | 332 | .BR hash (3), |
83856dde | 333 | .BR ident (3), |
05fbeb03 | 334 | .BR lbuf (3), |
335 | .BR lock (3), | |
336 | .BR mdwopt (3), | |
1025598e | 337 | .BR pkbuf (3), |
05fbeb03 | 338 | .BR quis (3), |
339 | .BR report (3), | |
340 | .BR sel (3), | |
341 | .BR selbuf (3), | |
1025598e | 342 | .BR selpk (3), |
484eed5d | 343 | .BR sig (3), |
05fbeb03 | 344 | .BR str (3), |
345 | .BR sub (3), | |
346 | .BR sym (3), | |
53e76188 | 347 | .BR trace (3), |
05fbeb03 | 348 | .BR tv (3), |
349 | .BR url (3). | |
c4ccbbf9 MW |
350 | . |
351 | .\"-------------------------------------------------------------------------- | |
05fbeb03 | 352 | .SH AUTHOR |
c4ccbbf9 | 353 | . |
9b5ac6ff | 354 | Mark Wooding, <mdw@distorted.org.uk> |
c4ccbbf9 MW |
355 | . |
356 | .\"----- That's all, folks -------------------------------------------------- |