cleanup: All the whitespace fixes, all at once.

[mLib] / man / mLib.3

diff --git a/man/mLib.3 b/man/mLib.3
index 43a95a26fbb1b248ebc983b03c389661bc85b86f..174a03e453b043c48dd6141e2cc217b53602b07c 100644 (file)
--- a/man/mLib.3
+++ b/man/mLib.3
@@ -1,12 +1,12 @@
 .\" -*-nroff-*-
 .\" -*-nroff-*-

-.TH mLib 3 "7 July 1999" mLib
+.TH mLib 3 "7 July 1999" "Straylight/Edgeware" "mLib utilities library"

 .SH NAME
 mLib \- library of miscellaneous utilities
 .\" @mLib
 .SH DESCRIPTION
 The
 .B mLib
 .SH NAME
 mLib \- library of miscellaneous utilities
 .\" @mLib
 .SH DESCRIPTION
 The
 .B mLib

-library is a mixed back of things which the author finds useful in large
+library is a mixed bag of things which the author finds useful in large

 numbers of programs.  As a result, its structure is somewhat arbitrary,
 and it's accreted extra bits over time rather than actually being
 designed as a whole.  In the author's opinion this isn't too much of a
 numbers of programs.  As a result, its structure is somewhat arbitrary,
 and it's accreted extra bits over time rather than actually being
 designed as a whole.  In the author's opinion this isn't too much of a


@@ -23,7 +23,7 @@ module
 would be put in
 .BR <mLib/ \c
 .IR foo \c
 would be put in
 .BR <mLib/ \c
 .IR foo \c

-.BR > .
+.BR .h> .

 .PP
 This description is a bit abstract, and
 .BR mLib ,
 .PP
 This description is a bit abstract, and
 .BR mLib ,


@@ -34,12 +34,18 @@ The rest of this section describes the various chunks and layers.
 .SS "Exception handling"
 Right at the bottom, there's a fairly primitive exception handling
 system.  It's provided by the
 .SS "Exception handling"
 Right at the bottom, there's a fairly primitive exception handling
 system.  It's provided by the

-.B exc
+.BR exc (3)

 module, and stands alone.  It's used mainly by the memory allocation
 modules to raise exceptions when there's no more memory to be had.
 .SS "Memory allocation"
 The
 module, and stands alone.  It's used mainly by the memory allocation
 modules to raise exceptions when there's no more memory to be had.
 .SS "Memory allocation"
 The

-.B alloc
+.BR arena (3)
+module provides an abstraction of memory allocation.  By writing
+appropriate arena implementations, a client program can control where
+and how memory is allocated for various structures.
+.PP
+The
+.BR alloc (3)

 module provides simple veneers onto traditional memory allocation
 functions like
 .BR malloc (3)
 module provides simple veneers onto traditional memory allocation
 functions like
 .BR malloc (3)


@@ -50,10 +56,12 @@ and
 doesn't actually depend on
 .B strdup
 being defined in the library) which raise exceptions when there's not
 doesn't actually depend on
 .B strdup
 being defined in the library) which raise exceptions when there's not

-enough memory left.
+enough memory left.  These work through the
+.B arena
+layer, so that the caller can control memory allocation.

 .PP
 The
 .PP
 The

-.B sub
+.BR sub (3)

 module handles efficient allocation of small blocks.  It allocates
 memory in relatively big chunks and divides the chunks up into small
 blocks before returning them.  It keeps lists of differently-sized
 module handles efficient allocation of small blocks.  It allocates
 memory in relatively big chunks and divides the chunks up into small
 blocks before returning them.  It keeps lists of differently-sized


@@ -64,32 +72,43 @@ The
 .B track
 module (not yet documented) is a simple memory allocation tracker.  It
 can be handy when trying to fix memory leaks.
 .B track
 module (not yet documented) is a simple memory allocation tracker.  It
 can be handy when trying to fix memory leaks.

+.PP
+The
+.BR pool (3)
+module maintains resource pools which can manage memory and other
+resources, all of the resources held in a pool being destroyed along
+with the pool itself.

 .SS "String handling"
 The
 .SS "String handling"
 The

-.B str
+.BR str (3)

 module provides some trivial string-manipulation functions which tend to
 be useful quite often.
 .PP
 The
 module provides some trivial string-manipulation functions which tend to
 be useful quite often.
 .PP
 The

-.B dstr
+.BR dstr (3)

 module implements a dynamic string data type.  It works quite quickly
 and well, and is handy in security-sensitive programs, to prevent
 buffer-overflows.  Dynamic strings are used occasionally through the
 rest of the library, mainly as output arguments.
 .PP
 The
 module implements a dynamic string data type.  It works quite quickly
 and well, and is handy in security-sensitive programs, to prevent
 buffer-overflows.  Dynamic strings are used occasionally through the
 rest of the library, mainly as output arguments.
 .PP
 The

