chiark / gitweb /
Update manual style.
[mLib] / man / mLib.3
05fbeb03 1.\" -*-nroff-*-
fbf20b5b 2.TH mLib 3 "7 July 1999" "Straylight/Edgeware" "mLib utilities library"
05fbeb03 3.SH NAME
4mLib \- library of miscellaneous utilities
5.\" @mLib
8.B mLib
484eed5d 9library is a mixed bag of things which the author finds useful in large
05fbeb03 10numbers of programs. As a result, its structure is somewhat arbitrary,
11and it's accreted extra bits over time rather than actually being
12designed as a whole. In the author's opinion this isn't too much of a
15At the most granular level,
16.B mLib
17is split into `modules', each of which has its own header file and
18manual page. Sometimes there are identifiable `chunks' of several
19modules which fit together as a whole. Modules and chunks fit into
20`layers', each depending on the ones below it. The header file for
22.I foo
23would be put in
24.BR <mLib/ \c
25.IR foo \c
484eed5d 26.BR .h> .
05fbeb03 27.PP
28This description is a bit abstract, and
29.BR mLib ,
30as a result of its history, doesn't fit it as well as I might like.
31Even so, it's not too bad a model really.
33The rest of this section describes the various chunks and layers.
34.SS "Exception handling"
35Right at the bottom, there's a fairly primitive exception handling
36system. It's provided by the
484eed5d 37.BR exc (3)
05fbeb03 38module, and stands alone. It's used mainly by the memory allocation
39modules to raise exceptions when there's no more memory to be had.
40.SS "Memory allocation"
9787c8a8 42.BR arena (3)
43module provides an abstraction of memory allocation. By writing
44appropriate arena implementations, a client program can control where
45and how memory is allocated for various structures.
484eed5d 48.BR alloc (3)
05fbeb03 49module provides simple veneers onto traditional memory allocation
50functions like
51.BR malloc (3)
53.BR strdup (3)
55.B mLib
56doesn't actually depend on
57.B strdup
58being defined in the library) which raise exceptions when there's not
9787c8a8 59enough memory left. These work through the
60.B arena
61layer, so that the caller can control memory allocation.
05fbeb03 62.PP
484eed5d 64.BR sub (3)
05fbeb03 65module handles efficient allocation of small blocks. It allocates
66memory in relatively big chunks and divides the chunks up into small
67blocks before returning them. It keeps lists of differently-sized
68blocks so allocation and freeing is fast. The downside is that your
69code must know how big a block is when it's being freed.
72.B track
73module (not yet documented) is a simple memory allocation tracker. It
74can be handy when trying to fix memory leaks.
9787c8a8 75.PP
77.BR pool (3)
78module maintains resource pools which can manage memory and other
79resources, all of the resources held in a pool being destroyed along
80with the pool itself.
05fbeb03 81.SS "String handling"
484eed5d 83.BR str (3)
05fbeb03 84module provides some trivial string-manipulation functions which tend to
85be useful quite often.
484eed5d 88.BR dstr (3)
05fbeb03 89module implements a dynamic string data type. It works quite quickly
90and well, and is handy in security-sensitive programs, to prevent
91buffer-overflows. Dynamic strings are used occasionally through the
92rest of the library, mainly as output arguments.
484eed5d 95.BR dspool (3)
05fbeb03 96module implements a `pool' of dynamic strings which saves lots of
97allocation and deallocation when a piece of code has high string
99.SS "Program identification and error reporting"
484eed5d 101.BR quis (3)
05fbeb03 102module remembers the name of the program and supplies it when asked.
103It's used in error messages and similar things.
484eed5d 106.BR report (3)
05fbeb03 107module emits standard Unixy error messages. It provides functions
108.B moan
110.B die
111which the author uses rather a lot.
53e76188 114.BR trace (3)
115module provides an interface for emitting tracing information with
116configurable verbosity levels. It needs improving to be able to cope
117with outputting to the system log.
05fbeb03 118.SS "Other data types"
7eb5aec5 120.BR hash (3)
121module provides the basics for an extending hashtable implementation.
122Many different hashtable-based data structures can be constructed with
123little effort.
484eed5d 126.BR sym (3)
7eb5aec5 127module implements a rather good general-purpose extending hash table.
128Keys and values can be arbitrary data. It is implemented using
129.BR hash (3).
05fbeb03 130.PP
1025598e 132.BR atom (3)
133module implements
134.IR atoms ,
135which are essentially strings with the property that two atoms have the
136same address if and only if they have the same text, so they can be used
137for rapid string comparisons. The
138.BR assoc (3)
139module implements a hash table which uses atoms as keys, thus saving
140time spent hashing and comparing hash keys, and the space used for the
53e76188 144.BR darray (3)
145module implements dynamically resizing arrays which support Perl-like
146stack operations efficiently.
05fbeb03 147.SS "Miscellaneous utilities"
484eed5d 149.BR crc32 (3)
05fbeb03 150module calculates CRC values for strings. It's used by the symbol table
151manager as a hash function.
484eed5d 154.BR lock (3)
05fbeb03 155module does POSIX
156.BR fcntl (2)-style
157locking with a timeout.
484eed5d 160.BR env (3)
3fecac47 161module manipulates environment variables stored in a hashtable, and
162converts between the hashtable and the standard array representation of
163a process environment.
484eed5d 166.BR fdflags (3)
3fecac47 167module manipulates file descriptor flags in a fairly painless way.
32e1147e 170.BR fwatch (3)
171module allows you to easily find out whether a file has changed since
172the last time you looked at it.
484eed5d 175.BR lbuf (3)
05fbeb03 176module implements a `line buffer', which is an object that emits
177completed lines of text from an incoming asynchronous data stream. It's
178remarkably handy in programs that want to read lines from pipes and
1025598e 179sockets can't block while waiting for a line-end to arrive. Similarly,
181.BR pkbuf (3)
182module implements a `packet buffer', which waits for packets of given
183lengths to arrive before dispatching them to a handler.
05fbeb03 184.PP
484eed5d 186.BR tv (3)
05fbeb03 187module provides some macros and functions for playing with
484eed5d 188.BR "struct timeval" .
05fbeb03 189.PP
484eed5d 191.BR bits (3)
05fbeb03 192module defines some types and macros for playing with words as chunks of
193bits. There are portable rotate and shift macros (harder than you'd
194think), and macros to do loading and storing in known-endian formats.
484eed5d 198.BR mdwopt (3)
05fbeb03 199module implements a fairly serious options parser compatible with the
200GNU options parser.
484eed5d 203.BR testrig (3)
05fbeb03 204module provides a generic structure for reading test vectors from files
205and running them through functions. I mainly use it for testing
206cryptographic transformations of various kinds.
207.SS "Encoding and decoding"
484eed5d 209.BR base64 (3)
05fbeb03 210module does base64 encoding and decoding, as defined in RFC2045. Base64
211encodes arbitrary binary data in a reliable way which is resistant to
212character-set transformations and other mail transport bogosity.
484eed5d 215.BR url (3)
05fbeb03 216module does urlencoding and decoding, as defined in RFC1866.
217Urlencoding encodes arbitrary (but mostly text-like) name/value pairs as
218a text string containing no whitespace.
219.SS "Multiplexed I/O"
484eed5d 221.BR sel (3)
05fbeb03 222module provides a basis for doing nonblocking I/O in Unix systems. It
223provides types and functions for receiving events when files are ready
224for reading or writing, and when timers expire.
484eed5d 227.BR conn (3)
05fbeb03 228module implements nonblocking network connections in a way which fits in
229with the
230.B sel
231system. It makes nonblocking connects pretty much trivial.
484eed5d 234.BR selbuf (3)
05fbeb03 235module attaches to the
236.B sel
1025598e 237system and sends an event when lines of text arrive from a file. It's
238useful when reading text from a network connection. Similarly,
239.BR selpk (3)
240sents events when packets of given sizes arrive from a file.
484eed5d 241.PP
243.BR sig (3)
244module introduces signal handling into the multiplexed I/O world.
245Signals are queued until dispatched through the normal
246.B sel
83856dde 248.PP
250.BR ident (3)
1025598e 251module provides a nonblocking ident (RFC931) client. The
83856dde 252.BR bres (3)
253module 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).
289Mark Wooding, <>