1File::RsyncP::FileIO(3)User Contributed Perl DocumentatioFnile::RsyncP::FileIO(3)
2
6 File::RsyncP::FileIO - Perl Rsync client file system IO
7
9 use File::RsyncP::FileIO;
10 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 });
36
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 File::RsyncP::FileIO provides the following functions.
45 Setup and utility functions
47 new({ options... })
49 Creates a new File::RsyncP::FileIO object. The single argument is
50 a hashref of options:
51 blockSize
53 Defaults to 700. Can be set later using the blockSize func‐
54 tion.
55 logLevel
57 Defaults to 0. Controls the verbosity of FileIO operations.
58 digest
60 Defaults to File::RsyncP::Digest->new. No need to override.
61 checksumSeed
63 The checksum seed used in digest calculations. Defaults to 0.
64 The server-side Rsync generates a checksum seed and sends it to
65 the client. This value is usually set later, after the check‐
66 sum seed is received from the remote rsync, via the checksum‐
67 Seed function.
68 logHandler
70 A subroutine reference to a function that handles all the log
71 messages. The default is a subroutine that prints the messages
72 to STDERR.
73 blockSize($value)
75 Set the block size to the new value, in case it wasn't set via the
76 blockSize option to new().
77 checksumSeed($seed)
79 Set the checksum seed used in digest calculations to the new value.
80 Usually this value isn't known when new() is called, so it is nec‐
81 essary to set it later via this function.
82 logHandlerSet
84 Set the log handler callback function. Usually this value is spec‐
85 ified via new(), but it can be changed later via this function.
86 dirs($localDir, $remoteDir)
88 Specify the local and remote directories.
89 log(@msg)
91 Save one (or more) messages for logging purposes.
92 statsGet
94 Return an optional hashref of statistics compiled by the FileIO
95 object. These values are opaquely passed up to File::RsyncP.
96 finish($isChild)
98 Do any necessary finish-up processing. The $isChild argument is
99 true if this is the child process (remember the receiving side has
100 two processes: the child receives the file deltas while the parent
101 generates the block digests).
102 Checksum computation functions
104 csumStart($f, $needMD4)
106 Get ready to generate block checksums for the given file. The
107 argument is a hashref typically returned by
108 File::RsyncP::FileList->get. Typically this opens the underlying
109 file and creates a File::RsyncP::Digest object. If $needMD4 is
110 non-zero, then csumEnd() will return the file MD4 digest.
111 csumGet($num, $csumLen, $blockSize)
113 Return $num bkocks work of checksums with the MD4 checksum length
114 of $csumLen (typically 2 or 16), with a block size of $blockSize.
115 Typically this reads the file and calls
116 File::RsyncP::Digest->blockDigest.
117 csumEnd()
119 Finish up the checksum calculation. Typically closes the underly‐
120 ing file. Note that csumStart, csumGet, csumEnd are called in
121 strict order so they don't need to be reentrant (ie: there is only
122 one csum done at a time). If csumStart() was called with $needMD4
123 then csumEnd() will return the file MD4 digest.
124 File reading functions
126 There are used for sending files (currently sending files doesn't
128 implement deltas; it behaves as though --whole-file was specified):
129 readStart($f)
131 Get ready to read the given file. The argument is a hashref typi‐
132 cally returned by File::RsyncP::FileList->get. Typically this
133 opens the underlying file.
134 read($num)
136 Read $num bytes from the file.
137 readEnd()
139 Finish up the read operation. Typically closes the underlying
140 file. Note that readStart, readGet, readEnd are called in strict
141 order so they don't need to be reentrant (ie: there is only one
142 read done at a time).
143 File operations
145 attribGet($f)
147 Return the attributes for the given file as a hashref. The argu‐
148 ment is a hashref typically returned by
149 File::RsyncP::FileList->get.
150 attribSet($f, $placeHolder)
152 Set the attributes for the given file. The argument is a hashref
153 typically returned by File::RsyncP::FileList->get. If $placeHolder
154 is true then don't do anything. Returns undef on success.
155 makePath($f)
157 Create the directory specified by $f. The argument is a hashref
158 typically returned by File::RsyncP::FileList->get. Returns undef
159 on success.
160 makeSpecial($f)
162 Create the special file specified by $f. The argument is a hashref
163 typically returned by File::RsyncP::FileList->get. Returns undef
164 on success.
165 unlink($remotePath)
167 Unlink the file or directory corresponding to the given remote
168 path.
169 ignoreAttrOnFile($f)
171 Normally should return undef, meaning use the default setting of
172 ignore-times. Otherwise, if this function returns zero or
173 non-zero, the returned value overrides the setting of ignore-times
174 for this file. The argument is a hashref typically returned by
175 File::RsyncP::FileList->get. See the doPartial option in
176 File::RsyncP->new().
177 File delta receiving functions
179 These functions are only called when we are receiving files. They are
181 called by the child process.
182 fileDeltaRxStart($f, $cnt, $size, $remainder)
184 Start the receiving of file deltas for file $f, a hashref typically
185 returned by File::RsyncP::FileList->get. The remaining arguments
186 are the number of blocks, size of blocks, and size of the last
187 (partial) block as generated by the parent on the receiving side
188 (they are not the values the new file on the sending side).
189 Returns undef on success.
190 fileDeltaRxNext($blk, $newData)
192 This function is called repeatedly as the file is constructed.
193 Exactly one of $blk and $newData are defined. If $blk is defined
194 it is an integer that specifies which block of the original file
195 should be written at this point. If $newData is defined, it is
196 literal data (that didn't match any blocks) that should be written
197 at this point.
198 fileDeltaRxDone($md4)
200 Finish processing of the file deltas for this file. $md4 is the
201 MD4 digest of the sent file. It should be compared against the MD4
202 digest of the reconstructed file. Returns undef on success, 1 if
203 the file's MD4 didn't agree (meaning it should be repeated for
204 phase 2), and negative on error.
205 File list sending function
207 fileListSend($fileList, $outputFunc)
209 Generate the file list (by calling $fileList->encode for every file
210 to be sent) and call the output function $outputFunc with the out‐
211 put data by calling
212 &$outputFunc($fileList->encodeData);
214
216 File::RsyncP::FileList was written by Craig Barratt <cbar‐
217 ratt@users.sourceforge.net> based on rsync 2.5.5.
218 Rsync was written by Andrew Tridgell <tridge@samba.org> and Paul Mack‐
220 erras. It is available under a GPL license. See
221 http://rsync.samba.org
222
224 This program is free software; you can redistribute it and/or modify it
225 under the terms of the GNU General Public License as published by the
226 Free Software Foundation; either version 2 of the License, or (at your
227 option) any later version.
228 This program is distributed in the hope that it will be useful, but
230 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
231 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
232 Public License for more details.
233 You should have received a copy of the GNU General Public License in
235 the LICENSE file along with this program; if not, write to the Free
236 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
237 02111-1307 USA.
238
240 See <http://perlrsync.sourceforge.net> for File::RsyncP's SourceForge
241 home page.
242 See File::RsyncP, File::RsyncP::Digest, and File::RsyncP::FileList.
244 Also see BackupPC's lib/BackupPC/Xfer/RsyncFileIO.pm for an example of
246 another implementation of File::RsyncP::FileIO, in fact one that is
247 more tested than the default File::RsyncP::FileIO.pm.
248perl v5.8.8 2006-11-19 File::RsyncP::FileIO(3)