@node Net/FTP, Net/NIS, Net/DummyInetd, Module List
@unnumbered FTP Client class


@unnumberedsec NAME

Net::FTP - FTP Client class

@unnumberedsec SYNOPSIS

@example
use Net::FTP;

$ftp = Net::FTP->new("some.host.name");
$ftp->login("anonymous","me@@here.there");
$ftp->cwd("/pub");
$ftp->get("that.file");
$ftp->quit;
@end example

@unnumberedsec DESCRIPTION

@code{Net::FTP} is a class implementing a simple FTP client in Perl as described
in RFC959

@code{Net::FTP} provides methods that will perform various operations. These methods
could be split into groups depending the level of interface the user requires.

@unnumberedsec CONSTRUCTOR

@table @asis
@item new (HOST [,OPTIONS])
This is the constructor for a new Net::SMTP object. @code{HOST} is the
name of the remote host to which a FTP connection is required.

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

@strong{Firewall} - The name of a machine which acts as a FTP firewall. This can be
overridden by an environment variable @code{FTP_FIREWALL}. If specified, and the
given host cannot be directly connected to, then the
connection is made to the firwall machine and the string @code{@@hostname} is
appended to the login identifier.

Port - The port number to connect to on the remote machine for the
FTP connection

@strong{Timeout} - Set a timeout value (defaults to 120)

Debug - Debug level

@strong{Passive} - If set to @emph{true} then all data transfers will be done using 
passive mode. This is required for some @emph{dumb} servers.

@end table
@unnumberedsec METHODS

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

@table @asis
@item login ([LOGIN [,PASSWORD [, ACCOUNT] ] ])
Log into the remote FTP server with the given login information. If
no arguments are given then the @code{Net::FTP} uses the @code{Net::Netrc}
package to lookup the login information for the connected host.
If no information is found then a login of @emph{anonymous} is used.
If no password is given and the login is @emph{anonymous} then the users
Email address will be used for a password.

If the connection is via a firewall then the authorize method will
be called with no arguments.

@item authorize ( [AUTH [, RESP]])
This is a protocol used by some firewall ftp proxies. It is used
to authorise the user to send data out.  If both arguments are not specified
then authorize uses @code{Net::Netrc} to do a lookup.

@item type (TYPE [, ARGS])
This method will send the TYPE command to the remote FTP server
to change the type of data transfer. The return value is the previous
value.

@item ascii ([ARGS]) binary([ARGS]) ebcdic([ARGS]) byte([ARGS])
Synonyms for type with the first arguments set correctly

NOTE ebcdic and byte are not fully supported.

@item rename ( OLDNAME, NEWNAME )
Rename a file on the remote FTP server from @code{OLDNAME} to @code{NEWNAME}. This
is done by sending the RNFR and RNTO commands.

@item delete ( FILENAME )
Send a request to the server to delete @code{FILENAME}.

@item cwd ( [ DIR ] )
Change the current working directory to DIR, or / if not given.

@item cdup ()
Change directory to the parent of the current directory.

@item pwd ()
Returns the full pathname of the current directory.

@item rmdir ( DIR )
Remove the directory with the name DIR.

@item mkdir ( DIR [, RECURSE ])
Create a new directory with the name DIR. If @code{RECURSE} is @emph{true} then
mkdir will attempt to create all the directories in the given path.

Returns the full pathname to the new directory.

@item ls ( [ DIR ] )
Get a directory listing of DIR, or the current directory.

Returns a reference to a list of lines returned from the server.

@item dir ( [ DIR ] )
Get a directory listing of DIR, or the current directory in long format.

Returns a reference to a list of lines returned from the server.

@item get ( REMOTE_FILE [, LOCAL_FILE ] )
Get @code{REMOTE_FILE} from the server and store locally. @code{LOCAL_FILE} may be
a filename or a filehandle. If not specified the the file will be stored in
the current directory with the same leafname as the remote file.

Returns @code{LOCAL_FILE}, or the generated local file name if @code{LOCAL_FILE}
is not given.

@item put ( LOCAL_FILE [, REMOTE_FILE ] )
Put a file on the remote server. @code{LOCAL_FILE} may be a name or a filehandle.
If @code{LOCAL_FILE} is a filehandle then @code{REMOTE_FILE} must be specified. If
@code{REMOTE_FILE} is not specified then the file will be stored in the current
directory with the same leafname as @code{LOCAL_FILE}.

Returns @code{REMOTE_FILE}, or the generated remote filename if @code{REMOTE_FILE}
is not given.

@item put_unique ( LOCAL_FILE [, REMOTE_FILE ] )
Same as put but uses the @code{STOU} command.

Returns the name of the file on the server.

@item append ( LOCAL_FILE [, REMOTE_FILE ] )
Same as put but appends to the file on the remote server.

