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.