view release on metacpan or  search on metacpan

local/lib/perl5/Net/SFTP/Foreign.pm  view on Meta::CPAN

determines if access and modification time attributes have to be
copied from remote file. Default is to copy them.

=item copy_perm =E<gt> $bool

determines if permission attributes have to be copied from remote
file. Default is to copy them after applying the local process umask.

=item umask =E<gt> $umask

allows one to select the umask to apply when setting the permissions
of the copied file. Default is to use the umask for the current
process or C<0> if the C<perm> option is also used.

=item perm =E<gt> $perm

sets the permission mask of the file to be $perm, remote
permissions are ignored.

=item resume =E<gt> 1 | 'auto'

resumes an interrupted transfer.

If the C<auto> value is given, the transfer will be resumed only when
the local file is newer than the remote one.

C<get> transfers can not be resumed when a data conversion is in
place.

=item append =E<gt> 1

appends the contents of the remote file at the end of the local one
instead of overwriting it. If the local file does not exist a new one
is created.

=item overwrite =E<gt> 0

setting this option to zero cancels the transfer when a local file of
the same name already exists.

=item numbered =E<gt> 1

modifies the local file name inserting a sequence number when required
in order to avoid overwriting local files.

For instance:

  for (1..2) {
    $sftp->get("data.txt", "data.txt", numbered => 1);
  }

will copy the remote file as C<data.txt> the first time and as
C<data(1).txt> the second one.

If a scalar reference is passed as the numbered value, the final
target will be stored in the value pointed by the reference. For
instance:

  my $target;
  $sftp->get("data.txt", "data.txt", numbered => \$target);
  say "file was saved as $target" unless $sftp->error

=item atomic =E<gt> 1

The remote file contents are transferred into a temporal file that
once the copy completes is renamed to the target destination.

If not-overwrite of remote files is also requested, an empty file may
appear at the target destination before the rename operation is
performed. This is due to limitations of some operating/file systems.

=item mkpath =E<gt> 0

By default the method creates any non-existent parent directory for
the given target path. That feature can be disabled setting this flag
to 0.

=item cleanup =E<gt> 1

If the transfer fails, remove the incomplete file.

This option is set to by default when there is not possible to resume
the transfer afterwards (i.e., when using `atomic` or `numbered`
options).

=item best_effort =E<gt> 1

Ignore minor errors as setting time or permissions.

=item conversion =E<gt> $conversion

on the fly data conversion of the file contents can be performed with
this option. See L</On the fly data conversion> below.

=item callback =E<gt> $callback

C<$callback> is a reference to a subroutine that will be called after
every iteration of the download process.

The callback function will receive as arguments: the current
Net::SFTP::Foreign object; the data read from the remote file; the
offset from the beginning of the file in bytes; and the total size of
the file in bytes.

This mechanism can be used to provide status messages, download
progress meters, etc.:

    sub callback {
        my($sftp, $data, $offset, $size) = @_;
        print "Read $offset / $size bytes\r";
    }

The C<abort> method can be called from inside the callback to abort
the transfer:

    sub callback {
        my($sftp, $data, $offset, $size) = @_;
        if (want_to_abort_transfer()) {
            $sftp->abort("You wanted to abort the transfer");
        }
    }