05fbeb03 |
1 | .\" -*-nroff-*- |
2 | .TH mLib 3 "7 July 1999" mLib |
3 | .SH NAME |
4 | mLib \- library of miscellaneous utilities |
5 | .\" @mLib |
6 | .SH DESCRIPTION |
7 | The |
8 | .B mLib |
9 | library is a mixed back 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 |
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 |
26 | .BR > . |
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 |
37 | .B exc |
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 |
42 | .B alloc |
43 | module provides simple veneers onto traditional memory allocation |
44 | functions like |
45 | .BR malloc (3) |
46 | and |
47 | .BR strdup (3) |
48 | (although |
49 | .B mLib |
50 | doesn't actually depend on |
51 | .B strdup |
52 | being defined in the library) which raise exceptions when there's not |
53 | enough memory left. |
54 | .PP |
55 | The |
56 | .B sub |
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. |
62 | .PP |
63 | The |
64 | .B track |
65 | module (not yet documented) is a simple memory allocation tracker. It |
66 | can be handy when trying to fix memory leaks. |
67 | .SS "String handling" |
68 | The |
69 | .B str |
70 | module provides some trivial string-manipulation functions which tend to |
71 | be useful quite often. |
72 | .PP |
73 | The |
74 | .B dstr |
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. |
79 | .PP |
80 | The |
81 | .B dspool |
82 | module implements a `pool' of dynamic strings which saves lots of |
83 | allocation and deallocation when a piece of code has high string |
84 | turnover. |
85 | .SS "Program identification and error reporting" |
86 | The |
87 | .B quis |
88 | module remembers the name of the program and supplies it when asked. |
89 | It's used in error messages and similar things. |
90 | .PP |
91 | The |
92 | .B report |
93 | module emits standard Unixy error messages. It provides functions |
94 | .B moan |
95 | and |
96 | .B die |
97 | which the author uses rather a lot. |
98 | .PP |
99 | The |
100 | .B trace |
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 |
104 | to the system log. |
105 | .SS "Other data types" |
106 | The |
107 | .B sym |
108 | module implements a rather good extending hash table. Keys and values can |
109 | be arbitrary data. |
110 | .PP |
111 | The |
112 | .B dynarray |
113 | module (not yet documented) implements unbounded sparse arrays. It |
114 | needs rewriting. |
115 | .SS "Miscellaneous utilities" |
116 | The |
117 | .B crc32 |
118 | module calculates CRC values for strings. It's used by the symbol table |
119 | manager as a hash function. |
120 | .PP |
121 | The |
122 | .B lock |
123 | module does POSIX |
124 | .BR fcntl (2)-style |
125 | locking with a timeout. |
126 | .PP |
127 | The |
128 | .B lbuf |
129 | module implements a `line buffer', which is an object that emits |
130 | completed lines of text from an incoming asynchronous data stream. It's |
131 | remarkably handy in programs that want to read lines from pipes and |
132 | sockets can't block while waiting for a line-end to arrive. |
133 | .PP |
134 | The |
135 | .B tv |
136 | module provides some macros and functions for playing with |
137 | .B "struct timeval" |
138 | .PP |
139 | The |
140 | .B bits |
141 | module defines some types and macros for playing with words as chunks of |
142 | bits. There are portable rotate and shift macros (harder than you'd |
143 | think), and macros to do loading and storing in known-endian formats. |
144 | values. |
145 | .PP |
146 | The |
147 | .B mdwopt |
148 | module implements a fairly serious options parser compatible with the |
149 | GNU options parser. |
150 | .PP |
151 | The |
152 | .B testrig |
153 | module provides a generic structure for reading test vectors from files |
154 | and running them through functions. I mainly use it for testing |
155 | cryptographic transformations of various kinds. |
156 | .SS "Encoding and decoding" |
157 | The |
158 | .B base64 |
159 | module does base64 encoding and decoding, as defined in RFC2045. Base64 |
160 | encodes arbitrary binary data in a reliable way which is resistant to |
161 | character-set transformations and other mail transport bogosity. |
162 | .PP |
163 | The |
164 | .B url |
165 | module does urlencoding and decoding, as defined in RFC1866. |
166 | Urlencoding encodes arbitrary (but mostly text-like) name/value pairs as |
167 | a text string containing no whitespace. |
168 | .SS "Multiplexed I/O" |
169 | The |
170 | .B sel |
171 | module provides a basis for doing nonblocking I/O in Unix systems. It |
172 | provides types and functions for receiving events when files are ready |
173 | for reading or writing, and when timers expire. |
174 | .PP |
175 | The |
176 | .B conn |
177 | module implements nonblocking network connections in a way which fits in |
178 | with the |
179 | .B sel |
180 | system. It makes nonblocking connects pretty much trivial. |
181 | .PP |
182 | The |
183 | .B selbuf |
184 | module attaches to the |
185 | .B sel |
186 | system and sends an event when lines of text arrive on a file. It's |
187 | useful when reading text from a network connection. |
188 | .SH "SEE ALSO" |
189 | .BR alloc (3), |
190 | .BR base64 (3), |
191 | .BR bits (3), |
192 | .BR conn (3), |
193 | .BR crc32 (3), |
194 | .BR dspool (3), |
195 | .BR dstr (3), |
196 | .BR exc (3), |
197 | .BR lbuf (3), |
198 | .BR lock (3), |
199 | .BR mdwopt (3), |
200 | .BR quis (3), |
201 | .BR report (3), |
202 | .BR sel (3), |
203 | .BR selbuf (3), |
204 | .BR str (3), |
205 | .BR sub (3), |
206 | .BR sym (3), |
207 | .BR tv (3), |
208 | .BR url (3). |
209 | .SH AUTHOR |
210 | Mark Wooding, <mdw@nsict.org> |