The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
TODDR / IPC-Run-0.99 / README.md

Build Status

Build status

NAME

IPC::Run - system() and background procs w/ piping, redirs, ptys (Unix, Win32)

SYNOPSIS

## First,a command to run:
   my @cat = qw( cat );

## Using run() instead of system():
   use IPC::Run qw( run timeout );

   run \@cat, \$in, \$out, \$err, timeout( 10 ) or die "cat: $?"

   # Can do I/O to sub refs and filenames, too:
   run \@cat, '<', "in.txt", \&out, \&err or die "cat: $?"
   run \@cat, '<', "in.txt", '>>', "out.txt", '2>>', "err.txt";


   # Redirecting using pseudo-terminals instead of pipes.
   run \@cat, '<pty<', \$in,  '>pty>', \$out_and_err;

## Scripting subprocesses (like Expect):

   use IPC::Run qw( start pump finish timeout );

   # Incrementally read from / write to scalars. 
   # $in is drained as it is fed to cat's stdin,
   # $out accumulates cat's stdout
   # $err accumulates cat's stderr
   # $h is for "harness".
   my $h = start \@cat, \$in, \$out, \$err, timeout( 10 );

   $in .= "some input\n";
   pump $h until $out =~ /input\n/g;

   $in .= "some more input\n";
   pump $h until $out =~ /\G.*more input\n/;

   $in .= "some final input\n";
   finish $h or die "cat returned $?";

   warn $err if $err; 
   print $out;         ## All of cat's output

# Piping between children
   run \@cat, '|', \@gzip;

# Multiple children simultaneously (run() blocks until all
# children exit, use start() for background execution):
   run \@foo1, '&', \@foo2;

# Calling \&set_up_child in the child before it executes the
# command (only works on systems with true fork() & exec())
# exceptions thrown in set_up_child() will be propagated back
# to the parent and thrown from run().
   run \@cat, \$in, \$out,
      init => \&set_up_child;

# Read from / write to file handles you open and close
   open IN,  '<in.txt'  or die $!;
   open OUT, '>out.txt' or die $!;
   print OUT "preamble\n";
   run \@cat, \*IN, \*OUT or die "cat returned $?";
   print OUT "postamble\n";
   close IN;
   close OUT;

# Create pipes for you to read / write (like IPC::Open2 & 3).
   $h = start
      \@cat,
         '<pipe', \*IN,
         '>pipe', \*OUT,
         '2>pipe', \*ERR 
      or die "cat returned $?";
   print IN "some input\n";
   close IN;
   print <OUT>, <ERR>;
   finish $h;

# Mixing input and output modes
   run \@cat, 'in.txt', \&catch_some_out, \*ERR_LOG );

# Other redirection constructs
   run \@cat, '>&', \$out_and_err;
   run \@cat, '2>&1';
   run \@cat, '0<&3';
   run \@cat, '<&-';
   run \@cat, '3<', \$in3;
   run \@cat, '4>', \$out4;
   # etc.

# Passing options:
   run \@cat, 'in.txt', debug => 1;

# Call this system's shell, returns TRUE on 0 exit code
# THIS IS THE OPPOSITE SENSE OF system()'s RETURN VALUE
   run "cat a b c" or die "cat returned $?";

# Launch a sub process directly, no shell.  Can't do redirection
# with this form, it's here to behave like system() with an
# inverted result.
   $r = run "cat a b c";

# Read from a file in to a scalar
   run io( "filename", 'r', \$recv );
   run io( \*HANDLE,   'r', \$recv );

DESCRIPTION

IPC::Run allows you to run and interact with child processes using files, pipes, and pseudo-ttys. Both system()-style and scripted usages are supported and may be mixed. Likewise, functional and OO API styles are both supported and may be mixed.

Various redirection operators reminiscent of those seen on common Unix and DOS command lines are provided.

Before digging in to the details a few LIMITATIONS are important enough to be mentioned right up front:

We now return you to your regularly scheduled documentation.

Harnesses

Child processes and I/O handles are gathered in to a harness, then started and run until the processing is finished or aborted.

run() vs. start(); pump(); finish();

There are two modes you can run harnesses in: run() functions as an enhanced system(), and start()/pump()/finish() allow for background processes and scripted interactions with them.

