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... })
48 Creates a new File::RsyncP::FileIO object. The single argument is
49 a hashref of options:
50 blockSize
52 Defaults to 700. Can be set later using the blockSize
53 function.
54 logLevel
56 Defaults to 0. Controls the verbosity of FileIO operations.
57 digest
59 Defaults to File::RsyncP::Digest->new. No need to override.
60 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 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 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 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 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 dirs($localDir, $remoteDir)
87 Specify the local and remote directories.
88 log(@msg)
90 Save one (or more) messages for logging purposes.
91 statsGet
93 Return an optional hashref of statistics compiled by the FileIO
94 object. These values are opaquely passed up to File::RsyncP.
95 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 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 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 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 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 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 read($num)
133 Read $num bytes from the file.
134 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 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 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 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 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 unlink($remotePath)
163 Unlink the file or directory corresponding to the given remote
164 path.
165 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 File delta receiving functions
175 These functions are only called when we are receiving files. They are
176 called by the child process.
177 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 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 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 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 &$outputFunc($fileList->encodeData);
208
210 File::RsyncP::FileList was written by Craig Barratt
211 <cbarratt@users.sourceforge.net> based on rsync 2.5.5.
212 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
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 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 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
234 See <http://perlrsync.sourceforge.net> for File::RsyncP's SourceForge
235 home page.
236 See File::RsyncP, File::RsyncP::Digest, and File::RsyncP::FileList.
238 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.
242perl v5.32.0 2020-09-29 File::RsyncP::FileIO(3)