NAME

       File::RsyncP::FileIO - Perl Rsync client file system IO

SYNOPSIS

           use File::RsyncP::FileIO;

           my $rs = File::RsyncP->new({
                       logLevel   => 1,
                       rsyncCmd => ["/bin/rsh", $host,  "-l", $user, "/bin/rsync"],
                       rsyncArgs  => [qw(
                               --numeric-ids
                               --perms
                               --owner
                               --group
                               --devices
                               --links
                               --ignore-times
                               --block-size=700
                               --relative
                               --recursive
                               -v
                           )],
                       logHandler => sub {
                               my($str) = @_;
                               print MyHandler "log: $str\n";
                           };
                       fio        => File::RsyncP::FileIO->new({
                                       logLevel   => 1,
                                   });

                   });

DESCRIPTION

       File::RsyncP::FileIO contains all of the file system access functions needed by
       File::RsyncP.  This functionality is relegated to this module so it can be subclassed or
       replaced by different code for applications where an rsync interface is provided for non-
       file system data (eg: databases).

       File::RsyncP::FileIO provides the following functions.

   Setup and utility functions
       new({ options... })
           Creates a new File::RsyncP::FileIO object.  The single argument is a hashref of
           options:

           blockSize
               Defaults to 700.  Can be set later using the blockSize function.

           logLevel
               Defaults to 0.  Controls the verbosity of FileIO operations.

           digest
               Defaults to File::RsyncP::Digest->new.  No need to override.

           checksumSeed
               The checksum seed used in digest calculations.  Defaults to 0.  The server-side
               Rsync generates a checksum seed and sends it to the client.  This value is usually
               set later, after the checksum seed is received from the remote rsync, via the
               checksumSeed function.

           logHandler
               A subroutine reference to a function that handles all the log messages.  The
               default is a subroutine that prints the messages to STDERR.

       blockSize($value)
           Set the block size to the new value, in case it wasn't set via the blockSize option to
           new().

       checksumSeed($seed)
           Set the checksum seed used in digest calculations to the new value.  Usually this
           value isn't known when new() is called, so it is necessary to set it later via this
           function.

       logHandlerSet
           Set the log handler callback function.  Usually this value is specified via new(), but
           it can be changed later via this function.

       dirs($localDir, $remoteDir)
           Specify the local and remote directories.

       log(@msg)
           Save one (or more) messages for logging purposes.

       statsGet
           Return an optional hashref of statistics compiled by the FileIO object.  These values
           are opaquely passed up to File::RsyncP.

       finish($isChild)
           Do any necessary finish-up processing.  The $isChild argument is true if this is the
           child process (remember the receiving side has two processes: the child receives the
           file deltas while the parent generates the block digests).

   Checksum computation functions
       csumStart($f, $needMD4)
           Get ready to generate block checksums for the given file.  The argument is a hashref
           typically returned by File::RsyncP::FileList->get.  Typically this opens the
           underlying file and creates a File::RsyncP::Digest object.  If $needMD4 is non-zero,
           then csumEnd() will return the file MD4 digest.

       csumGet($num, $csumLen, $blockSize)
           Return $num bkocks work of checksums with the MD4 checksum length of $csumLen
           (typically 2 or 16), with a block size of $blockSize.  Typically this reads the file
           and calls File::RsyncP::Digest->blockDigest.

       csumEnd()
           Finish up the checksum calculation.  Typically closes the underlying file.  Note that
           csumStart, csumGet, csumEnd are called in strict order so they don't need to be
           reentrant (ie: there is only one csum done at a time).  If csumStart() was called with
           $needMD4 then csumEnd() will return the file MD4 digest.

   File reading functions
       There are used for sending files (currently sending files doesn't implement deltas; it
       behaves as though --whole-file was specified):

       readStart($f)
           Get ready to read the given file.  The argument is a hashref typically returned by
           File::RsyncP::FileList->get.  Typically this opens the underlying file.

       read($num)
           Read $num bytes from the file.

       readEnd()
           Finish up the read operation.  Typically closes the underlying file.  Note that
           readStart, readGet, readEnd are called in strict order so they don't need to be
           reentrant (ie: there is only one read done at a time).

   File operations
       attribGet($f)
           Return the attributes for the given file as a hashref.  The argument is a hashref
           typically returned by File::RsyncP::FileList->get.

       attribSet($f, $placeHolder)
           Set the attributes for the given file.  The argument is a hashref typically returned
           by File::RsyncP::FileList->get.  If $placeHolder is true then don't do anything.
           Returns undef on success.

       makePath($f)
           Create the directory specified by $f.  The argument is a hashref typically returned by
           File::RsyncP::FileList->get.  Returns undef on success.

       makeSpecial($f)
           Create the special file specified by $f.  The argument is a hashref typically returned
           by File::RsyncP::FileList->get.  Returns undef on success.

       unlink($remotePath)
           Unlink the file or directory corresponding to the given remote path.

       ignoreAttrOnFile($f)
           Normally should return undef, meaning use the default setting of ignore-times.
           Otherwise, if this function returns zero or non-zero, the returned value  overrides
           the setting of ignore-times for this file.  The argument is a hashref typically
           returned by File::RsyncP::FileList->get.  See the doPartial option in
           File::RsyncP->new().

   File delta receiving functions
       These functions are only called when we are receiving files.  They are called by the child
       process.

       fileDeltaRxStart($f, $cnt, $size, $remainder)
           Start the receiving of file deltas for file $f, a hashref typically returned by
           File::RsyncP::FileList->get.  The remaining arguments are the number of blocks, size
           of blocks, and size of the last (partial) block as generated by the parent on the
           receiving side (they are not the values the new file on the sending side).  Returns
           undef on success.

       fileDeltaRxNext($blk, $newData)
           This function is called repeatedly as the file is constructed.  Exactly one of $blk
           and $newData are defined.  If $blk is defined it is an integer that specifies which
           block of the original file should be written at this point.  If $newData is defined,
           it is literal data (that didn't match any blocks) that should be written at this
           point.

       fileDeltaRxDone($md4)
           Finish processing of the file deltas for this file.  $md4 is the MD4 digest of the
           sent file.  It should be compared against the MD4 digest of the reconstructed file.
           Returns undef on success, 1 if the file's MD4 didn't agree (meaning it should be
           repeated for phase 2), and negative on error.

   File list sending function
       fileListSend($fileList, $outputFunc)
           Generate the file list (by calling $fileList->encode for every file to be sent) and
           call the output function $outputFunc with the output data by calling

               &$outputFunc($fileList->encodeData);

AUTHOR

       File::RsyncP::FileList was written by Craig Barratt <cbarratt@users.sourceforge.net> based
       on rsync 2.5.5.

       Rsync was written by Andrew Tridgell <tridge@samba.org> and Paul Mackerras.  It is
       available under a GPL license.  See http://rsync.samba.org

LICENSE

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License in the LICENSE file
       along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple
       Place, Suite 330, Boston, MA 02111-1307 USA.

SEE ALSO

       See <http://perlrsync.sourceforge.net> for File::RsyncP's SourceForge home page.

       See File::RsyncP, File::RsyncP::Digest, and File::RsyncP::FileList.

       Also see BackupPC's lib/BackupPC/Xfer/RsyncFileIO.pm for an example of another
       implementation of File::RsyncP::FileIO, in fact one that is more tested than the default
       File::RsyncP::FileIO.pm.