When using run(), all data to be sent to the harness is set up in advance (though one can feed subprocesses input from subroutine refs to get around this limitation). The harness is run and all output is collected from it, then any child processes are waited for:

run \@cmd, \<<IN, \$out;
blah
IN

## To precompile harnesses and run them later:
my $h = harness \@cmd, \<<IN, \$out;
blah
IN

run $h;

The background and scripting API is provided by start(), pump(), and finish(): start() creates a harness if need be (by calling harness()) and launches any subprocesses, pump() allows you to poll them for activity, and finish() then monitors the harnessed activities until they complete.

## Build the harness, open all pipes, and launch the subprocesses
my $h = start \@cat, \$in, \$out;
$in = "first input\n";

## Now do I/O.  start() does no I/O.
pump $h while length $in;  ## Wait for all input to go

## Now do some more I/O.
$in = "second input\n";
pump $h until $out =~ /second input/;

## Clean up
finish $h or die "cat returned $?";

You can optionally compile the harness with harness() prior to start()ing or run()ing, and you may omit start() between harness() and pump(). You might want to do these things if you compile your harnesses ahead of time.

Using regexps to match output

As shown in most of the scripting examples, the read-to-scalar facility for gathering subcommand's output is often used with regular expressions to detect stopping points. This is because subcommand output often arrives in dribbles and drabs, often only a character or line at a time. This output is input for the main program and piles up in variables like the $out and $err in our examples.

Regular expressions can be used to wait for appropriate output in several ways. The cat example in the previous section demonstrates how to pump() until some string appears in the output. Here's an example that uses smb to fetch files from a remote server:

$h = harness \@smbclient, \$in, \$out;

$in = "cd /src\n";
$h->pump until $out =~ /^smb.*> \Z/m;
die "error cding to /src:\n$out" if $out =~ "ERR";
$out = '';

$in = "mget *\n";
$h->pump until $out =~ /^smb.*> \Z/m;
die "error retrieving files:\n$out" if $out =~ "ERR";

$in = "quit\n";
$h->finish;

Notice that we carefully clear $out after the first command/response cycle? That's because IPC::Run does not delete $out when we continue, and we don't want to trip over the old output in the second command/response cycle.

Say you want to accumulate all the output in $out and analyze it afterwards. Perl offers incremental regular expression matching using the m//gc and pattern matching idiom and the \G assertion. IPC::Run is careful not to disturb the current pos() value for scalars it appends data to, so we could modify the above so as not to destroy $out by adding a couple of /gc modifiers. The /g keeps us from tripping over the previous prompt and the /c keeps us from resetting the prior match position if the expected prompt doesn't materialize immediately:

$h = harness \@smbclient, \$in, \$out;

$in = "cd /src\n";
$h->pump until $out =~ /^smb.*> \Z/mgc;
die "error cding to /src:\n$out" if $out =~ "ERR";

$in = "mget *\n";
$h->pump until $out =~ /^smb.*> \Z/mgc;
die "error retrieving files:\n$out" if $out =~ "ERR";

$in = "quit\n";
$h->finish;

analyze( $out );

When using this technique, you may want to preallocate $out to have plenty of memory or you may find that the act of growing $out each time new input arrives causes an O(length($out)^2) slowdown as $out grows. Say we expect no more than 10,000 characters of input at the most. To preallocate memory to $out, do something like:

my $out = "x" x 10_000;
$out = "";

perl will allocate at least 10,000 characters' worth of space, then mark the $out as having 0 length without freeing all that yummy RAM.

Timeouts and Timers

More than likely, you don't want your subprocesses to run forever, and sometimes it's nice to know that they're going a little slowly. Timeouts throw exceptions after a some time has elapsed, timers merely cause pump() to return after some time has elapsed. Neither is reset/restarted automatically.

Timeout objects are created by calling timeout( $interval ) and passing the result to run(), start() or harness(). The timeout period starts ticking just after all the child processes have been fork()ed or spawn()ed, and are polled for expiration in run(), pump() and finish(). If/when they expire, an exception is thrown. This is typically useful to keep a subprocess from taking too long.

If a timeout occurs in run(), all child processes will be terminated and all file/pipe/ptty descriptors opened by run() will be closed. File descriptors opened by the parent process and passed in to run() are not closed in this event.