Returns @code{REMOTE_FILE}, or the generated remote filename if @code{REMOTE_FILE}
is not given.

@item unique_name ()
Returns the name of the last file stored on the server using the
@code{STOU} command.

@item mdtm ( FILE )
Returns the @emph{modification time} of the given file

@item size ( FILE )
Returns the size in bytes for the given file.

@end table
The following methods can return different results depending on
how they are called. If the user explicitly calls either
of the pasv or port methods then these methods will
return a @emph{true} or @emph{false} value. If the user does not
call either of these methods then the result will be a
reference to a @code{Net::FTP::dataconn} based object.

@table @asis
@item nlst ( [ DIR ] )
Send a @code{NLST} command to the server, with an optional parameter.

@item list ( [ DIR ] )
Same as nlst but using the LIST command

@item retr ( FILE )
Begin the retrieval of a file called FILE from the remote server.

@item stor ( FILE )
Tell the server that you wish to store a file. FILE is the
name of the new file that should be created.

@item stou ( FILE )
Same as stor but using the @code{STOU} command. The name of the unique
file which was created on the server will be avalaliable via the unique_name
method after the data connection has been closed.

@item appe ( FILE )
Tell the server that we want to append some data to the end of a file
called FILE. If this file does not exist then create it.

@end table
If for some reason you want to have complete control over the data connection,
this includes generating it and calling the @code{response} method when required,
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.

@table @asis
@item port ( [ PORT ] )
Send a @code{PORT} command to the server. If @code{PORT} is specified then it is sent
to the server. If not the a listen socket is created and the correct information
sent to the server.

@item 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.

@end table
The following methods can be used to transfer files between two remote
servers, providing that these two servers can connect directly to each other.

@table @asis
@item pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )
This method will do a file transfer between two remote ftp servers. If
@code{DEST_FILE} is omitted then the leaf name of @code{SRC_FILE} will be used.

@item pasv_wait ( NON_PASV_SERVER )
This method can be used to wait for a transfer to complete between a passive
server and a non-passive server. The method should be called on the passive
server with the @code{Net::FTP} object for the non-passive server passed as an
argument.

@item abort ()
Abort the current data transfer.

@item quit ()
Send the QUIT command to the remote FTP server and close the socket connection.

@end table
@unnumberedsubsec Methods for the adventurous

@code{Net::FTP} inherits from @code{Net::Cmd} so methods defined in @code{Net::Cmd} may
be used to send commands to the remote FTP server.

@table @asis
@item quot (CMD [,ARGS])
Send a command, that Net::FTP does not directly support, to the remote
server and wait for a response.

Returns most significant digit of the response code.

WARNING This call should only be used on commands that do not require
data connections. Misuse of this method can hang the connection.

@end table
@unnumberedsec THE dataconn CLASS

Some of the methods defined in @code{Net::FTP} return an object which will
be derived from this class.The dataconn class itself is derived from
the IO::Socket::INET class, so any normal IO operations can be performed.
However the following methods are defined in the dataconn class and IO should
be performed using these.

@table @asis
@item read ( BUFFER, SIZE [, TIMEOUT ] )
Read @code{SIZE} bytes of data from the server and place it into @code{BUFFER}, also
performing any <CRLF> translation necessary. @code{TIMEOUT} is optional, if not
given the the timeout value from the command connection will be used.

Returns the number of bytes read before any <CRLF> translation.

@item write ( BUFFER, SIZE [, TIMEOUT ] )
Write @code{SIZE} bytes of data from @code{BUFFER} to the server, also
performing any <CRLF> translation necessary. @code{TIMEOUT} is optional, if not
given the the timeout value from the command connection will be used.

Returns the number of bytes written before any <CRLF> translation.

@item abort ()
Abort the current data transfer.

@item close ()
Close the data connection and get a response from the FTP server. Returns
@emph{true} if the connection was closed sucessfully and the first digit of
the response from the server was a @'2@'.

@end table
@unnumberedsec AUTHOR

Graham Barr <Graham.Barr@@tiuk.ti.com>

@unnumberedsec REVISION

$Revision: 2.8 $
$Date: 1996/09/05 06:53:58 $

The VERSION is derived from the revision by changing each number after the
first dot into a 2 digit number so

@example
Revision 1.8   => VERSION 1.08
Revision 1.2.3 => VERSION 1.0203
@end example

@unnumberedsec SEE ALSO

@xref{Net/Netrc,Net/Netrc},
@xref{Net/Cmd,Net/Cmd},

@unnumberedsec CREDITS

Henry Gabryjelski <henryg@@WPI.EDU> - for the suggestion of creating directories
recursively.

@unnumberedsec COPYRIGHT

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

