The Allegro FTP client module (original) (raw)

1.0 Introduction

The Allegro FTP client module can be used to communicate with an FTP server, including Allegro FTPd (http://github.com/franzinc/aftpd/). Symbols defining operators, classes, and variables in the FTP client module are in the net.ftp.client package.

The Allegro FTP client module can do the following:

Loading the ftp module

Load the ftp module by evaluating the following require form:

(require :ftp)

Symbols naming functionality in the ftp module are in the net.ftp.client package.

The following operators and variables are supported.

All operators are functions unless otherwise indicated.

Operators that open an FTP connection

Operators that act on an open FTP connection

Other operators

The function ftp-date-string-to-ut supported in earlier versions is no longer supported. since it is no longer necessary. map-over-ftp-directory passes the already converted date in universal time format to the map function.

Variables

Classes

connect-to-ftp-server

function, package: net.ftp.client

Arguments: host &key user password port

connect-to-ftp-server creates and returns a stream connected to an FTP server on host and port, using user and password to authenticate the session. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

If port is not given then it defaults to the ftp service port.

As with any Lisp stream, the connection can be closed with close, with the FTP stream as its argument.

If an error occurs while establishing the connection the stream is closed and an error of type failed-connection is signaled.

open-ftp-stream

function, package: net.ftp.client

Arguments: file &key (host "localhost") port (user *default-user*) (password *default-password*) (direction :input) (mode :binary) (passive t)

open-ftp-stream opens and returns a stream to or from a file on a remote host.

The name of the host is host using port port. user and password are used for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

direction is either :input, the default, :output or :directory. A direction value of :directory causes the return of an input stream containing a directory listing.

host and port default to localhost and the ftp service port.

mode can be either :binary, the default, or :text. Note that in :text mode lines end with CRLF (Carriage-Return Linefeed, the standard on the Internet).

passive, if non-`nil, the default, causes passive mode transfers to occur, which is useful to get through some IP filters and firewalls.

As with any Lisp stream, the connection can be closed with close, with the FTP stream as its argument.

See also connect-to-ftp-server and with-open-ftp-connection.

with-open-ftp-connection

macro, package: net.ftp.client

Arguments: (var host &key port (user *default-user*) (password *default-password*) &body body

with-open-ftp-connection establishes a connection to an FTP server on host and port, using user and password to authenticate the session. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

The stream bound to var is closed after body is evaluated, and the value returned is that returned by body.

See the documentation for connect-to-ftp-server for more information on host, port, user and password.

The value of opening a connection to an FTP server using this macro is that multiple commands can be sent to the same server without having to close and reopen the connection. When using a heavily used FTP server it might be quite difficult to make a connection, so having to reestablish it might not be a good idea.

Functions in this package whose names start with ``ftp-stream-'' operate on open FTP sessions.

The definition is equivalent to:

(defmacro with-open-ftp-connection ((var host
                                     &key port
                                          (user *default-user*)
                                          (password *default-password*))
                                    &body body)
  `(with-open-stream (,var (connect-to-ftp-server ,host
                                                  :user ,user
                                                  :password ,password
                                                  :port ,port))
     ,@body))

ftp-transfer-file

function, package: net.ftp.client

Arguments: &key from-host from-port from-file (from-user *default-user*) (from-password *default-password*) to-host to-port to-file (to-user *default-user*) (to-password *default-password*)

ftp-transfer-file transfers from-file on host from-host to the file named to-file on host to-host. from-port and to-port are used to change the default ports for FTP connections.

from-user and to-user, and from-password and to-password, are used to set authentication for each connection. All must be strings. The default values of both *-user and *-password keywords are the values of *default-user* and *default-password*. Unless the username and password are the same on both hosts, values must be specified for at least one pair.

mode can be either :binary, the default, or :text. Note that in :text mode lines end with CRLF (Carriage-Return Linefeed, the standard on the Internet).

The files on each host can have different names.

Note that the host on which this is executed can be different than either the from-host or to-host, making for a 3-host FTP file transfer.

ftp-get

function, package: net.ftp.client

Arguments: host remote-path local-filespec &key port (if-exists :error) (user *default-user*) (password *default-password*) (mode :binary)

ftp-get retrieves a file from a remote host into a local file. The connection is made to host and port using user and password for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

If port is not given then it defaults to the ftp service port.

remote-path is relative to the current directory in effect on the remote host.

local-filespec is the destination for the retrieval.

mode can be either :binary, the default, or :text. Note that in :text mode lines end with CRLF (Carriage-Return Linefeed, the standard on the Internet).

On success t is returned. See also ftp-stream-get.

ftp-stream-get

function, package: net.ftp.client

Arguments: ftps remote-path local-filespec &key (if-exists :error) (mode :binary)

ftp-stream-get retrieves a file from a remote host into a local file. This function is similar to ftp-get, except that it uses an already open FTP connection (see with-open-ftp-connection or connect-to-ftp-server) given by ftps.

remote-path, local-filespec, if-exists and mode have the same meaning as for ftp-get.

On success t is returned.