If a timeout occurs in pump(), pump_nb(), or finish(), it's up to you to decide whether to kill_kill() all the children or to implement some more graceful fallback. No I/O will be closed in pump(), pump_nb() or finish() by such an exception (though I/O is often closed down in those routines during the natural course of events).

Often an exception is too harsh. timer( $interval ) creates timer objects that merely prevent pump() from blocking forever. This can be useful for detecting stalled I/O or printing a soothing message or "." to pacify an anxious user.

Timeouts and timers can both be restarted at any time using the timer's start() method (this is not the start() that launches subprocesses). To restart a timer, you need to keep a reference to the timer:

  ## Start with a nice long timeout to let smbclient connect.  If
  ## pump or finish take too long, an exception will be thrown.

my $h;
eval {
  $h = harness \@smbclient, \$in, \$out, \$err, ( my $t = timeout 30 );
  sleep 11;  # No effect: timer not running yet

  start $h;
  $in = "cd /src\n";
  pump $h until ! length $in;

  $in = "ls\n";
  ## Now use a short timeout, since this should be faster
  $t->start( 5 );
  pump $h until ! length $in;

  $t->start( 10 );  ## Give smbclient a little while to shut down.
  $h->finish;
};
if ( $@ ) {
  my $x = $@;    ## Preserve $@ in case another exception occurs
  $h->kill_kill; ## kill it gently, then brutally if need be, or just
                  ## brutally on Win32.
  die $x;
}

Timeouts and timers are not checked once the subprocesses are shut down; they will not expire in the interval between the last valid process and when IPC::Run scoops up the processes' result codes, for instance.

Spawning synchronization, child exception propagation

start() pauses the parent until the child executes the command or CODE reference and propagates any exceptions thrown (including exec() failure) back to the parent. This has several pleasant effects: any exceptions thrown in the child, including exec() failure, come flying out of start() or run() as though they had occurred in the parent.

This includes exceptions your code thrown from init subs. In this example:

eval {
   run \@cmd, init => sub { die "blast it! foiled again!" };
};
print $@;

the exception "blast it! foiled again" will be thrown from the child process (preventing the exec()) and printed by the parent.

In situations like

run \@cmd1, "|", \@cmd2, "|", \@cmd3;

@cmd1 will be initted and exec()ed before @cmd2, and @cmd2 before @cmd3. This can save time and prevent oddball errors emitted by later commands when earlier commands fail to execute. Note that IPC::Run doesn't start any commands unless it can find the executables referenced by all commands. These executables must pass both the -f and -x tests described in perlfunc.

Another nice effect is that init() subs can take their time doing things and there will be no problems caused by a parent continuing to execute before a child's init() routine is complete. Say the init() routine needs to open a socket or a temp file that the parent wants to connect to; without this synchronization, the parent will need to implement a retry loop to wait for the child to run, since often, the parent gets a lot of things done before the child's first timeslice is allocated.

This is also quite necessary for pseudo-tty initialization, which needs to take place before the parent writes to the child via pty. Writes that occur before the pty is set up can get lost.

A final, minor, nicety is that debugging output from the child will be emitted before the parent continues on, making for much clearer debugging output in complex situations.

The only drawback I can conceive of is that the parent can't continue to operate while the child is being initted. If this ever becomes a problem in the field, we can implement an option to avoid this behavior, but I don't expect it to.

Win32: executing CODE references isn't supported on Win32, see "Win32 LIMITATIONS" for details.

Syntax

run(), start(), and harness() can all take a harness specification as input. A harness specification is either a single string to be passed to the systems' shell:

run "echo 'hi there'";

or a list of commands, io operations, and/or timers/timeouts to execute. Consecutive commands must be separated by a pipe operator '|' or an '&'. External commands are passed in as array references, and, on systems supporting fork(), Perl code may be passed in as subs:

run \@cmd;
run \@cmd1, '|', \@cmd2;
run \@cmd1, '&', \@cmd2;
run \&sub1;
run \&sub1, '|', \&sub2;
run \&sub1, '&', \&sub2;

'|' pipes the stdout of \@cmd1 the stdin of \@cmd2, just like a shell pipe. '&' does not. Child processes to the right of a '&' will have their stdin closed unless it's redirected-to.

IPC::Run::IO objects may be passed in as well, whether or not child processes are also specified:

run io( "infile", ">", \$in ), io( "outfile", "<", \$in );

