chiark / gitweb /
Describe installation of manpages.
[mLib] / README
32a3ab99 1mLib
6 mLib is a collection of bits of code I've found handy in various
7 programs. With a few very minor exceptions, the routines are
8 highly portable, and mostly strictly conformant.
10 My programming style is probably what you'd describe as
11 `unconventional'. I'm skeptical about object-orientation, and
12 not a huge fan of over-hiding information of any kind. The
13 structure and interface of the library reflects these views.
93f77e5b 15 There is now a (hopefully fairly good) set of manual pages for
16 mLib. The manual isn't installed by default since it takes a
17 while to install and it's not a very good idea when it's part
18 of a larger package. To install the manual pages, say
20 make install-man
22 (after everything else is built, obviously).
32a3ab99 23
25Quick tour
27 mLib doesn't have much of a `structure' as such. It's more a
28 collection of useful things than a coherent whole. Even so,
29 it's possible to detect a vague layering of the library's
30 components.
32 The underpinnings of the system are the exception structure, and
33 the memory allocation routines.
35 * `exc.h' declares some macros which do a reasonable (though
36 not perfect) job of providing exception handling facilities
37 for C.
39 * `alloc.h' declares some thin veneers over `malloc' and
40 `free' which raise exceptions for out-of-memory conditions,
41 so you don't have to bother trapping these in main code.
43 Above this are the memory tracking system, the suballocator, and
44 a couple of useful data structures.
46 * `track.h' declares the symbols required for a (very) simple
47 memory allocation tracker. I wrote it because I had a
48 memory leak in a program. It tags allocated memory blocks
49 with information about who allocated them, and keeps track
50 of the memory allocated so far. Most of the time, you don't
51 bother compiling this in, and you don't need to care about
52 it at all.
54 * `sub.h' provides an allocation mechanism for small,
55 known-size blocks. It fetches big chunks from an underlying
56 allocator and divvies them up into small ones. This reduces
57 the overhead of calling the underlying allocator, and
58 (because the small blocks are linked together in lists by
59 their size) means that allocation and freeing are very
60 quick. It also reduces the amount of memory used by a small
61 amount.
63 * `sym.h' provides a symbol table manager. It uses an
64 extensible hashing scheme (with 32-bit CRC as the hash
65 function), and permits arbitrary data blocks in both the
66 keys and values. It seems fairly quick.
68 * `dstr.h' provides a dynamically sized string type. In the
69 rather paltry tests I've run, it seemed faster than
70 libstdc++'s string type, but I shouldn't read too much into
71 that if I were you. The representation is exposed, in case
72 you want to start fiddling with it. Just make sure that the
73 string looks sane before you start expecting any of the
74 functions or macros to work.
76 * `dynarray.h' is a big nasty macro which defines functions
77 capable of dealing with dynamically-sized arrays of
78 arbitrary types. (You build a new set of functions for each
79 type. Think of it as a hacky C++ template-a-like.) The
80 arrays are sparse, but not ever-so efficient in terms of
81 look-up time.
83 At the same conceptual level, there's some code for handling
84 multiplexed I/O. Although the core is named `sel', and it uses
85 `select' internally, it could fairly easily be changed to use
86 `poll' instead.
88 * `tv.h' declares some useful arithmetic operations on the
89 `struct timeval' type used by the `select' system call.
91 * `sel.h' declares a collection of types and routines for
92 handling `select' calls in a nice way. There's nothing
93 particularly exciting in itself, but it's a good base on
94 which to build other things.
96 * `lbuf.h' accepts arbitrary chunks of data and then passes
97 completed text lines on to a function. This is handy when
98 you're trying to read text from a socket, but don't want to
99 block while the end of the line is on its way. (In
100 particular, that'd leave you vulnerable to a trivial denial-
101 of-service attack.)
103 * `selbuf.h' implements an `lbuf' tied to a read selector.
104 Whenever completed lines are read from a particular source,
105 they're passed to a handler function.
107 * `conn.h' handles non-blocking `connect'. It starts a
108 connect, and adds itself to the select system. When the
109 connect completes, you get given the file descriptor.
111 Then there's a bunch of other stuff.
113 * `crc32.h' declares the 32-bit CRC used by `sym'.
115 * `quis.h' works out the program name from the value of
116 `argv[0]' and puts it in a variable for everything else to
117 find.
119 * `report.h' reports fatal and nonfatal errors in the standard
120 Unixy way.
122 * `trace.h' provides a simple tracing facility, which can be
123 turned on and off both at compile- and run-time.
125 * `testrig.h' is a generic test rig skeleton. It reads test
126 vector files with a slightly configurable syntax, passes the
127 arguments to a caller-defined test function, and reports the
128 results. It's particularly handy with cryptographic
129 algorithms, I find.
132Future directions
134 I'm going to write some manual pages. Promise.
137 Mark Wooding