                          September 22, 2003

The home page for "shunt" and "exactly" is at the following URL:

    http://www.serice.net/shunt/

More detailed documentation can be found at the home page, but
briefly, "shunt" is a general tool that allows you to replace
processes in one segment of a pipe without breaking the pipe
regardless of where you insert the process.

As it currently stands, "shunt" can only restart the same process
after that process exits, but this is good enough for things like
burning CDs without having to resort to using temporary files for ISO
images.  Also, if you need more sophisticated process replacement, you
can always move that logic into the shell script that is being
restarted or perhaps by calling "shunt" recursively.

As a convenience, "shunt" sets the following two environment
variables:

        SHUNT_STARTS ==> Counts how often this process has started.
    SHUNT_ALL_STARTS ==> Counts how often all process have started.

By default these environment variables are based on the "unsigned long
int" type which means by default you will not have a dependency on
libcalc when building, but you might have to worry about overflow in
some extreme circumstances.  You can change the default in the
Config.mk file by enabling BUILD_SHUNT_USING_LIBCALC.  If you decide
to use libcalc, you will have to it installed somewhere on your
system, and the size of the "shunt" executable will jump from 10K to
600K.  The advantage is that you will not have to worry about
overflow.  You now get to worry about running out of memory.  :-) My
recommendation is that you build with libcalc if you can unless you
need to build a version of "shunt" that needs to fit on a disaster
recovery floppy.

The other tool in this package is called "exactly."  It is used to
make sure that consumers on your pipe consume an exact amount of data
-- no more, no less.  This is useful especially when the consumer is
using the standard C/C++ buffered I/O libraries.

I have personally compiled this on FreeBSD, Linux, NetBSD, and
OpenBSD.  I haven't tested it thoroughly, but it seems to work in
general.  Specifically under Linux, I have had very good success using
the included programs along with mkisofs and cdrecord to make backups
to CDs that span multiple volumes without the need for any temporary
files.  Also, when restoring, you can use the included programs to
restore without the need for any temporary files.

If you have success with this program, please send me an e-mail at
Paul Serice <paul@serice.net>.  I'm interested not only in how you use
it to make backups with CDs and DVDs, but also new uses to which you
put it.

Thanks,
Paul Serice
