| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version | ||||||||
This document contains the following sections:
1.0 Introduction
The Allegro FTP client module can be used to communicate with an FTP
server, including Allegro FTPd (https://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:
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.
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.
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-connectionis signaled.
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.
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))
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*) (mode :binary)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Arguments: &key
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.
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.
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).
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.
Arguments:
This function is kept for backwards compatibility only. It should not be used in new code. Use map-over-ftp-directory instead.
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.
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.
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.
This is the condition signaled when connect-to-ftp-server fails.
Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version | ||||||||