as can IPC::Run::Timer objects:

run \@cmd, io( "outfile", "<", \$in ), timeout( 10 );

Commands may be followed by scalar, sub, or i/o handle references for redirecting child process input & output:

run \@cmd,  \undef,            \$out;
run \@cmd,  \$in,              \$out;
run \@cmd1, \&in, '|', \@cmd2, \*OUT;
run \@cmd1, \*IN, '|', \@cmd2, \&out;

This is known as succinct redirection syntax, since run(), start() and harness(), figure out which file descriptor to redirect and how. File descriptor 0 is presumed to be an input for the child process, all others are outputs. The assumed file descriptor always starts at 0, unless the command is being piped to, in which case it starts at 1.

To be explicit about your redirects, or if you need to do more complex things, there's also a redirection operator syntax:

run \@cmd, '<', \undef, '>',  \$out;
run \@cmd, '<', \undef, '>&', \$out_and_err;
run(
   \@cmd1,
      '<', \$in,
   '|', \@cmd2,
      \$out
);

Operator syntax is required if you need to do something other than simple redirection to/from scalars or subs, like duping or closing file descriptors or redirecting to/from a named file. The operators are covered in detail below.

After each \@cmd (or \&foo), parsing begins in succinct mode and toggles to operator syntax mode when an operator (ie plain scalar, not a ref) is seen. Once in operator syntax mode, parsing only reverts to succinct mode when a '|' or '&' is seen.

In succinct mode, each parameter after the \@cmd specifies what to do with the next highest file descriptor. These File descriptor start with 0 (stdin) unless stdin is being piped to ('|', \@cmd), in which case they start with 1 (stdout). Currently, being on the left of a pipe (\@cmd, \$out, \$err, '|') does not cause stdout to be skipped, though this may change since it's not as DWIMerly as it could be. Only stdin is assumed to be an input in succinct mode, all others are assumed to be outputs.

If no piping or redirection is specified for a child, it will inherit the parent's open file handles as dictated by your system's close-on-exec behavior and the $^F flag, except that processes after a '&' will not inherit the parent's stdin. Also note that $^F does not affect file descriptors obtained via POSIX, since it only applies to full-fledged Perl file handles. Such processes will have their stdin closed unless it has been redirected-to.

If you want to close a child processes stdin, you may do any of:

run \@cmd, \undef;
run \@cmd, \"";
run \@cmd, '<&-';
run \@cmd, '0<&-';

Redirection is done by placing redirection specifications immediately after a command or child subroutine:

run \@cmd1,      \$in, '|', \@cmd2,      \$out;
run \@cmd1, '<', \$in, '|', \@cmd2, '>', \$out;

If you omit the redirection operators, descriptors are counted starting at 0. Descriptor 0 is assumed to be input, all others are outputs. A leading '|' consumes descriptor 0, so this works as expected.

run \@cmd1, \$in, '|', \@cmd2, \$out;

The parameter following a redirection operator can be a scalar ref, a subroutine ref, a file name, an open filehandle, or a closed filehandle.

If it's a scalar ref, the child reads input from or sends output to that variable:

$in = "Hello World.\n";
run \@cat, \$in, \$out;
print $out;

Scalars used in incremental (start()/pump()/finish()) applications are treated as queues: input is removed from input scalers, resulting in them dwindling to '', and output is appended to output scalars. This is not true of harnesses run() in batch mode.

It's usually wise to append new input to be sent to the child to the input queue, and you'll often want to zap output queues to '' before pumping.

$h = start \@cat, \$in;
$in = "line 1\n";
pump $h;
$in .= "line 2\n";
pump $h;
$in .= "line 3\n";
finish $h;

The final call to finish() must be there: it allows the child process(es) to run to completion and waits for their exit values.

OBSTINATE CHILDREN

Interactive applications are usually optimized for human use. This can help or hinder trying to interact with them through modules like IPC::Run. Frequently, programs alter their behavior when they detect that stdin, stdout, or stderr are not connected to a tty, assuming that they are being run in batch mode. Whether this helps or hurts depends on which optimizations change. And there's often no way of telling what a program does in these areas other than trial and error and occasionally, reading the source. This includes different versions and implementations of the same program.

All hope is not lost, however. Most programs behave in reasonably tractable manners, once you figure out what it's trying to do.