-.B dspool
+.BR buf (3)
+module provides simple functions for reading and writing binary data to
+or from fixed-sized buffers.
+.PP
+The
+.BR dspool (3)

 module implements a `pool' of dynamic strings which saves lots of
 allocation and deallocation when a piece of code has high string
 turnover.
 .SS "Program identification and error reporting"
 The
 module implements a `pool' of dynamic strings which saves lots of
 allocation and deallocation when a piece of code has high string
 turnover.
 .SS "Program identification and error reporting"
 The

-.B quis
+.BR quis (3)

 module remembers the name of the program and supplies it when asked.
 It's used in error messages and similar things.
 .PP
 The
 module remembers the name of the program and supplies it when asked.
 It's used in error messages and similar things.
 .PP
 The

-.B report
+.BR report (3)

 module emits standard Unixy error messages.  It provides functions
 .B moan
 and
 module emits standard Unixy error messages.  It provides functions
 .B moan
 and


@@ -97,126 +116,191 @@ and
 which the author uses rather a lot.
 .PP
 The
 which the author uses rather a lot.
 .PP
 The

-.B trace
-module (not yet documented)
-provides an interface for emitting tracing information with configurable
-verbosity levels.  It needs improving to be able to cope with outputting
-to the system log.
+.BR trace (3)
+module provides an interface for emitting tracing information with
+configurable verbosity levels.  It needs improving to be able to cope
+with outputting to the system log.

 .SS "Other data types"
 The
 .SS "Other data types"
 The

-.B sym
-module implements a rather good extending hash table.  Keys and values can
-be arbitrary data.
+.BR hash (3)
+module provides the basics for an extending hashtable implementation.
+Many different hashtable-based data structures can be constructed with
+little effort.
+.PP
+The
+.BR sym (3)
+module implements a rather good general-purpose extending hash table.
+Keys and values can be arbitrary data.  It is implemented using
+.BR hash (3).
+.PP
+The
+.BR atom (3)
+module implements
+.IR atoms ,
+which are essentially strings with the property that two atoms have the
+same address if and only if they have the same text, so they can be used
+for rapid string comparisons.  The
+.BR assoc (3)
+module implements a hash table which uses atoms as keys, thus saving
+time spent hashing and comparing hash keys, and the space used for the
+keys.

 .PP
 The
 .PP
 The

-.B dynarray
-module (not yet documented) implements unbounded sparse arrays.  It
-needs rewriting.
+.BR darray (3)
+module implements dynamically resizing arrays which support Perl-like
+stack operations efficiently.

 .SS "Miscellaneous utilities"
 The
 .SS "Miscellaneous utilities"
 The

-.B crc32
-module calculates CRC values for strings.  It's used by the symbol table
-manager as a hash function.
+.BR crc32 (3)
+module calculates CRC values for strings.  It used to be used by the
+symbol table manager as a hash function.

 .PP
 The
 .PP
 The

-.B lock
+.BR unihash (3)
+module implements a simple but efficient universal hashing family.  This
+is a keyed hash function which provides security against an adversary
+choosing input to a hash table deliberately to cause collisions.
+.PP
+The
+.BR lock (3)

 module does POSIX
 .BR fcntl (2)-style
 locking with a timeout.
 .PP
 The
 module does POSIX
 .BR fcntl (2)-style
 locking with a timeout.
 .PP
 The

-.B env
+.BR env (3)

 module manipulates environment variables stored in a hashtable, and
 converts between the hashtable and the standard array representation of
 a process environment.
 .PP
 The
 module manipulates environment variables stored in a hashtable, and
 converts between the hashtable and the standard array representation of
 a process environment.
 .PP
 The

-.B fdflags
+.BR fdflags (3)

 module manipulates file descriptor flags in a fairly painless way.
 .PP
 The
 module manipulates file descriptor flags in a fairly painless way.
 .PP
 The

-.B lbuf
+.BR fwatch (3)
+module allows you to easily find out whether a file has changed since
+the last time you looked at it.
+.PP
+The
+.BR lbuf (3)

 module implements a `line buffer', which is an object that emits
 completed lines of text from an incoming asynchronous data stream.  It's
 remarkably handy in programs that want to read lines from pipes and
 module implements a `line buffer', which is an object that emits
 completed lines of text from an incoming asynchronous data stream.  It's
 remarkably handy in programs that want to read lines from pipes and