ftp-put

function, package: net.ftp.client

Arguments: host local-filespec remote-path &key port (user *default-user*) (password *default-password*) (mode :binary)

ftp-put copies a local file to a remote host. The connection is made to host and port using user and password for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

If port is not given then it defaults to the ftp service port.

remote-path is relative to the current directory in effect on the remote host.

mode can be either :binary, the default, or :text. Note that in :text mode lines end with CRLF (Carriage-Return Linefeed, the standard on the Internet).

On success t is returned. See also ftp-stream-put.

ftp-stream-put

function, package: net.ftp.client

Arguments: ftps local-filespec remote-path &key (mode :binary)

ftp-stream-put copies a local file to a remote host. This function is similar to ftp-put, except that it uses an already open FTP connection (see with-open-ftp-connection or connect-to-ftp-server) given by ftps.

remote-path, local-filespec and mode have the same meaning as for ftp-put.

On success t is returned.

ftp-append

function, package: net.ftp.client

Arguments: host local-filespec remote-path &key port (user *default-user*) (password *default-password*) (mode :binary)

ftp-append appends a local file to a file on a remote host. The connection is made to host and port using user and password for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

If port is not given then it defaults to the ftp service port.

remote-path is relative to the current directory in effect on the remote host.

mode can be either :binary, the default, or :text. Note that in :text mode lines end with CRLF (Carriage-Return Linefeed, the standard on the Internet).

On success t is returned. See also ftp-stream-append.

ftp-stream-append

function, package: net.ftp.client

Arguments: ftps local-filespec remote-path &key (mode :binary)

ftp-stream-append appends a local file to a file on a remote host. This function is similar to ftp-append, except that it uses an already open FTP connection (see with-open-ftp-connection or connect-to-ftp-server) given by ftps.

remote-path, local-filespec and mode have the same meaning as for ftp-append.

On success t is returned.

ftp-stream-cwd

function, package: net.ftp.client

Arguments: ftps remote-path

ftp-stream-cwd changes the current working directory to remote-path in an already open FTP session (see with-open-ftp-connection or connect-to-ftp-server) given by ftps.

On success t is returned.

ftp-mkdir

function, package: net.ftp.client

Arguments: *host remote-path &key port (user *default-user*) (password *default-password*)

ftp-mkdir makes a directory on a remote host. The connection is made to host and port using user and password for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

If port is not given then it defaults to the ftp service port.

remote-path is relative to the current directory in effect on the remote host.

On success t is returned. See also ftp-stream-mkdir.

ftp-stream-mkdir

function, package: net.ftp.client

Arguments: ftps remote-path

ftp-stream-mkdir makes a directory on a remote host. This function is similar to ftp-mkdir, except that it uses an already open FTP connection (see with-open-ftp-connection or connect-to-ftp-server) given by ftps.

remote-path has the same meaning as for ftp-mkdir.

On success t is returned.

ftp-rmdir

function, package: net.ftp.client

Arguments: *host remote-path &key port (user *default-user*) (password *default-password*)

ftp-rmdir removes a directory on a remote host. The connection is made to host and port using user and password for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

If port is not given then it defaults to the ftp service port.

remote-path is relative to the current directory in effect on the remote host.

On success t is returned. See also ftp-stream-rmdir.

ftp-stream-rmdir

function, package: net.ftp.client

Arguments: ftps remote-path

ftp-stream-rmdir removes a directory on a remote host. This function is similar to ftp-rmdir, except that it uses an already open FTP connection (see with-open-ftp-connection or connect-to-ftp-server) given by ftps.

remote-path has the same meaning as for ftp-rmdir.

On success t is returned.

ftp-delete

function, package: net.ftp.client

Arguments: host remote-path &key port (user *default-user*) (password *default-password*)

ftp-delete deletes a file on a remote host. The connection is made to host and port using user and password for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

If port is not given then it defaults to the ftp service port.

remote-path is relative to the current directory in effect on the remote host.

On success t is returned. See also ftp-stream-delete.

ftp-stream-delete

function, package: net.ftp.client

Arguments: ftps remote-path

ftp-stream-delete deletes a file on a remote host. This function is similar to ftp-delete, except that it uses an already open FTP connection (see with-open-ftp-connection or connect-to-ftp-server) given by ftps.

remote-path has the same meaning as for ftp-delete.

On success t is returned.

ftp-rename

function, package: net.ftp.client

Arguments: host remote-from-path remote-to-path &key port (user *default-user*) (password *default-password*)

ftp-rename renames a file on a remote host. The connection is made to host and port using user and password for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

If port is not given then it defaults to the ftp service port.

The name of the remote file remote-from-path is changed to remote-to-path. remote-from-path and remote-to-path are relative to the current directory in effect on the remote host.

On success t is returned. See also ftp-stream-rename.

ftp-stream-rename

function, package: net.ftp.client

Arguments: ftps remote-from-path remote-to-path

ftp-stream-rename renames a file on a remote host. This function is similar to ftp-rename, except that it uses an already open FTP connection (see with-open-ftp-connection or connect-to-ftp-server) given by ftps.

