File::R...:FileIO(3)

🎀 NAME 🎀

Okay so this whole page is the manual for File::RsyncP::FileIO (you'll see it filed under File::R...:FileIO(3) in the User Contributed Perl Documentation, no cap) — it's the Perl Rsync client file system IO module. Bestie, it's giving "the plumbing behind the magic." Let's get into it. ✨

---

🦋 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 is where all the file system access functions that File::RsyncP needs actually live. Why is it its own module? Because the vibes demanded it: this way the whole thing can be subclassed or swapped out for different code when your app is doing rsync over something that isn't a file system — databases, for instance. Very demure, very modular. 👑

So here's the full roster of what File::RsyncP::FileIO gives you. 🫶

🧰 Setup and utility functions 🧰

• new({ options... }) — makes you a brand new File::RsyncP::FileIO object. There's exactly one argument, and it's a hashref of options, which are:
  • blockSize — defaults to 700. You can totally change it later with the blockSize function. ✨
  • logLevel — defaults to 0. This one controls how chatty the FileIO operations get. 🔇
  • digest — defaults to File::RsyncP::Digest->new. You literally never need to override this, bestie. Leave it. 🙈
  • checksumSeed — the checksum seed used in digest calculations, defaulting to 0. So here's the tea: the server-side Rsync generates a checksum seed and sends it over to the client. Which means this value usually gets set later, after the checksum seed arrives from the remote rsync, using the checksumSeed function. 🌱
  • logHandler — a subroutine reference to a function that handles all the log messages. The default is a sub that just prints the messages to STDERR. 📢
• blockSize($value) — sets the block size to this new value, for when you didn't already set it through the blockSize option in new(). 🔧
• checksumSeed($seed) — sets the checksum seed used in digest calculations to the new value. Usually you don't know this value yet when new() is called, so yeah, you'll be setting it later through this function. Timing is everything. ⏰
• logHandlerSet — sets the log handler callback function. Normally you'd pass this in via new(), but it can be changed later with this function if you're feeling spontaneous. 🎀
• dirs($localDir, $remoteDir) — tells it the local directory and the remote directory. Two dirs, one function. 🗂️
• log(@msg) — saves one (or more) messages for logging purposes. 📝
• statsGet — returns an optional hashref of statistics that the FileIO object compiled. Those values get passed opaquely up to File::RsyncP. Very mysterious, very opaque. 💫
• finish($isChild) — does whatever finish-up processing is needed. The $isChild argument is true when this is the child process — and remember, bestie, the receiving side runs two processes: the child receives the file deltas, while the parent generates the block digests. 👯

🧮 Checksum computation functions 🧮

• csumStart($f, $needMD4) — gets ready to generate block checksums for the given file. The argument is a hashref, typically the one returned by File::RsyncP::FileList->get. Typically this opens the underlying file and creates a File::RsyncP::Digest object. And if $needMD4 is non-zero, then csumEnd() will hand you back the file MD4 digest. 🔐
• csumGet($num, $csumLen, $blockSize) — returns $num blocks' worth of checksums, with the MD4 checksum length set to $csumLen (typically 2 or 16), using a block size of $blockSize. Typically it reads the file and calls File::RsyncP::Digest->blockDigest. 📖
• csumEnd() — finishes up the checksum calculation, and typically closes the underlying file. Heads up: csumStart, csumGet, csumEnd are called in strict order, so they don't need to be reentrant (i.e. only one csum is happening at a time). And if csumStart() was called with $needMD4, then csumEnd() returns the file MD4 digest. 🏁

📚 File reading functions 📚

These get used for sending files — and quick note, sending files currently does not implement deltas; it behaves as though --whole-file was specified. 🗒️

• readStart($f) — gets ready to read the given file. The argument is a hashref, typically the one returned by File::RsyncP::FileList->get. Typically this opens the underlying file. 🔓
• read($num) — reads $num bytes from the file. 📥
• readEnd() — finishes up the read operation, and typically closes the underlying file. Same deal as the checksums: readStart, readGet, readEnd are called in strict order, so no reentrancy needed (only one read at a time, periodt). 🛑

🗃️ File operations 🗃️

• attribGet($f) — returns the attributes for the given file as a hashref. The argument is a hashref, typically the one returned by File::RsyncP::FileList->get. 🔍
• attribSet($f, $placeHolder) — sets the attributes for the given file. The argument is a hashref, typically the one returned by File::RsyncP::FileList->get. If $placeHolder is true, then don't do anything at all. Returns undef on success. ✅
• makePath($f) — creates the directory that $f specifies. The argument is a hashref, typically the one returned by File::RsyncP::FileList->get. Returns undef on success. 📁
• makeSpecial($f) — creates the special file that $f specifies. The argument is a hashref, typically the one returned by File::RsyncP::FileList->get. Returns undef on success. ⭐
• unlink($remotePath) — unlinks the file or directory matching that given remote path. ✂️
• ignoreAttrOnFile($f) — normally this should return undef, which means "use the default setting of ignore-times." Otherwise, if this function returns zero or non-zero, whatever it returns overrides the ignore-times setting for this particular file. The argument is a hashref, typically the one returned by File::RsyncP::FileList->get. Peep the doPartial option in File::RsyncP->new() for more. 👀

📥 File delta receiving functions 📥

These functions only get called when we're receiving files. They're called by the child process. 👶

• fileDeltaRxStart($f, $cnt, $size, $remainder) — starts 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, the size of blocks, and the size of the last (partial) block as generated by the parent on the receiving side — so careful, they are not the values of the new file on the sending side. Returns undef on success. 🚀
• fileDeltaRxNext($blk, $newData) — called over and over as the file gets constructed. Exactly one of $blk and $newData is defined. If $blk is defined, it's an integer saying which block of the original file should be written at this point. If $newData is defined, it's literal data — stuff that didn't match any blocks — that should be written at this point. 🧩
• fileDeltaRxDone($md4) — finishes processing the file deltas for this file. $md4 is the MD4 digest of the sent file, and you should compare it 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 a negative value on error. 😤

📤 File list sending function 📤

• fileListSend($fileList, $outputFunc) — generates the file list (by calling $fileList->encode for every file to be sent) and calls the output function $outputFunc with the output data, like this:

&$outputFunc($fileList->encodeData);

---

🌟 AUTHOR 🌟

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

Rsync was written by Andrew Tridgell <tridge@samba.org> and Paul Mackerras. It's available under a GPL license — go look at <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 peep BackupPC's lib/BackupPC/Xfer/RsyncFileIO.pm for an example of another implementation of File::RsyncP::FileIO — and honestly, it's one that's more tested than the default File::RsyncP::FileIO.pm. 🔥

---

That's the whole page, bestie, no skips. ✨ Signing off from perl v5.42.0, dated 2025-07-25, filed under File::R...:FileIO(3) — mwah, slay, go read your file lists. 💅🎀