chiark / gitweb /
(conn_connect): Change sizes to be @size_t@.
[mLib] / README
32a3ab99 1mLib
6 mLib is a collection of bits of code I've found handy in various
323ffb6c 7 programs. Once upon a time, almost all of the code was nearly-
8 strictly conforming C. Since then, a big pile of Unix-specific
9 code's been added, with a particularly strong networking
10 emphasis. The Unix-specific code is targetted at sensible
11 POSIX-conforming systems, and should port easily.
32a3ab99 12
13 My programming style is probably what you'd describe as
14 `unconventional'. I'm skeptical about object-orientation, and
15 not a huge fan of over-hiding information of any kind. The
323ffb6c 16 structure and interface of the library reflects these views. On
17 the other hand, I like documentation quite a lot.
32a3ab99 21
93f77e5b 22 There is now a (hopefully fairly good) set of manual pages for
23 mLib. The manual isn't installed by default since it takes a
24 while to install and it's not a very good idea when it's part
25 of a larger package. To install the manual pages, say
27 make install-man
29 (after everything else is built, obviously).
32a3ab99 30
323ffb6c 31 There's also documentation in the header files. The header file
32 comments were, in general, written at the same time as the code.
33 This has the disadvantage that they focus at a fairly low level,
34 and use terminology relating to the implementation rather than
35 the interface.
37 The header file comments can be handy for quick browsing.
38 However, the manual pages are considered the authoritative
39 source of information about the programming interface. If you
40 have to look at the source code, it usually means that my
41 documentation or interface design is wrong.
32a3ab99 43
44Quick tour
46 mLib doesn't have much of a `structure' as such. It's more a
47 collection of useful things than a coherent whole. Even so,
48 it's possible to detect a vague layering of the library's
49 components.
51 The underpinnings of the system are the exception structure, and
52 the memory allocation routines.
54 * `exc.h' declares some macros which do a reasonable (though
55 not perfect) job of providing exception handling facilities
56 for C.
58 * `alloc.h' declares some thin veneers over `malloc' and
e351a12d 59 friends which raise exceptions for out-of-memory conditions,
32a3ab99 60 so you don't have to bother trapping these in main code.
62 Above this are the memory tracking system, the suballocator, and
63 a couple of useful data structures.
65 * `track.h' declares the symbols required for a (very) simple
66 memory allocation tracker. I wrote it because I had a
67 memory leak in a program. It tags allocated memory blocks
68 with information about who allocated them, and keeps track
69 of the memory allocated so far. Most of the time, you don't
70 bother compiling this in, and you don't need to care about
e351a12d 71 it at all. [This may be withdrawn in a later release. Too
72 much code in mLib doesn't support it properly, and it's not
73 being maintained or documented very well.]
32a3ab99 74
75 * `sub.h' provides an allocation mechanism for small,
76 known-size blocks. It fetches big chunks from an underlying
77 allocator and divvies them up into small ones. This reduces
78 the overhead of calling the underlying allocator, and
79 (because the small blocks are linked together in lists by
80 their size) means that allocation and freeing are very
81 quick. It also reduces the amount of memory used by a small
82 amount.
84 * `sym.h' provides a symbol table manager. It uses an
85 extensible hashing scheme (with 32-bit CRC as the hash
86 function), and permits arbitrary data blocks in both the
87 keys and values. It seems fairly quick.
323ffb6c 89 * `hash.h' provides the underpinnings of the `sym' hashtable.
90 It's a completely generic hashtable skeleton. It provides
91 the basics like rehashing when the table is full and so on.
92 It needs a fair bit of work to turn into a usable data
93 structure, though, which is what `sym' is for.
32a3ab99 95 * `dstr.h' provides a dynamically sized string type. In the
96 rather paltry tests I've run, it seemed faster than
97 libstdc++'s string type, but I shouldn't read too much into
98 that if I were you. The representation is exposed, in case
99 you want to start fiddling with it. Just make sure that the
100 string looks sane before you start expecting any of the
101 functions or macros to work.
323ffb6c 103 * `darray.h' implements dynamically growing arrays which can be
104 extended at both ends, a bit like Perl's. It replaces the
105 old `dynarray.h' which wasn't very good. However, `darray's
106 arrays are not sparse. Maybe a good sparse array module
107 will be added later.
32a3ab99 108
109 At the same conceptual level, there's some code for handling
110 multiplexed I/O. Although the core is named `sel', and it uses
111 `select' internally, it could fairly easily be changed to use
112 `poll' instead.
114 * `tv.h' declares some useful arithmetic operations on the
115 `struct timeval' type used by the `select' system call.
117 * `sel.h' declares a collection of types and routines for
118 handling `select' calls in a nice way. There's nothing
119 particularly exciting in itself, but it's a good base on
120 which to build other things.
122 * `lbuf.h' accepts arbitrary chunks of data and then passes
123 completed text lines on to a function. This is handy when
124 you're trying to read text from a socket, but don't want to
125 block while the end of the line is on its way. (In
126 particular, that'd leave you vulnerable to a trivial denial-
127 of-service attack.)
129 * `selbuf.h' implements an `lbuf' tied to a read selector.
130 Whenever completed lines are read from a particular source,
131 they're passed to a handler function.
133 * `conn.h' handles non-blocking `connect'. It starts a
134 connect, and adds itself to the select system. When the
135 connect completes, you get given the file descriptor.
323ffb6c 137 * `ident.h' is an RFC931 (identd) client.
139 * `bres.h' is a background name resolver. It keeps a pool of
140 resolver processes to answer queries.
142 * `sig.h' traps signals and dispatches them through the
143 event-driven `sel' system.
32a3ab99 145 Then there's a bunch of other stuff.
323ffb6c 147 * `base64.h' does Base64 encoding and decoding.
149 * `bits.h' provides some portable bit manipulation macros.
32a3ab99 151 * `crc32.h' declares the 32-bit CRC used by `sym'.
323ffb6c 153 * `env.h' provides some routines for handling environment
154 variables in a hashtable.
156 * `fdflags.h' encapsulates some traditional little dances with
157 fcntl when playing with nonblocking files.
159 * `lock.h' does fcntl-style locking with a timeout.
32a3ab99 161 * `quis.h' works out the program name from the value of
162 `argv[0]' and puts it in a variable for everything else to
163 find.
165 * `report.h' reports fatal and nonfatal errors in the standard
166 Unixy way.
323ffb6c 168 * `str.h' provides some occasionally useful string-
169 manipulation toys.
32a3ab99 171 * `trace.h' provides a simple tracing facility, which can be
172 turned on and off both at compile- and run-time.
174 * `testrig.h' is a generic test rig skeleton. It reads test
175 vector files with a slightly configurable syntax, passes the
176 arguments to a caller-defined test function, and reports the
177 results. It's particularly handy with cryptographic
178 algorithms, I find.
323ffb6c 180 * `url.h' does url-encoding, which armours mostly-textual
181 name/value pairs so they contain no whitespace characters.
32a3ab99 182
184 Mark Wooding
323ffb6c 186\f
187Local variables:
188mode: text