1File::RsyncP::FileIO(3)User Contributed Perl DocumentatioFnile::RsyncP::FileIO(3)
2
3
4

NAME

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

SYNOPSIS

9           use File::RsyncP::FileIO;
10
11           my $rs = File::RsyncP->new({
12                       logLevel   => 1,
13                       rsyncCmd => ["/bin/rsh", $host,  "-l", $user, "/bin/rsync"],
14                       rsyncArgs  => [qw(
15                               --numeric-ids
16                               --perms
17                               --owner
18                               --group
19                               --devices
20                               --links
21                               --ignore-times
22                               --block-size=700
23                               --relative
24                               --recursive
25                               -v
26                           )],
27                       logHandler => sub {
28                               my($str) = @_;
29                               print MyHandler "log: $str\n";
30                           };
31                       fio        => File::RsyncP::FileIO->new({
32                                       logLevel   => 1,
33                                   });
34
35                   });
36

DESCRIPTION

38       File::RsyncP::FileIO contains all of the file system access functions
39       needed by File::RsyncP.  This functionality is relegated to this module
40       so it can be subclassed or replaced by different code for applications
41       where an rsync interface is provided for non-file system data (eg:
42       databases).
43
44       File::RsyncP::FileIO provides the following functions.
45
46   Setup and utility functions
47       new({ options... })
48           Creates a new File::RsyncP::FileIO object.  The single argument is
49           a hashref of options:
50
51           blockSize
52               Defaults to 700.  Can be set later using the blockSize
53               function.
54
55           logLevel
56               Defaults to 0.  Controls the verbosity of FileIO operations.
57
58           digest
59               Defaults to File::RsyncP::Digest->new.  No need to override.
60
61           checksumSeed
62               The checksum seed used in digest calculations.  Defaults to 0.
63               The server-side Rsync generates a checksum seed and sends it to
64               the client.  This value is usually set later, after the
65               checksum seed is received from the remote rsync, via the
66               checksumSeed function.
67
68           logHandler
69               A subroutine reference to a function that handles all the log
70               messages.  The default is a subroutine that prints the messages
71               to STDERR.
72
73       blockSize($value)
74           Set the block size to the new value, in case it wasn't set via the
75           blockSize option to new().
76
77       checksumSeed($seed)
78           Set the checksum seed used in digest calculations to the new value.
79           Usually this value isn't known when new() is called, so it is
80           necessary to set it later via this function.
81
82       logHandlerSet
83           Set the log handler callback function.  Usually this value is
84           specified via new(), but it can be changed later via this function.
85
86       dirs($localDir, $remoteDir)
87           Specify the local and remote directories.
88
89       log(@msg)
90           Save one (or more) messages for logging purposes.
91
92       statsGet
93           Return an optional hashref of statistics compiled by the FileIO
94           object.  These values are opaquely passed up to File::RsyncP.
95
96       finish($isChild)
97           Do any necessary finish-up processing.  The $isChild argument is
98           true if this is the child process (remember the receiving side has
99           two processes: the child receives the file deltas while the parent
100           generates the block digests).
101
102   Checksum computation functions
103       csumStart($f, $needMD4)
104           Get ready to generate block checksums for the given file.  The
105           argument is a hashref typically returned by
106           File::RsyncP::FileList->get.  Typically this opens the underlying
107           file and creates a File::RsyncP::Digest object.  If $needMD4 is
108           non-zero, then csumEnd() will return the file MD4 digest.
109
110       csumGet($num, $csumLen, $blockSize)
111           Return $num bkocks work of checksums with the MD4 checksum length
112           of $csumLen (typically 2 or 16), with a block size of $blockSize.
113           Typically this reads the file and calls
114           File::RsyncP::Digest->blockDigest.
115
116       csumEnd()
117           Finish up the checksum calculation.  Typically closes the
118           underlying file.  Note that csumStart, csumGet, csumEnd are called
119           in strict order so they don't need to be reentrant (ie: there is
120           only one csum done at a time).  If csumStart() was called with
121           $needMD4 then csumEnd() will return the file MD4 digest.
122
123   File reading functions
124       There are used for sending files (currently sending files doesn't
125       implement deltas; it behaves as though --whole-file was specified):
126
127       readStart($f)
128           Get ready to read the given file.  The argument is a hashref
129           typically returned by File::RsyncP::FileList->get.  Typically this
130           opens the underlying file.
131
132       read($num)
133           Read $num bytes from the file.
134
135       readEnd()
136           Finish up the read operation.  Typically closes the underlying
137           file.  Note that readStart, readGet, readEnd are called in strict
138           order so they don't need to be reentrant (ie: there is only one
139           read done at a time).
140
141   File operations
142       attribGet($f)
143           Return the attributes for the given file as a hashref.  The
144           argument is a hashref typically returned by
145           File::RsyncP::FileList->get.
146
147       attribSet($f, $placeHolder)
148           Set the attributes for the given file.  The argument is a hashref
149           typically returned by File::RsyncP::FileList->get.  If $placeHolder
150           is true then don't do anything.  Returns undef on success.
151
152       makePath($f)
153           Create the directory specified by $f.  The argument is a hashref
154           typically returned by File::RsyncP::FileList->get.  Returns undef
155           on success.
156
157       makeSpecial($f)
158           Create the special file specified by $f.  The argument is a hashref
159           typically returned by File::RsyncP::FileList->get.  Returns undef
160           on success.
161
162       unlink($remotePath)
163           Unlink the file or directory corresponding to the given remote
164           path.
165
166       ignoreAttrOnFile($f)
167           Normally should return undef, meaning use the default setting of
168           ignore-times.  Otherwise, if this function returns zero or non-
169           zero, the returned value  overrides the setting of ignore-times for
170           this file.  The argument is a hashref typically returned by
171           File::RsyncP::FileList->get.  See the doPartial option in
172           File::RsyncP->new().
173
174   File delta receiving functions
175       These functions are only called when we are receiving files.  They are
176       called by the child process.
177
178       fileDeltaRxStart($f, $cnt, $size, $remainder)
179           Start the receiving of file deltas for file $f, a hashref typically
180           returned by File::RsyncP::FileList->get.  The remaining arguments
181           are the number of blocks, size of blocks, and size of the last
182           (partial) block as generated by the parent on the receiving side
183           (they are not the values the new file on the sending side).
184           Returns undef on success.
185
186       fileDeltaRxNext($blk, $newData)
187           This function is called repeatedly as the file is constructed.
188           Exactly one of $blk and $newData are defined.  If $blk is defined
189           it is an integer that specifies which block of the original file
190           should be written at this point.  If $newData is defined, it is
191           literal data (that didn't match any blocks) that should be written
192           at this point.
193
194       fileDeltaRxDone($md4)
195           Finish processing of the file deltas for this file.  $md4 is the
196           MD4 digest of the sent file.  It should be compared against the MD4
197           digest of the reconstructed file.  Returns undef on success, 1 if
198           the file's MD4 didn't agree (meaning it should be repeated for
199           phase 2), and negative on error.
200
201   File list sending function
202       fileListSend($fileList, $outputFunc)
203           Generate the file list (by calling $fileList->encode for every file
204           to be sent) and call the output function $outputFunc with the
205           output data by calling
206
207               &$outputFunc($fileList->encodeData);
208

AUTHOR

210       File::RsyncP::FileList was written by Craig Barratt
211       <cbarratt@users.sourceforge.net> based on rsync 2.5.5.
212
213       Rsync was written by Andrew Tridgell <tridge@samba.org> and Paul
214       Mackerras.  It is available under a GPL license.  See
215       http://rsync.samba.org
216

LICENSE

218       This program is free software; you can redistribute it and/or modify it
219       under the terms of the GNU General Public License as published by the
220       Free Software Foundation; either version 2 of the License, or (at your
221       option) any later version.
222
223       This program is distributed in the hope that it will be useful, but
224       WITHOUT ANY WARRANTY; without even the implied warranty of
225       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
226       General Public License for more details.
227
228       You should have received a copy of the GNU General Public License in
229       the LICENSE file along with this program; if not, write to the Free
230       Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
231       02111-1307 USA.
232

SEE ALSO

234       See <http://perlrsync.sourceforge.net> for File::RsyncP's SourceForge
235       home page.
236
237       See File::RsyncP, File::RsyncP::Digest, and File::RsyncP::FileList.
238
239       Also see BackupPC's lib/BackupPC/Xfer/RsyncFileIO.pm for an example of
240       another implementation of File::RsyncP::FileIO, in fact one that is
241       more tested than the default File::RsyncP::FileIO.pm.
242
243
244
245perl v5.32.0                      2020-09-29           File::RsyncP::FileIO(3)
Impressum