Overview

CL-FTP is a library which provides FTP client functionality to a Common Lisp program. CL-FTP uses the ACL-COMPAT package for network sockets and the SPLIT-SEQUENCE package for some parsing needs.

License

This software, and documentation, is (c) 2002 Matthew Danish. Redistribution and modification is permitted under a MIT-style license. See the LICENSE file for more details.

Programmers Interface

• Class ftp-connection derived from () --
  Initargs:
  

  • :HOSTNAME -- The remote hostname -- Default: Not specified
  • :PORT -- The remote port -- Default: 21
  • :USERNAME -- The login username -- Default: "anonymous"
  • :PASSWORD -- The login password -- Default: "cl-ftp@cclan.net"
  • :PASSIVE-FTP-P -- Use passive FTP if non-nil -- Default: NIL
  • :SESSION-STREAM -- Send FTP session output to this stream, if non-nil -- Default: NIL
  • :CODE-CUT-OFF-P -- When non-nil, cut-off FTP codes in logging output -- Default: T
  Represents an FTP connection and associated state. The INITIALIZE-INSTANCE :AFTER method takes care of connection and login, if possible.

• Function ftp-hostname (connection-variable)
  The remote hostname

  Function ftp-port (connection-variable)
  The remote port

  Function ftp-username (connection-variable)
  The login username

  Function ftp-password (connection-variable)
  The login password

  Function ftp-session-stream (connection-variable)
  The session stream for the FTP connection

  Function passive-ftp-p (connection-variable)
  Non-nil iff given FTP connection is to use passive FTP for data transfers

  Function (setf passive-ftp-p) (value connection-variable)
  Value should be non-nil to use passive FTP for data transfers with the given FTP connection

  Function code-cut-off-p (connection-variable)
  Non-nil iff FTP codes are to be cut-off when logging

  Function (setf code-cut-off-p) (value connection-variable)
  Alter value of code-cut-off-p

• Condition ftp-error derived from () --
  Slots:
  

  • ftp-error-code -- Code associated with message -- Default: Not specified
  • error-message -- FTP server's error message -- Default: Not specified

• Condition invalid-code derived from (ftp-error) --
  Slots:
  

  • expected -- Expected code -- Default: Not specified
  • received -- Received code -- Default: Not specified

• Condition transient-negative-completion derived from (ftp-error) --
  Slots:
  

  Signalled when a transient error is received from the FTP server. This means that the input was fine, but something else went wrong. Feel free to resend.

• Condition permanent-negative-completion derived from (ftp-error) --
  Slots:
  

  Signalled when a permanent error is received from the FTP server. This means that the input was not acceptable and should not be re-sent.

• Function connect-to-server (connection-variable)
  Attempts to connect to the server using the information provided by connection-variable. If connection-variable represents an existing connection, then that connection will be closed and a new one established.

• Function close-connection (connection-variable)
  Closes the given FTP connection

• Macro with-ftp-connection ((connection-variable &key hostname port username password passive-ftp-p session-stream (if-failed error)) &body body)
  Opens and ensures proper close of an FTP connection. Binds connection-variable to the FTP-CONNECTION object in the scope of body. Arguments are similar to that of the initargs for the class FTP-CONNECTION.

• Macro with-transfer-socket ((transfer-socket connection-variable command-string &key rest (type binary)) &body body)
  Opens a data transfer socket in the scope of body, using the given FTP connection and executing the given FTP command-string. If :REST is specified, then the FTP "REST" command will be sent with the value of the argument. :TYPE may be :BINARY or :ASCII. Closes the transfer-socket upon dynamic exit of body.

• Function call-with-transfer-socket (connection-variable command-string function &key rest (type binary))
  Similar to WITH-TRANSFER-SOCKET, except that function is a function which accepts a single argument; namely the transfer-socket

• Function retrieve-file (connection-variable remote local &key (type binary) rest)
  Retrieves a file given a remote filename, and a local filename or stream. :TYPE is either :ASCII or :BINARY, and :REST specifies an integer amount to seek into the file before retrieving it.

• Function store-file (connection-variable local remote &key (type binary))
  Stores a file given a local filename or stream and a remote filename. :TYPE is either :ASCII or :BINARY.

• Function receive-response (connection-variable &key (block nil))
  Receives a response from the FTP server. Returns a list of strings as the first value and the response code as the second. If :BLOCK is T, then will block until response received. Otherwise return NIL if nothing is available currently.

• Function data-to-string (data-list)
  Converts a list of strings, such as that produced by receive-response, to one string with newlines after each formerly-list-element.

• Function data-ready-p (connection-variable)
  Non-nil iff data is waiting to be read from the control connection.

• Function send-list-command (connection-variable output &optional (pathname .))
  Sends the FTP LIST command. If OUTPUT is NIL, returns a string. If OUTPUT is T, prints to *standard-output*. Otherwise, it treats OUTPUT as the output stream.

• Function send-nlst-command (connection-variable output &optional (pathname .))
  Sends the FTP NLST command. If OUTPUT is NIL, returns a string. If OUTPUT is T, prints to *standard-output*. Otherwise, it treats OUTPUT as the output stream.

• Function retrieve-filename-list (connection-variable &optional (pathname .))
  Retrieves a list of filenames for the given pathname.

• Function retrieve-file-info-list (connection-variable &optional (pathname .))
  Retrieves a list of the form (type name) where type is :DIRECTORY or :FILE and name is a filename in the given directory named by pathname. Note: this is implemented by attempting CWDs, and may break if the FTP server does strange things.

• Function send-size-command (connection-variable remote-filename)
  Sends the FTP SIZE command on the given remote-filename. Returns an integer size. Signals error if no such file.

• Function send-cwd-command (connection-variable remote-directory)
  Sends the FTP CWD command, to change to the given remote-directory. If remote-directory is "..", CDUP is sent instead. Signals error if not possible.

• Function send-cdup-command (connection-variable)
  Sends the FTP CDUP command.

• Function send-pwd-command (connection-variable)
  Sends the FTP PWD command and returns the current working directory as a string.

• Function send-mkd-command (connection-variable remote-directory)
  Sends the FTP MKD command to make a remote directory. Returns directory name as string. Signals error if not possible.

Examples

(with-ftp-connection (conn :hostname "foo") (retrieve-file conn "bar" "baz"))

Further examples should be included with your copy of this software. See simple-client.lisp for a simple FTP client written with CL-FTP.