-sockets can't block while waiting for a line-end to arrive.
+sockets can't block while waiting for a line-end to arrive.  Similarly,
+the
+.BR pkbuf (3)
+module implements a `packet buffer', which waits for packets of given
+lengths to arrive before dispatching them to a handler.

 .PP
 The
 .PP
 The

-.B tv
+.BR tv (3)

 module provides some macros and functions for playing with
 module provides some macros and functions for playing with

-.B "struct timeval"
+.BR "struct timeval" .

 .PP
 The
 .PP
 The

-.B bits
+.BR bits (3)

 module defines some types and macros for playing with words as chunks of
 bits.  There are portable rotate and shift macros (harder than you'd
 think), and macros to do loading and storing in known-endian formats.
 values.
 .PP
 The
 module defines some types and macros for playing with words as chunks of
 bits.  There are portable rotate and shift macros (harder than you'd
 think), and macros to do loading and storing in known-endian formats.
 values.
 .PP
 The

-.B mdwopt
+.BR mdwopt (3)

 module implements a fairly serious options parser compatible with the
 GNU options parser.
 .PP
 The
 module implements a fairly serious options parser compatible with the
 GNU options parser.
 .PP
 The

-.B testrig
+.BR testrig (3)

 module provides a generic structure for reading test vectors from files
 and running them through functions.  I mainly use it for testing
 cryptographic transformations of various kinds.
 .SS "Encoding and decoding"
 The
 module provides a generic structure for reading test vectors from files
 and running them through functions.  I mainly use it for testing
 cryptographic transformations of various kinds.
 .SS "Encoding and decoding"
 The

-.B base64
+.BR base64 (3)

 module does base64 encoding and decoding, as defined in RFC2045.  Base64
 encodes arbitrary binary data in a reliable way which is resistant to
 module does base64 encoding and decoding, as defined in RFC2045.  Base64
 encodes arbitrary binary data in a reliable way which is resistant to

-character-set transformations and other mail transport bogosity.
+character-set transformations and other mail transport bogosity.  The
+.BR base32 (3)
+module does base32 encoding and decoding, as defined in RFC2938.  This
+is a mad format which is needed for sha1 URNs, for no good reason.  The
+.BR hex (3)
+module does hex encoding and decoding.

 .PP
 The
 .PP
 The

-.B url
+.BR url (3)

 module does urlencoding and decoding, as defined in RFC1866.
 Urlencoding encodes arbitrary (but mostly text-like) name/value pairs as
 a text string containing no whitespace.
 .SS "Multiplexed I/O"
 The
 module does urlencoding and decoding, as defined in RFC1866.
 Urlencoding encodes arbitrary (but mostly text-like) name/value pairs as
 a text string containing no whitespace.
 .SS "Multiplexed I/O"
 The

-.B sel
+.BR sel (3)

 module provides a basis for doing nonblocking I/O in Unix systems.  It
 provides types and functions for receiving events when files are ready
 for reading or writing, and when timers expire.
 .PP
 The
 module provides a basis for doing nonblocking I/O in Unix systems.  It
 provides types and functions for receiving events when files are ready
 for reading or writing, and when timers expire.
 .PP
 The

-.B conn
+.BR conn (3)

 module implements nonblocking network connections in a way which fits in
 with the
 .B sel
 system.  It makes nonblocking connects pretty much trivial.
 .PP
 The
 module implements nonblocking network connections in a way which fits in
 with the
 .B sel
 system.  It makes nonblocking connects pretty much trivial.
 .PP
 The

-.B selbuf
+.BR selbuf (3)

 module attaches to the
 .B sel
 module attaches to the
 .B sel

-system and sends an event when lines of text arrive on a file.  It's
-useful when reading text from a network connection.
+system and sends an event when lines of text arrive from a file.  It's
+useful when reading text from a network connection.  Similarly,
+.BR selpk (3)
+sents events when packets of given sizes arrive from a file.
+.PP
+The
+.BR sig (3)
+module introduces signal handling into the multiplexed I/O world.
+Signals are queued until dispatched through the normal
+.B sel
+mechanism.
+.PP
+The
+.BR ident (3)
+module provides a nonblocking ident (RFC931) client.  The
+.BR bres (3)
+module does background hostname and address resolution.

 .SH "SEE ALSO"
 .BR alloc (3),
 .SH "SEE ALSO"
 .BR alloc (3),

+.BR assoc (3),
+.BR atom (3),

 .BR base64 (3),
 .BR bits (3),
 .BR base64 (3),
 .BR bits (3),

+.BR buf (3),
+.BR bres (3),

 .BR conn (3),
 .BR crc32 (3),
 .BR conn (3),
 .BR crc32 (3),

+.BR darray (3),

 .BR dspool (3),
 .BR dstr (3),
 .BR env (3),
 .BR exc (3),
 .BR fdflags (3),
 .BR dspool (3),
 .BR dstr (3),
 .BR env (3),
 .BR exc (3),
 .BR fdflags (3),

+.BR fwatch (3),
+.BR hash (3),
+.BR ident (3),

 .BR lbuf (3),
 .BR lock (3),
 .BR mdwopt (3),
 .BR lbuf (3),
 .BR lock (3),
 .BR mdwopt (3),

+.BR pkbuf (3),

 .BR quis (3),
 .BR report (3),
 .BR sel (3),
 .BR selbuf (3),
 .BR quis (3),
 .BR report (3),
 .BR sel (3),
 .BR selbuf (3),

+.BR selpk (3),
+.BR sig (3),

 .BR str (3),
 .BR sub (3),
 .BR sym (3),
 .BR str (3),
 .BR sub (3),
 .BR sym (3),

+.BR trace (3),

 .BR tv (3),
 .BR url (3).
 .SH AUTHOR
 .BR tv (3),
 .BR url (3).
 .SH AUTHOR

-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>