282 lines
10 KiB
TeX
282 lines
10 KiB
TeX
\section{FTP client}\label{sec:ftp}
|
|
\begin{description}
|
|
\item[Used files:] ftp.scm, ftp-obsolete.scm
|
|
\item[Name of the package:] ftp, ftp-obsolete
|
|
\end{description}
|
|
|
|
\subsection{What users want to know}
|
|
This module lets you transfer files between networked machines from
|
|
the Scheme Shell, using the File Transfer Protocol as described in
|
|
RFC~959. The protocol specifies the behaviour of a server machine,
|
|
which runs an ftp daemon (not implemented by this module), and of
|
|
clients (that's us) which request services from the server.
|
|
|
|
Some of the procedures in this module extract useful information from
|
|
the server's reply, such as the size of a file, or the name of the
|
|
directory we have moved to. These procedures return either the
|
|
extracted information, or \sharpf{} to indicate failure. Other
|
|
procedures return a ``status'', which is either the server's reply as
|
|
a string, or \sharpf{} to signify failure.
|
|
|
|
The server's response is always checked. If the server's response
|
|
doesn't match the expected code from the server, a catchable
|
|
\ex{ftp-error} is raised.
|
|
|
|
\FIXME{The source says you can look at pop3.scm to find out how to
|
|
catch the ftp-error raised by some procedures this. We have not had
|
|
a look there, yet.}
|
|
|
|
\subsubsection*{Entry points }
|
|
|
|
\defun{ftp-connect} {host \ovar{logfile}} {connection}
|
|
\begin{desc}
|
|
Open a command connection with the remote machine \semvar{host}.
|
|
Optionally start logging the conversation with the server to
|
|
\semvar{logfile}, which will be appended to if it already exists,
|
|
and created otherwise. Beware, the \semvar{logfile} contains
|
|
passwords in clear text (it is created with permissions
|
|
\ex{og-rxw})!
|
|
\end{desc}
|
|
|
|
\defun{ftp-login} {connection \ovar{login \ovar{passwd}}} {status}
|
|
\begin{desc}
|
|
Log in to the remote host. If a \semvar{login} and \semvar{password}
|
|
are not provided, they are first searched for in the user's
|
|
\~/.netrc file, or default to user ``anonymous'' and password
|
|
``user@host''
|
|
\end{desc}
|
|
|
|
\defun{ftp-type} {connection type} {status}
|
|
\begin{desc}
|
|
Change the transfer mode for future data connections. This may be
|
|
either \ex{'ascii }or \ex{'text}, respectively, for transfering text
|
|
files, or \ex{'binary} for transfering binary files. If
|
|
\semvar{type} is a string it is sent verbatim to the server.
|
|
\end{desc}
|
|
|
|
\defun{ftp-rename} {connection oldname newname} {status}
|
|
\begin{desc}
|
|
Change the name of \semvar{oldname} on the remote host to
|
|
\semvar{newname} (assuming sufficient permissions). \semvar{oldname}
|
|
and \semvar{newname} are strings; if prefixed with "/" they are
|
|
taken relative to the server's root, and otherwise they are relative
|
|
to the current directory. Note that in the case of anonymous ftp
|
|
(user ``anonymous'' or ``ftp''), the server root is different from
|
|
the root of the servers's filesystem.
|
|
\end{desc}
|
|
|
|
\defun{ftp-delete} {connection file} {status}
|
|
\begin{desc}
|
|
Delete \semvar{file} from the remote host (assuming the user has
|
|
appropriate permissions).
|
|
\end{desc}
|
|
|
|
\defun{ftp-cd} {connection dir} {status}
|
|
\begin{desc}
|
|
Change the current directory on the server.
|
|
\end{desc}
|
|
|
|
\defun{ftp-cdup} {connection} {status}
|
|
\begin{desc}
|
|
Move to the parent directory on the server.
|
|
\end{desc}
|
|
|
|
\defun{ftp-pwd} {connection} {string}
|
|
\begin{desc}
|
|
Return the current directory on the remote host, as a string.
|
|
\end{desc}
|
|
|
|
\defun{ftp-ls} {connection} {status}
|
|
\begin{desc}
|
|
Provide a listing of the current directory's contents, in short
|
|
format, \ie as a list of filenames.
|
|
\end{desc}
|
|
|
|
\defun{ftp-dir} {connection} {status}
|
|
\begin{desc}
|
|
Provide a listing of the current directory's contents, in long
|
|
format. Most servers (\Unix, MS Windows, MacOS) use a standard
|
|
format with one file per line, with the file size and other
|
|
information, but other servers (VMS, \ldots) use their own format.
|
|
\end{desc}
|
|
|
|
\defun{ftp-get} {connection remote-file \ovar{local-file}} {status $|$ string}
|
|
\begin{desc}
|
|
Download \semvar{remote-file} from the FTP server. If
|
|
\semvar{local-file} is a string, save the data to
|
|
\semvar{local-file} on the local host; otherwise save to a local
|
|
file named \semvar{remote-file}. \semvar{remote-file} and
|
|
\semvar{local-file} may be absolute file names (with a leading `/'),
|
|
or relative to the current directory. If \semvar{local-file} is
|
|
\sharpt, output data to \ex{(current-output-port)}, and if it is
|
|
\sharpf{} return the data as a string.
|
|
\end{desc}
|
|
|
|
\defun{ftp-put} {connection local-file \ovar{remote-file}} {status}
|
|
\begin{desc}
|
|
Upload \semvar{local-file} to the FTP server. If
|
|
\semvar{remote-file} is specified, then save the data to
|
|
\semvar{remote-file} on the remote host; otherwise save to a remote
|
|
file named \semvar{local-file}. \semvar{local-file} and
|
|
\semvar{remote-file} may be absolute file names (with a leading
|
|
`/'), or relative to the current directory.
|
|
\end{desc}
|
|
|
|
\defun{ftp-append}{connection local-file \ovar{remote-file}}{status}
|
|
\begin{desc}
|
|
Does the same as \ex{ftp-get}, but appends the data to the remote
|
|
file, if it exists.
|
|
\end{desc}
|
|
|
|
\defun{ftp-rmdir} {connection dir} {status}
|
|
\begin{desc}
|
|
Remove the directory \semvar{dir} from the remote host (assuming
|
|
sufficient permissions).
|
|
\end{desc}
|
|
|
|
\defun{ftp-mkdir} {connection dir} {status}
|
|
\begin{desc}
|
|
Create a new directory named \semvar{dir} on the remote host
|
|
(assuming sufficient permissions).
|
|
\end{desc}
|
|
|
|
\defun{ftp-modification-time} {connection file} {date}
|
|
\begin{desc}
|
|
Request the time of the last modification of \semvar{file} on the
|
|
remote host, and on success return a Scsh date record. This command
|
|
is not part of RFC~959 and is not implemented by all servers, but is
|
|
useful for mirroring.
|
|
\end{desc}
|
|
|
|
\defun{ftp-size} {connection file} {integer}
|
|
\begin{desc}
|
|
Return the size of \semvar{file} in bytes.
|
|
\end{desc}
|
|
|
|
\defun{ftp-abort} {connection} {status}
|
|
\begin{desc}
|
|
Abort the current data transfer. Not particularly useful with this
|
|
im\-ple\-men\-ta\-tion since the data transfer commands only return
|
|
once the transfer is complete.
|
|
\end{desc}
|
|
|
|
\defun{ftp-quit} {connection} {status}
|
|
\begin{desc}
|
|
Close the connection to the remote host. The \semvar{connection}
|
|
object is useless after a quit command.
|
|
\end{desc}
|
|
|
|
\defun{ftp-quot}{connection command}{status}
|
|
\begin{desc}
|
|
Send a \semvar{command} verbatim to the remote server and wait for a
|
|
response.
|
|
\end{desc}
|
|
|
|
\defun{ftp-error?}{thing}{boolean}
|
|
\begin{desc}
|
|
Returns \sharpt, if \semvar{thing} is a \ex{ftp-error} object,
|
|
otherwise \sharpf.
|
|
\end{desc}
|
|
|
|
\subsubsection*{Unimplemented}
|
|
|
|
The following rfc959 commands are not implemented:
|
|
|
|
\begin{tabular}{ll}
|
|
\ex{ACCT} & account; this is ignored by most servers) \\
|
|
\ex{SMNT} & structure mount, for mounting another filesystem \\
|
|
\ex{REIN} & reinitialize connection \\
|
|
\ex{LOGOUT} & quit without interrupting ongoing transfers \\
|
|
\ex{STRU} & file structure \\
|
|
\ex{ALLO} & allocate space on server \\
|
|
\end{tabular}
|
|
|
|
\subsection{What programmers want to know}
|
|
|
|
\subsection*{Overview}
|
|
Communication is initiated by the client. The server responds to each
|
|
request with a three digit status code and an explanatory message, and
|
|
occasionally with data (which is sent via a separate, one-off
|
|
channel). The client starts by opening a command connection to a well
|
|
known port on the server machine. Messages send to the server are of
|
|
the form
|
|
\codex{CMD [ <space> arg ] <CR> <LF>}
|
|
Replies from the server are of the form
|
|
\codex{xyz <space> Informative message <CR> <LF>}
|
|
where xyz is a three digit code which indicates whether the operation
|
|
succeeded or not, whether the server is waiting for more data, etc.
|
|
The server may also send multiline messages of the form
|
|
|
|
\begin{alltt}
|
|
xyz- <space> Start of multiline message <CR> <LF>
|
|
[ <space>+ More information ]* <CR> <LF>
|
|
xyz <space> End of multiline message <CR> <LF>%
|
|
\end{alltt}
|
|
|
|
For further informations have a look at the source file.
|
|
|
|
This module has no support for sites behind a firewall. It shouldn't
|
|
be very tricky; it only requires using passive mode. Might want to add
|
|
something like the \ex{/usr/bin/ftp} command \ex{restrict}, which
|
|
implements data port range restrictions.
|
|
|
|
\subsubsection*{Obsolete procedures}
|
|
|
|
Names in further versions of \ex{ftp} contained a colon (`\ex{:}')
|
|
after the prefix `\ex{ftp-}'. This is now changed to a hyphen
|
|
('\ex{-}'), accordingly to SUnet's philosophy. If you need the old
|
|
names, use the \ex{ftp\=obsolete}-package that maps the old names to
|
|
the new ones.
|
|
|
|
|
|
\subsubsection*{Portablitity}
|
|
|
|
Items of the following list are necessary in order to use this module:
|
|
\begin{itemize}
|
|
\item The netrc.scm module for parsing ~/.netrc files.
|
|
\item Scsh socket code
|
|
\item Scsh records
|
|
\item Receive for multiple values
|
|
\item \scm{} signals/handlers
|
|
\end{itemize}
|
|
|
|
|
|
\subsubsection*{Related work}
|
|
|
|
\begin{itemize}
|
|
\item RFC~959 describes the FTP protocol; see \newline
|
|
\ex{http://www.cis.ohio-state.edu/htbin/rfc/rfc959.html}
|
|
\item \ex{/anonymous@sunsite.unc.edu:/pub/Linux/libs/ftplib.tar.gz} is
|
|
a library similar to this one, written in C, by Thomas Pfau
|
|
\item \ex{FTP.pm} is a Perl module with similar functionality
|
|
(available from \ex{http://www.perl.com/CPAN})
|
|
\item Emacs gets transparent remote file access from \ex{ange-ftp.el}
|
|
by Ange Norman. However, it cheats by using \ex{/usr/bin/ftp}.
|
|
\item Siod (a small-footprint Scheme implementation by George Carette)
|
|
comes with a file \ex{ftp.scm }with a small subset of these
|
|
functions defined.
|
|
\end{itemize}
|
|
|
|
\subsubsection*{TODO}
|
|
\begin{itemize}
|
|
\item Handle passive mode and firewalls.
|
|
\item Unix-specific commands such as \ex{SITE UMASK}, \ex{SITE CHMOD},
|
|
\ex{SITE IDLE}, \ex{SITE HELP}.
|
|
\item Object-based interface? (like SICP message passing).
|
|
\item Improved error handling.
|
|
\item A lot of the calls to format could be replaced by calls to
|
|
string-join. Maybe format is easier to read?
|
|
\item The \ex{ftp-rename} command should have an optional argument
|
|
\ex{:rename} which defaults to \sharpf, which would make us upload
|
|
to a temporary name and rename at the end of the upload. This
|
|
atomicity is important for ftp or http servers which are serving a
|
|
load, and to avoid problems with "no space on device".
|
|
\item Automatic relogin a la \ex{ang-ftp}.
|
|
\end{itemize}
|
|
|
|
%%% Local Variables:
|
|
%%% mode: latex
|
|
%%% TeX-master: man.tex
|
|
%%% End:
|
|
|