remote-from-path and remote-to-path have the same meaning as for ftp-rename.

On success t is returned.

ftp-size

function, package: net.ftp.client

Arguments: host remote-path &key port (user *default-user*) (password *default-password*)

ftp-size returns the size of a remote file. The connection is made to host and port using user and password for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

If port is not given then it defaults to the ftp service port.

remote-path is relative to the current directory in effect on the remote host.

This function uses the SIZE command. This command is somewhat new--it is not part of RFC959--and is probably not implemented in all FTP servers (Allegro FTPd does implement it). If an error occurs, this function returns nil and, in some cases, a second value which is an error code from the FTP server. This second value will probably be helpful in determining why the SIZE command failed.

On success the size of remote-path is returned, and nil is returned if an error occurs or the server cannot determine the size.

ftp-stream-size

function, package: net.ftp.client

Arguments: ftps remote-path

ftp-stream-size returns the size of a remote file. This function is similar to ftp-size, except that it uses an already open FTP connection (see with-open-ftp-connection or connect-to-ftp-server) given by ftps.

remote-path has the same meaning as for ftp-size.

On success the size of remote-path is returned, and nil is returned if an error occurs or the server cannot determine the size.

ftp-chmod

function, package: net.ftp.client

Arguments: host mode remote-path &key port (user *default-user*) (password *default-password*)

ftp-chmod changes the mode of a remote file. The connection is made to host and port using user and password for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

If port is not given then it defaults to the ftp service port.

mode should be a number which must be greater than or equal to zero and less than or equal to #o777 (octal 777 which is decimal 511).

remote-path is relative to the current directory in effect on the remote host.

On success t is returned.

ftp-stream-chmod

function, package: net.ftp.client

Arguments: ftps mode remote-path &key debug

ftp-stream-chmod changes the mode of a remote file. This function is similar to ftp-chmod, except that it uses an already open FTP connection (see with-open-ftp-connection or connect-to-ftp-server) given by ftps.

mode and remote-path have the same meaning as for ftp-chmod.

On success t is returned. See also ftp-stream-umask.

ftp-stream-umask

function, package: net.ftp.client

Arguments: ftps mode

ftp-stream-umask changes the umask in an already open FTP session to remote-path.

mode should be a number which must be greater than or equal to zero and less than or equal to #o777 (octal 777 which is decimal 511).

On success t is returned. See also ftp-stream-chmod.

ftp-file-mod-time

function, package: net.ftp.client

Arguments: host remote-path &key port (user *default-user*) (password *default-password*)

ftp-file-mod-time retrieves the file modification time on host and port of remote-path, using user and password for authentication of the session. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

remote-path should be a pathname namestring. Backward slashes in the namestring will automatically be converted to forward slashes (that is a namestring like "\pub\patches\7.0\windows\ftp.001" will be converted to "/pub/patches/7.0/windows/ftp.001"). This conversion is done because ftp servers typically only understand Windows pathname namestring format.

If port is not given then it defaults to the ftp service port.

This function uses the MDTM command. This command is somewhat new--it is not part of RFC959--and is probably not implemented in all FTP servers (Allegro FTPd does implement it). If an error occurs, this function returns nil and, in some cases, a second value which is an error code from the FTP server. This second value will probably be helpful in determining why the MDTM command failed.

On success, the file modification time of the remote file is returned as a Common Lisp universal time (see decode-universal-time).

ftp-stream-file-mod-time

function, package: net.ftp.client

Arguments: ftps remote-path

ftp-stream-file-mod-time retrieves the file modification time on remote-path using an already open connection to an FTP server ftps. For more information see the ftp-file-mod-time function.

ftp-walk

function, package: net.ftp.client

Arguments:

This function is kept for backwards compatibility only. It should not be used in new code. Use map-over-ftp-directory instead.

map-over-ftp-directory

function, package: net.ftp.client

Arguments: function host remote-path &key (recurse t) port (user *default-user*) (password *default-password*)

map-over-ftp-directory calls function on each directory entry on a remote host. The connection is made to host and port using user and password for authentication. user and password must be strings. Their default values are the values of *default-user* and *default-password*.

function is given three arguments, the filename, the length of the file and a universal time corresponding to the last modification time of the file.

If include-directories is non-nil, then directories will be given to function as well. However, their length and modification time will be nil.

If recurse is non-nil, the default, then descent into subdirectories will occur.

This function return no values.

*default-password*

Variable, package: net.ftp.client

The value of this variable will be used as the value of the password keyword argument for functions that take such an argument (and for the to-password and from-password keyword arguments to ftp-transfer-file). Its initial value is "anonymous". Its value must be a string.

*default-user*

Variable, package: net.ftp.client

The value of this variable will be used as the value of the user keyword argument for functions that take such an argument (and for the to-user and from-user keyword arguments to ftp-transfer-file). Its initial value is "anonymous@somewhere". Its value must be a string.

failed-connection

Class, package: net.ftp.client

This is the condition signaled when connect-to-ftp-server fails.

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.