NAME¶
File::Rsync - perl module interface to
rsync(1)
http://rsync.samba.org/rsync/
SYNOPSIS¶
use File::Rsync;
$obj = File::Rsync->new( { archive => 1, compress => 1,
rsh => '/usr/local/bin/ssh',
'rsync-path' => '/usr/local/bin/rsync' } );
$obj->exec( { src => 'localdir', dest => 'rhost:remdir' } )
or warn "rsync failed\n";
DESCRIPTION¶
Perl Convenience wrapper for the
rsync(1) program. Written for
rsync-2.3.2 and updated for
rsync-2.6.0 but should perform
properly with most recent versions.
- File::Rsync::new
- $obj = new File::Rsync;
or
$obj = File::Rsync-> new;
or
$obj = File::Rsync->new(@options);
or
$obj = File::Rsync->new(\%options);
Create a File::Rsync object. Any options passed at creation are
stored in the object as defaults for all future exec calls on that
object. Options may be passed in the form of a hash and are the same as
the long options in rsync(1) with the leading
double-dash removed. An additional option of path-to-rsync also
exists which can be used to override the hardcoded path to the rsync
binary that is defined when the module is installed, and debug
which causes the module methods to print some debugging information to
STDERR. There are also 2 options to wrap the source and/or destination
paths in double-quotes. They are quote-src and quote-dest,
and may be useful in protecting the paths from shell expansion
(particularly useful for paths containing spaces). The outfun and
errfun options take a function reference. The function is called
once for each line of output from the rsync program with the output
line passed in as the first argument, the second arg is either 'out' or
'err' depending on the source. This makes it possible to use the same
function for both and still determine where the output came from. Options
may also be passed as a reference to a hash. The exclude option
needs an array reference as its value, since there cannot be duplicate
keys in a hash. There is an equivalent include option. Only an
exclude or include option should be used, not both. Use the
'+ ' or '- ' prefix trick to put includes in an exclude array, or
to put excludes in an include array (see
rsync(1) for details). Include/exclude options form
an ordered list. The order must be retained for proper execution. There
are also source and dest keys. The key src is also
accepted as an equivalent to source, and dst or
destination may be used as equivalents to dest. The
source option may take a scalar or an array reference. If the
source is the local system then multiple source paths are allowed.
In this case an array reference should be used. There is also a method for
passing multiple source paths to a remote system. This method may be
triggered in this module by passing the remote hostname to the
srchost key and passing an array reference to the source
key. If the source host is being accessed via an Rsync server, the remote
hostname should have a single trailing colon on the name. When rsync is
called, the srchost value and the values in the source array
will be joined with a colon resulting in the double-colon required for
server access. The dest key only takes a scalar since rsync
only accepts a single destination path.
Version 2.6.0 of rsync(1) provides a new
files-from option along with a few other supporting options (
from0, no-relative, and no-implied-dirs). To support
this wonderful new option at the level it deserves, this module now has an
additional parameter. If files-from is set to '-' (meaning read
from stdin) you can define infun to be a reference to a function
that prints your file list to the default file handle. The output from the
function is attached to stdin of the rsync call during exec. If
infun is defined it will be called regardless of the value of
files-from, so it can provide any data expected on stdin, but keep
in mind that stdin will not be attached to a tty so it is not very useful
for sending passwords (see the rsync(1) and
ssh(1) man pages for ways to handle authentication).
The rsync(1) man page has a more complete description
of files-from. Also see File::Find for ideas to use with
files-from and infun. The infun option may also be
used with the include-from or exclude-from settings, but
this is generally more clumsy than using the include or
exclude arrays.
Version 2.6.3 of rsync(1) provides new options
partial-dir, checksum-seed, keep-dirlinks,
inplace, ipv4, and ipv6. Version 2.6.4 of
rsync (1) provides new options del,
delete-before delete-during, delay-updates,
dirs, filter, fuzzy, itemize-changes,
list-only, omit-dir-times, remove-sent-files,
max-size, and protocol.
Version 0.38 of this module also adds support for the acls option
that is not part of rsync(1) unless the patch has
been applied, but people do use it. It also includes a new literal
option that takes an array reference similar to include,
exclude, and filter. Any arguments in the array are passed
as literal arguments to rsync, and are passed first. They should have the
proper single or double hyphen prefixes and the elements should be split
up the way you want them passed to exec. The purpose of this option is to
allow the use of arbitrary options added by patches, and/or to allow the
use of new options in rsync without needing an imediate update to the
module in addtition to rsync(1) itself.
- File::Rsync::defopts
- $obj->defopts(@options);
or
$obj->defopts(\%options);
Set default options for future exec calls for the object. See
rsync (1) for a complete list of valid options. This
is really the internal method that new calls but you can use it
too. The verbose and quiet options to rsync are actually
counters. When assigning the perl hash-style options you may specify the
counter value directly and the module will pass the proper number of
options to rsync.
- File::Rsync::getcmd
- my $cmd = $obj->getcmd(@options);
or
my $cmd = $obj->getcmd(\%options);
or
my ($cmd, $infun, $outfun, $errfun, $debug) = $obj->getcmd(\%options);
getcmd returns a reference to an array containing the real rsync
command that would be called if the exec function were called. The last
example above includes a reference to the optional stdin function, stdout
function, stderr function, and the debug setting. This is the form used by
the exec method to get the extra parameters it needs to do its job.
The function is exposed to allow a user-defined exec function to be used,
or for debugging purposes.
- File::Rsync::exec
- $obj->exec(@options) or warn "rsync failed\n";
or
$obj->exec(\%options) or warn "rsync failed\n";
This is the method that does the real work. Any options passed to this
routine are appended to any pre-set options and are not saved. They effect
the current execution of rsync only. In the case of conflicts, the
options passed directly to exec take precedence. It returns
1 if the return status was zero (or true), if the rsync
return status was non-zero it returns 0 and stores the return
status. You can examine the return status from rsync and any output
to stdout and stderr with the methods listed below.
- File::Rsync::list
- $out = $obj->list(@options);
or
$out = $obj->list(\%options);
or
@out = $obj->list(\%options);
This is a wrapper for exec called without a destination to get a
listing. It returns the output of stdout like the out function
below. When no destination is given rsync returns the equivalent of 'ls
-l' or 'ls -lr' modified by any include/exclude/filter parameters you
specify. This is useful for manual comparison without actual changes to
the destination or for comparing against another listing taken at a
different point in time.
(As of rsync version 2.6.4-pre1 this can also be accomplished with the
'list-only' option regardless of whether a destination is given.)
- File::Rsync::status
- $rval = $obj->status;
Returns the status from last exec call right shifted 8 bits.
- File::Rsync::realstatus
- $rval = $obj->realstatus;
Returns the real status from last exec call (not right shifted).
- File::Rsync::err
- $aref = $obj->err;
In a scalar context this method will return a reference to an array
containing all output to stderr from the last exec call, or zero
(false) if there was no output. In an array context it will return an
array of all output to stderr or an empty list. The scalar context can be
used to efficiently test for the existance of output. rsync sends
all messages from the remote rsync process and any error messages
to stderr. This method's purpose is to make it easier for you to parse
that output for appropriate information.
- File::Rsync::out
- $aref = $obj->out;
Similar to the err method, in a scalar context it returns a reference
to an array containing all output to stdout from the last exec
call, or zero (false) if there was no output. In an array context it
returns an array of all output to stdout or an empty list. rsync
sends all informational messages ( verbose option) from the local
rsync process to stdout.
- File::Rsync::lastcmd
- $aref = $obj->lastcmd;
Returns the actual system command used by the last exec call, or ''
before any calls to exec for the object. This can be useful in the
case of an error condition to give a more informative message or for
debugging purposes. In an array context it return an array of args as
passed to the system, in a scalar context it returns a space-seperated
string. See getcmd for access to the command before execution.
Author¶
Lee Eakin <leakin@dfw.nostrum.com>
Credits¶
The following people have contributed ideas, bug fixes, code or helped out by
reporting or tracking down bugs in order to improve this module since it's
initial release. See the Changelog for details:
Greg Ward
Boris Goldowsky
James Mello
Andreas Koenig
Joe Smith
Jonathan Pelletier
Heiko Jansen
Tong Zhu
Paul Egan
Ronald J Kimball
James CE Johnson
Bill Uhl
Peter teStrake
Harald Flaucher
Simon Myers
Inspiration and Assistance¶
Gerard Hickey "PGP::Pipe"
Russ Allbery "PGP::Sign"
Graham Barr "Net::*"
Andrew Tridgell and Paul Mackerras
rsync(1)
John Steele <steele@nostrum.com>
Philip Kizer <pckizer@nostrum.com>
Larry Wall
perl(1)
I borrowed many clues on wrapping an external program from the PGP modules, and
I would not have had such a useful tool to wrap except for the great work of
the
rsync authors. Thanks also to Graham Barr, the author of the libnet
modules and many others, for looking over this code. Of course I must mention
the other half of my brain, John Steele, and his good friend Philip Kizer for
finding
rsync and bringing it to my attention. And I would not have
been able to enjoy writing useful tools if not for the creator of the
perl language.
Copyrights¶
Copyright (c) 1999-2005 Lee Eakin. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.