12.44 rfc.ftp - FTP client ¶

Module: rfc.ftp ¶

This module provides a set of convenient functions to access ftp servers.

Class: <ftp-connection> ¶

{rfc.ftp} An object to keep FTP connection to a server. It has the following public slots.

Instance Variable of <ftp-connection>: transfer-type ¶

FTP transfer type. Must be one of the following symbols: ascii, binary (default), and image.

Instance Variable of <ftp-connection>: passive ¶

True if the client uses passive connection.c

Instance Variable of <ftp-connection>: log-drain ¶

This slot must hold a <log-drain> instance (see gauche.logger - User-level logging) or #f. If it has a <log-drain> instance, ftp communication logs are put to it.

Condition Type: <ftp-error> ¶

{rfc.ftp} This type of exception is thrown when the ftp server returns an error code. Inherits <error>. The message field contains the server reply, including the status code.

Function: call-with-ftp-connection host proc :key passive port username password account log-drain ¶

{rfc.ftp} A high-level convenience routine to open an ftp connection to an ftp server and calls the given procedure.

The server is specified by host. Optionally, you can add user name and/or port number by the form user@servername:port. If present, user and port portion in host supersedes the keyword arguments.

If ftp connection to host is established successfully, proc is called with one argument, which is an instance of <ftp-connection>. When proc returns, the connection is closed and the return value(s) of proc is/are returned from call-with-ftp-connection. When an exception is thrown, the ftp connection is closed before the exception escapes from call-with-ftp-connection.

When a true value is given to the keyword argument passive, created ftp connection will use passive mode to send/receive data. The default is the active mode.

The keyword argument port, username, and password specify the port number, username, and password, respectively. When omitted, the port number defaults to 21, username to "anonymous", and password to "anonymous@". Note that the port number and/or username are ignored when those information is given in the host argument.

If the keyword argument account is given, its value is passed to ftp ACCT command when requested by the server at login time. The default value is a null string "".

The keyword argument log-drain is set to the created ftp connection’s log-drain slot.

Function: ftp-transfer-type conn ¶

{rfc.ftp} Returns the transfer type of the ftp connection conn. Can be used with setter, e.g. (set! (ftp-transfer-type conn) 'ascii).

Function: ftp-passive? conn ¶

{rfc.ftp} Returns true iff ftp connection uses passive data retrieval.

Function: ftp-login host :key passive port username password account log-drain ¶

{rfc.ftp} Connects to the ftp server specified by host, authenticate the user, and returns a newly created <ftp-connection> instance. This procedure is called implicitly when you use call-with-ftp-connection. The semantics of the host argument and the keyword arguments are the same as call-with-ftp-connection.

Function: ftp-quit conn ¶

{rfc.ftp} Sends ftp QUIT command to the connection conn and shutdown the connection. This procedure is called implicitly when you use call-with-ftp-connection.

Once a connection is shut down, you cannot communicate through this connection.

Function: ftp-chdir conn dirname ¶

{rfc.ftp} Changes the remote directory to dirname.

Function: ftp-remove conn path ¶

{rfc.ftp} Removes the remote file named by path.

Function: ftp-help conn :optional option … ¶

{rfc.ftp} Sends ftp HELP commands. Options must be strings, and will be passed to the HELP command arguments.

Function: ftp-mkdir conn dirname ¶

{rfc.ftp} Creates a directory dirname. Returns the created directory name.

Function: ftp-current-directory conn ¶

{rfc.ftp} Returns the current remote directory.

Function: ftp-site conn arg ¶

{rfc.ftp} Sends ftp SITE command with the argument arg. The SITE command’s semantics depends on the server. Returns the server reply.

Function: ftp-rmdir conn dirname ¶

{rfc.ftp} Removes remote directory specified by dirname. Returns the server reply.

Function: ftp-stat conn :optional pathname ¶

{rfc.ftp} Sends ftp STAT command to the server. RFC959 defines several different semantics of this command. See RFC959 for the details. Returns the server reply.

Function: ftp-system conn ¶

{rfc.ftp} Queries the server’s operating system by ftp SYST command. Returns the server reply without status code.

(call-with-ftp-connection "localhost" ftp-system)
  ⇒ "UNIX Type: L8"

Function: ftp-size conn path ¶

{rfc.ftp} Queries the size of the remote file specified by path. Returns the integer value.

Note: The size may differ whether the connection is in ascii mode or binary mode; furthermore, some ftp server may returns the value only if the connection is in binary mode. Make sure you have desired transfer type in the connection.

Function: ftp-mdtm conn path ¶

{rfc.ftp} Queries the modification time of the remote file specified by path. This function returns the server’s reply as is, including the status code. Use ftp-mtime below to obtain a parsed result.

Function: ftp-mtime conn path :optional local-time? ¶

{rfc.ftp} Queries the modification time of the remote file specified by path, and returns the result in a <date> object (see srfi.19 - Time data types and procedures). If a true value is given to local-time?, the returned date is in local time. Otherwise, the returned date is in UTC.

Function: ftp-noop conn ¶

{rfc.ftp} Sends ftp NOOP command and returns the server’s reply.

Function: ftp-list conn :optional path ¶

{rfc.ftp} Returns the information about the files within the remote file or directory specified by path, or the current remote directory, much like ls(1) format. Returns a list of strings, where each string is for each line of the server’s reply. The exact format depends on the server.

Function: ftp-name-list conn :optional path ¶

Function: ftp-ls conn :optional path ¶

{rfc.ftp} Return the list of names in the specified path, or the current remote directory, without any other information. ftp-ls is just an alias of ftp-name-list for the convenience.

Note that the server may return an error if there’s no files in the remote directory.

Function: ftp-get conn path :key sink flusher ¶

{rfc.ftp} Retrieves a remote file path. The retrieved data is sent to an output port given to sink. Once all the data is retrieved, a procedure given to flusher is called with the port sink as an argument, and its return value(s) is/are returned from ftp-get.

The default values of sink and flusher are a newly created string port and get-output-string, respectively. That is, ftp-get returns the retrieved data as a string by default. You don’t want this behavior if the retrieved file is huge.

Function: ftp-put conn from-file :optional to-file ¶

{rfc.ftp} Sends the local file specified by from-file to the remote server as the name specified by to-file. If to-file is omitted, the basename of from-file is used. Returns the server response.

Function: ftp-put-unique conn from-file ¶

{rfc.ftp} Sends the local file specified by from-file to the remote server. The remote side filename is guaranteed to be unique. Returns two values—the final server response, and the remote file name. The second value can be #f if the remote host doesn’t support RFC1123 (which must be rare).

Function: ftp-rename conn from-name to-name ¶

{rfc.ftp} Renames the remote file specified by from-name to the name to-name. Returns the final response of the server.