5 .\" (c) 1999--2001, 2003, 2005, 2007, 2009, 2024 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the mLib utilities library.
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.
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.
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,
27 .\"--------------------------------------------------------------------------
28 .so ../defs.man \" @@@PRE@@@
30 .\"--------------------------------------------------------------------------
31 .TH mLib 3mLib "7 July 1999" "Straylight/Edgeware" "mLib utilities library"
34 .\"--------------------------------------------------------------------------
36 mLib \- library of miscellaneous utilities
38 .\"--------------------------------------------------------------------------
43 library is a mixed bag of things which the author finds useful in large
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
49 At the most granular level,
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
62 This description is a bit abstract, and
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.
67 The rest of this section describes the various chunks and layers.
69 .SS "Exception handling"
70 Right at the bottom, there's a fairly primitive exception handling
71 system. It's provided by the
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.
76 .SS "Memory allocation"
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.
85 module provides simple veneers onto traditional memory allocation
92 doesn't actually depend on
94 being defined in the library) which raise exceptions when there's not
95 enough memory left. These work through the
97 layer, so that the caller can control memory allocation.
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.
109 module (not yet documented) is a simple memory allocation tracker. It
110 can be handy when trying to fix memory leaks.
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.
118 .SS "String handling"
121 module provides some trivial string-manipulation functions which tend to
122 be useful quite often.
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.
133 module provides simple functions for reading and writing binary data to
134 or from fixed-sized buffers.
138 module implements a `pool' of dynamic strings which saves lots of
139 allocation and deallocation when a piece of code has high string
142 .SS "Program identification and error reporting"
145 module remembers the name of the program and supplies it when asked.
146 It's used in error messages and similar things.
150 module emits standard Unixy error messages. It provides functions
154 which the author uses rather a lot.
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.
162 .SS "Other data types"
165 module provides the basics for an extending hashtable implementation.
166 Many different hashtable-based data structures can be constructed with
171 module implements a rather good general-purpose extending hash table.
172 Keys and values can be arbitrary data. It is implemented using
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
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
189 module implements dynamically resizing arrays which support Perl-like
190 stack operations efficiently.
192 .SS "Miscellaneous utilities"
195 module calculates CRC values for strings. It used to be used by the
196 symbol table manager as a hash function.
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.
208 locking with a timeout.
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.
218 module manipulates file descriptor flags in a fairly painless way.
222 module allows you to easily find out whether a file has changed since
223 the last time you looked at it.
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
230 sockets can't block while waiting for a line-end to arrive. Similarly,
233 module implements a `packet buffer', which waits for packets of given
234 lengths to arrive before dispatching them to a handler.
238 module provides some macros and functions for playing with
239 .BR "struct timeval" .
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.
250 module implements a fairly serious options parser compatible with the
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.
259 .SS "Encoding and decoding"
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
264 character-set transformations and other mail transport bogosity. The
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
269 module does hex encoding and decoding.
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.
277 .SS "Multiplexed I/O"
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.
286 module implements nonblocking network connections in a way which fits in
289 system. It makes nonblocking connects pretty much trivial.
293 module attaches to the
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,
298 sents events when packets of given sizes arrive from a file.
302 module introduces signal handling into the multiplexed I/O world.
303 Signals are queued until dispatched through the normal
309 module provides a nonblocking ident (RFC931) client. The
311 module does background hostname and address resolution.
313 .\"--------------------------------------------------------------------------
351 .\"--------------------------------------------------------------------------
354 Mark Wooding, <mdw@distorted.org.uk>
356 .\"----- That's all, folks --------------------------------------------------
~mdw / mLib / blob