Here are some of the issues you might need to be aware of.

PSEUDO TERMINALS

On systems providing pseudo terminals under /dev, IPC::Run can use IO::Pty (available on CPAN) to provide a terminal environment to subprocesses. This is necessary when the subprocess really wants to think it's connected to a real terminal.

CAVEATS

Pseudo-terminals are not pipes, though they are similar. Here are some differences to watch out for.

Redirection Operators

Operator       SHNP   Description
========       ====   ===========
<, N<          SHN    Redirects input to a child's fd N (0 assumed)

>, N>          SHN    Redirects output from a child's fd N (1 assumed)
>>, N>>        SHN    Like '>', but appends to scalars or named files
>&, &>         SHN    Redirects stdout & stderr from a child process

<pty, N<pty    S      Like '<', but uses a pseudo-tty instead of a pipe
>pty, N>pty    S      Like '>', but uses a pseudo-tty instead of a pipe

N<&M                  Dups input fd N to input fd M
M>&N                  Dups output fd N to input fd M
N<&-                  Closes fd N

<pipe, N<pipe     P   Pipe opens H for caller to read, write, close.
>pipe, N>pipe     P   Pipe opens H for caller to read, write, close.

'N' and 'M' are placeholders for integer file descriptor numbers. The terms 'input' and 'output' are from the child process's perspective.

The SHNP field indicates what parameters an operator can take:

S: \$scalar or \&function references.  Filters may be used with
   these operators (and only these).
H: \*HANDLE or IO::Handle for caller to open, and close
N: "file name".
P: \*HANDLE opened by IPC::Run as the parent end of a pipe, but read
   and written to and closed by the caller (like IPC::Open3).

Just doing I/O

If you just want to do I/O to a handle or file you open yourself, you may specify a filehandle or filename instead of a command in the harness specification:

run io( "filename", '>', \$recv );

$h = start io( $io, '>', \$recv );

$h = harness \@cmd, '&', io( "file", '<', \$send );

Options

Options are passed in as name/value pairs:

run \@cat, \$in, debug => 1;

If you pass the debug option, you may want to pass it in first, so you can see what parsing is going on:

run debug => 1, \@cat, \$in;

RETURN VALUES

harness() and start() return a reference to an IPC::Run harness. This is blessed in to the IPC::Run package, so you may make later calls to functions as members if you like:

$h = harness( ... );
$h->start;
$h->pump;
$h->finish;

$h = start( .... );
$h->pump;
...

Of course, using method call syntax lets you deal with any IPC::Run subclasses that might crop up, but don't hold your breath waiting for any.

run() and finish() return TRUE when all subcommands exit with a 0 result code. This is the opposite of perl's system() command.

All routines raise exceptions (via die()) when error conditions are recognized. A non-zero command result is not treated as an error condition, since some commands are tests whose results are reported in their exit codes.

ROUTINES

FILTERS

These filters are used to modify input our output between a child process and a scalar or subroutine endpoint.

FILTER IMPLEMENTATION FUNCTIONS

These functions are for use from within filters.

TODO

These will be addressed as needed and as time allows.

Stall timeout.

Expose a list of child process objects. When I do this, each child process is likely to be blessed into IPC::Run::Proc.

$kid->abort(), $kid->kill(), $kid->signal( $num_or_name ).

Write tests for /(full_)?results?/ subs.

Currently, pump() and run() only work on systems where select() works on the filehandles returned by pipe(). This does *not* include ActiveState on Win32, although it does work on cygwin under Win32 (thought the tests whine a bit). I'd like to rectify that, suggestions and patches welcome.

Likewise start() only fully works on fork()/exec() machines (well, just fork() if you only ever pass perl subs as subprocesses). There's some scaffolding for calling Open3::spawn_with_handles(), but that's untested, and not that useful with limited select().

Support for \@sub_cmd as an argument to a command which gets replaced with /dev/fd or the name of a temporary file containing foo's output. This is like <(sub_cmd ...) found in bash and csh (IIRC).

Allow multiple harnesses to be combined as independent sets of processes in to one 'meta-harness'.

Allow a harness to be passed in place of an \@cmd. This would allow multiple harnesses to be aggregated.

Ability to add external file descriptors w/ filter chains and endpoints.

Ability to add timeouts and timing generators (i.e. repeating timeouts).

