From 323ffb6cddd1a6a65d06e254817a5c394195b758 Mon Sep 17 00:00:00 2001 Message-Id: <323ffb6cddd1a6a65d06e254817a5c394195b758.1714022650.git.mdw@distorted.org.uk> From: Mark Wooding Date: Fri, 22 Oct 1999 22:35:56 +0000 Subject: [PATCH] Corrections and general updates. Organization: Straylight/Edgeware From: mdw --- README | 75 ++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 62 insertions(+), 13 deletions(-) diff --git a/README b/README index aabf178..ab2c79c 100644 --- a/README +++ b/README @@ -4,13 +4,20 @@ mLib Overview mLib is a collection of bits of code I've found handy in various - programs. With a few very minor exceptions, the routines are - highly portable, and mostly strictly conformant. + programs. Once upon a time, almost all of the code was nearly- + strictly conforming C. Since then, a big pile of Unix-specific + code's been added, with a particularly strong networking + emphasis. The Unix-specific code is targetted at sensible + POSIX-conforming systems, and should port easily. My programming style is probably what you'd describe as `unconventional'. I'm skeptical about object-orientation, and not a huge fan of over-hiding information of any kind. The - structure and interface of the library reflects these views. + structure and interface of the library reflects these views. On + the other hand, I like documentation quite a lot. + + +Documentation There is now a (hopefully fairly good) set of manual pages for mLib. The manual isn't installed by default since it takes a @@ -21,6 +28,18 @@ Overview (after everything else is built, obviously). + There's also documentation in the header files. The header file + comments were, in general, written at the same time as the code. + This has the disadvantage that they focus at a fairly low level, + and use terminology relating to the implementation rather than + the interface. + + The header file comments can be handy for quick browsing. + However, the manual pages are considered the authoritative + source of information about the programming interface. If you + have to look at the source code, it usually means that my + documentation or interface design is wrong. + Quick tour @@ -65,6 +84,12 @@ Quick tour function), and permits arbitrary data blocks in both the keys and values. It seems fairly quick. + * `hash.h' provides the underpinnings of the `sym' hashtable. + It's a completely generic hashtable skeleton. It provides + the basics like rehashing when the table is full and so on. + It needs a fair bit of work to turn into a usable data + structure, though, which is what `sym' is for. + * `dstr.h' provides a dynamically sized string type. In the rather paltry tests I've run, it seemed faster than libstdc++'s string type, but I shouldn't read too much into @@ -73,12 +98,11 @@ Quick tour string looks sane before you start expecting any of the functions or macros to work. - * `dynarray.h' is a big nasty macro which defines functions - capable of dealing with dynamically-sized arrays of - arbitrary types. (You build a new set of functions for each - type. Think of it as a hacky C++ template-a-like.) The - arrays are sparse, but not ever-so efficient in terms of - look-up time. + * `darray.h' implements dynamically growing arrays which can be + extended at both ends, a bit like Perl's. It replaces the + old `dynarray.h' which wasn't very good. However, `darray's + arrays are not sparse. Maybe a good sparse array module + will be added later. At the same conceptual level, there's some code for handling multiplexed I/O. Although the core is named `sel', and it uses @@ -108,10 +132,30 @@ Quick tour connect, and adds itself to the select system. When the connect completes, you get given the file descriptor. + * `ident.h' is an RFC931 (identd) client. + + * `bres.h' is a background name resolver. It keeps a pool of + resolver processes to answer queries. + + * `sig.h' traps signals and dispatches them through the + event-driven `sel' system. + Then there's a bunch of other stuff. + * `base64.h' does Base64 encoding and decoding. + + * `bits.h' provides some portable bit manipulation macros. + * `crc32.h' declares the 32-bit CRC used by `sym'. + * `env.h' provides some routines for handling environment + variables in a hashtable. + + * `fdflags.h' encapsulates some traditional little dances with + fcntl when playing with nonblocking files. + + * `lock.h' does fcntl-style locking with a timeout. + * `quis.h' works out the program name from the value of `argv[0]' and puts it in a variable for everything else to find. @@ -119,6 +163,9 @@ Quick tour * `report.h' reports fatal and nonfatal errors in the standard Unixy way. + * `str.h' provides some occasionally useful string- + manipulation toys. + * `trace.h' provides a simple tracing facility, which can be turned on and off both at compile- and run-time. @@ -128,11 +175,13 @@ Quick tour results. It's particularly handy with cryptographic algorithms, I find. - -Future directions - - I'm going to write some manual pages. Promise. + * `url.h' does url-encoding, which armours mostly-textual + name/value pairs so they contain no whitespace characters. Mark Wooding mdw@nsict.org + +Local variables: +mode: text +End: -- [mdw]