NAME

Net::uFTP - Universal interface for FTP-like modules (FTP, SFTP, SCP), in most cases Net::FTP compatible.

SYNOPSIS

use Net::uFTP;

my $ftp = Net::uFTP->new('some.host.name', type => 'FTP', debug => 1);

$ftp->login('mylogin','mysecret')
  or die 'Incorrect password or login!';

$ftp->cwd("/pub")
  or die "Cannot change working directory ", $ftp->message;

$ftp->get("that.file")
  or die "get failed ", $ftp->message;

my $recurse = 1;
$ftp->get("that.dir", "this.path", $recurse)
  or die "get failed ", $ftp->message;

$ftp->quit;

DESCRIPTION

This module provides common interface (Net::FTP compatible) to popular FTP-like protocols (for now: FTP, SFTP, SCP). Flexibility of this module allows to add plugins to support other protocols (suggestions and plugins are welcome ;)

Currently Net::uFTP was successfuly tested for compatibility with Gtk2, Gtk2::GladeXML, Gtk2::GladeXML::OO and pragma encoding 'utf-8'. Other modules (some Pure Perl implementations) have problems with that. Consider this, when You're planning to build Gtk2 / multilingual application.

ATTENTION

Net::uFTP uses, for speed reason, Net::SSH2, so You have to have installed libssh (http://www.libssh2.org). Consider, that Net::SSH2 module is available on all most popular platforms (Linux, Windows, Mac, etc.), so You shouldn't have any trouble with this dependency.

If You are looking for Pure Perl implementation, take a look at Net::xFTP (based on Net::SSH::Perl) instead.

OVERVIEW

Rest of this documentation is based on Net::FTP documentation and describes subroutines/methods available in Net::uFTP.

Original version of this document (which describes Net::FTP) is avaliable at http://cpan.uwinnipeg.ca/htdocs/libnet/Net/FTP.html.

CONSTRUCTOR

new ( HOST, OPTIONS )

This is the constructor for a new Net::FTP object. HOST is the name of the remote host to which an FTP connection is required.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

Host - FTP host to connect to. The "host" method will return the value which was used to connect to the host.

debug - debug level (see the debug method in Net::Cmd)

type - type of connection. Possible values: FTP, SFTP, SCP. Default to FTP.

port - the port number to connect to on the remote machine.

If the constructor fails undef will be returned and an error message will be in $@

METHODS

Unless otherwise stated all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list.

login ([LOGIN [,PASSWORD [, ACCOUNT] ] ])

Log into the remote FTP server with the given login information.

ascii

Transfer file in ASCII. CRLF translation will be done if required

binary

Transfer file in binary mode. No transformation will be done.

Hint: If both server and client machines use the same line ending for text files, then it will be faster to transfer all files in binary mode.

rename ( OLDNAME, NEWNAME )

Rename a file on the remote FTP server from OLDNAME to NEWNAME. This is done by sending the RNFR and RNTO commands.

delete ( FILENAME )

Send a request to the server to delete FILENAME.

cwd ( [ DIR ] )

Attempt to change directory to the directory given in $dir. If $dir is "..", the FTP CDUP command is used to attempt to move up one directory. If no directory is given then an attempt is made to change the directory to the root directory.

cdup ()

Change directory to the parent of the current directory.

pwd ()

Returns the full pathname of the current directory.

rmdir ( DIR [, RECURSE ])

Remove the directory with the name DIR. If RECURSE is true then rmdir will attempt to delete everything inside the directory.

mkdir ( DIR [, RECURSE ])

Create a new directory with the name DIR. If RECURSE is true then mkdir will attempt to create all the directories in the given path.

Returns the full pathname to the new directory.

ls ( [ DIR ] )

Get a directory listing of DIR, or the current directory.

In an array context, returns a list of lines returned from the server. In a scalar context, returns a reference to a list.

dir ( [ DIR ] )

Get a directory listing of DIR, or the current directory in long format.

In an array context, returns a list of lines returned from the server. In a scalar context, returns a reference to a list.

get ( REMOTE_FILE [, LOCAL_FILE [, RECURSE ] ] )

Get REMOTE_FILE from the server and store locally. If not specified, the file will be stored in the current directory with the same leafname as the remote file. If RECURSE is true then get will attempt to get directory recursively.

Returns LOCAL_FILE, or the generated local file name if LOCAL_FILE is not given. If an error was encountered undef is returned.

put ( LOCAL_FILE [, REMOTE_FILE [, RECURSE ] ] )

Put a file on the remote server. LOCAL_FILE may be a regular file or a directory. If REMOTE_FILE is not specified then the file will be stored in the current directory with the same leafname as LOCAL_FILE. If RECURSE is true then get will attempt to put directory recursively.

Returns REMOTE_FILE, or the generated remote filename if REMOTE_FILE is not given.

NOTE: If for some reason the transfer does not complete and an error is returned then the contents that had been transfered will not be remove automatically.

mdtm ( FILE )

Returns the modification time of the given file.

size ( FILE )

Returns the size in bytes for the given file as stored on the remote server.

NOTE: The size reported is the size of the stored file on the remote server. If the file is subsequently transfered from the server in ASCII mode and the remote server and local machine have different ideas about "End Of Line" then the size of file on the local machine after transfer may be different.

If for some reason you want to have complete control over the data connection, then the user can use these methods to do so.

However calling these methods only affects the use of the methods above that can return a data connection. They have no effect on methods get, put, put_unique and those that do not require data connections.

port ( [ PORT ] )

Send a PORT command to the server. If PORT is specified then it is sent to the server. If not, then a listen socket is created and the correct information sent to the server.

pasv ()

Tell the server to go into passive mode. Returns the text that represents the port on which the server is listening, this text is in a suitable form to sent to another ftp server using the port method.

quit ()

Send the QUIT command to the remote FTP server and close the socket connection.

Net::uFTP provides also useful, not Net::FTP compatible methods, as follow:

is_dir ( REMOTE )

Returns true if REMOTE is a directory.

is_file ( REMOTE )

Returns true if REMOTE is a regular file.

change_root ( DIR )

Change root directory of current user. Only available in SFTP environment.

TODO

Add support for other methods from Net::FTP.

REPORTING BUGS

When reporting bugs/problems please include as much information as possible. It may be difficult for me to reproduce the problem as almost every setup is different.

A small script which yields the problem will probably be of help. It would also be useful if this script was run with the extra options debug = 1> passed to the constructor, and the output sent with the bug report. If you cannot include a small script then please include a debug trace from a run of your program which does yield the problem.

THANKS

Ryan Gorsuch for reaporting a bug as well as supplying relevant patch.

AUTHOR

Strzelecki £ukasz <lukasz@strzeleccy.eu>

SEE ALSO

Net::xFTP Net::FTP Net::SSH2

COPYRIGHT

Copyright (c) Strzelecki Łukasz. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Net::uFTP

perl -MCPAN -e shell
install Net::uFTP