High resolution timeouts.

Win32 LIMITATIONS

LIMITATIONS

On Unix, requires a system that supports waitpid( $pid, WNOHANG ) so it can tell if a child process is still running.

PTYs don't seem to be non-blocking on some versions of Solaris. Here's a test script contributed by Borislav Deianov borislav@ensim.com to see if you have the problem. If it dies, you have the problem.

#!/usr/bin/perl

use IPC::Run qw(run);
use Fcntl;
use IO::Pty;

sub makecmd {
    return ['perl', '-e', 
            '<STDIN>, print "\n" x '.$_[0].'; while(<STDIN>){last if /end/}'];
}

#pipe R, W;
#fcntl(W, F_SETFL, O_NONBLOCK);
#while (syswrite(W, "\n", 1)) { $pipebuf++ };
#print "pipe buffer size is $pipebuf\n";
my $pipebuf=4096;
my $in = "\n" x ($pipebuf * 2) . "end\n";
my $out;

$SIG{ALRM} = sub { die "Never completed!\n" };

print "reading from scalar via pipe...";
alarm( 2 );
run(makecmd($pipebuf * 2), '<', \$in, '>', \$out);
alarm( 0 );
print "done\n";

print "reading from code via pipe... ";
alarm( 2 );
run(makecmd($pipebuf * 3), '<', sub { $t = $in; undef $in; $t}, '>', \$out);
alarm( 0 );
print "done\n";

$pty = IO::Pty->new();
$pty->blocking(0);
$slave = $pty->slave();
while ($pty->syswrite("\n", 1)) { $ptybuf++ };
print "pty buffer size is $ptybuf\n";
$in = "\n" x ($ptybuf * 3) . "end\n";

print "reading via pty... ";
alarm( 2 );
run(makecmd($ptybuf * 3), '<pty<', \$in, '>', \$out);
alarm(0);
print "done\n";

No support for ';', '&&', '||', '{ ... }', etc: use perl's, since run() returns TRUE when the command exits with a 0 result code.

Does not provide shell-like string interpolation.

No support for cd, setenv, or export: do these in an init() sub

run(
   \cmd,
      ...
      init => sub {
         chdir $dir or die $!;
         $ENV{FOO}='BAR'
      }
);

Timeout calculation does not allow absolute times, or specification of days, months, etc.

WARNING: Function coprocesses (run \&foo, ...) suffer from two limitations. The first is that it is difficult to close all filehandles the child inherits from the parent, since there is no way to scan all open FILEHANDLEs in Perl and it both painful and a bit dangerous to close all open file descriptors with POSIX::close(). Painful because we can't tell which fds are open at the POSIX level, either, so we'd have to scan all possible fds and close any that we don't want open (normally exec() closes any non-inheritable but we don't exec() for &sub processes.

The second problem is that Perl's DESTROY subs and other on-exit cleanup gets run in the child process. If objects are instantiated in the parent before the child is forked, the DESTROY will get run once in the parent and once in the child. When coprocess subs exit, POSIX::_exit is called to work around this, but it means that objects that are still referred to at that time are not cleaned up. So setting package vars or closure vars to point to objects that rely on DESTROY to affect things outside the process (files, etc), will lead to bugs.

I goofed on the syntax: "<pipe" vs. "<pty<" and ">filename" are both oddities.

TODO

INSPIRATION

Well, select() and waitpid() badly needed wrapping, and open3() isn't open-minded enough for me.

The shell-like API inspired by a message Russ Allbery sent to perl5-porters, which included:

I've thought for some time that it would be
nice to have a module that could handle full Bourne shell pipe syntax
internally, with fork and exec, without ever invoking a shell.  Something
that you could give things like:

pipeopen (PIPE, [ qw/cat file/ ], '|', [ 'analyze', @args ], '>&3');

Message ylln51p2b6.fsf@windlord.stanford.edu, on 2000/02/04.

SUPPORT

Bugs should always be submitted via the GitHub bug tracker

https://github.com/toddr/IPC-Run/issues

AUTHORS

Adam Kennedy adamk@cpan.org

Barrie Slaymaker barries@slaysys.com

COPYRIGHT

Some parts copyright 2008 - 2009 Adam Kennedy.

Copyright 1999 Barrie Slaymaker.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the README file.