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.