|
Allegro CL version 11.0 | ||||||||
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:
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.
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.
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.
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))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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
Class, package: net.ftp.client
This is the condition signaled when connect-to-ftp-server fails.
Copyright (c) 2023, Franz Inc. Lafayette, CA., USA. All rights reserved.
|
Allegro CL version 11.0 | ||||||||