scsh-conservatory
/
sunet
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Reasonably complete and up-to-date docs for FTP.

This commit is contained in:
sperber 2003-01-16 14:12:11 +00:00
parent b81da26fdc
commit 4bcf374d8e
1 changed files with 86 additions and 204 deletions
doc/latex
ftp.tex

290
doc/latex/ftp.tex
View File

@ -1,278 +1,160 @@
\chapter{FTP client}\label{cha:ftp} \chapter{FTP client}\label{cha:ftp}
\begin{description}
\item[Used files:] ftp.scm, ftp-obsolete.scm
\item[Name of the package:] ftp, ftp-obsolete
\end{description}
\section{What users want to know} The \ex{ftp} structure lets you transfer files between networked
This module lets you transfer files between networked machines from machines from the Scheme Shell, using the File Transfer Protocol as
the Scheme Shell, using the File Transfer Protocol as described in described in RFC~959.
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 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 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 directory we have moved to. These procedures return the extracted
extracted information, or \sharpf{} to indicate failure. Other information, or, if the server's response doesn't match the expected
procedures return a ``status'', which is either the server's reply as code from the server, a catchable \ex{ftp-error} is raised.
a string, or \sharpf{} to signify failure.
The server's response is always checked. If the server's response \defun{ftp-connect}{host login password passive? [log-port]}{connection}
doesn't match the expected code from the server, a catchable
\ex{ftp-error} is raised.
%{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 [logfile]} {connection}
\begin{desc} \begin{desc}
Open a command connection with the remote machine \semvar{host}. Open a command connection with the remote machine \var{host} and
Optionally start logging the conversation with the server to login on that server with \var{login} and \var{password}.
\semvar{logfile}, which will be appended to if it already exists, \var{Login} and \var{password} can be \sharpf, in which case the
and created otherwise. Beware, the \semvar{logfile} contains information is extracted from the user's \ex{.netrc} file if necessary.
passwords in clear text (it is created with permissions
\ex{og-rxw})! If \var{log-port} is specified, it must be an output port: this
starts logging the conversation with the server to that port. Note
that the log contains passwords in clear text.
\end{desc} \end{desc}
\defun{ftp-login} {connection [login] [passwd]} {status} \dfn{ftp-type}{\synvar{name}}{ftp-type}{syntax}
\defunx{set-ftp-type!}{connection ftp-type}{undefined}
\begin{desc} \begin{desc}
Log in to the remote host. If a \semvar{login} and \semvar{password} This change the transfer mode for future file transfers. The
are not provided, they are first searched for in the user's transfer mode is specfified by \var{ftp-type} which can be created
\~/.netrc file, or default to user ``anonymous'' and password with the \ex{ftp-type} macro. \synvar{Name} must be either
``user@host'' \ex{binary} for binary data or \ex{ascii} for text.
\end{desc} \end{desc}
\defun{ftp-type} {connection type} {status} \defun{ftp-rename}{connection old new}{undefined}
\begin{desc} \begin{desc}
Change the transfer mode for future data connections. This may be This changes the name of \var{old} on the remote host to \var{new}
either \ex{'ascii }or \ex{'text}, respectively, for transfering text (assuming sufficient permissions). \var{Old} and \var{new} are
files, or \ex{'binary} for transfering binary files. If strings.
\semvar{type} is a string it is sent verbatim to the server.
\end{desc} \end{desc}
\defun{ftp-rename} {connection oldname newname} {status} \defun{ftp-delete}{connection file}{undefined}
\begin{desc} \begin{desc}
Change the name of \semvar{oldname} on the remote host to This deletes \var{file} from the remote host (assuming the user has
\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). appropriate permissions).
\end{desc} \end{desc}
\defun{ftp-cd} {connection dir} {status} \defun{ftp-cd}{connection dir}{undefined}
\begin{desc} \begin{desc}
Change the current directory on the server. This changes the current directory on the server.
\end{desc} \end{desc}
\defun{ftp-cdup} {connection} {status} \defun{ftp-cdup}{connection}{undefined}
\begin{desc} \begin{desc}
Move to the parent directory on the server. This move to the parent directory on the server.
\end{desc} \end{desc}
\defun{ftp-pwd} {connection} {string} \defun{ftp-pwd}{connection}{string}
\begin{desc} \begin{desc}
Return the current directory on the remote host, as a string. Return the current directory on the remote host, as a string.
\end{desc} \end{desc}
\defun{ftp-ls} {connection} {status} \defun{ftp-ls}{connection [dir]}{list}
\begin{desc} \begin{desc}
Provide a listing of the current directory's contents, in short This returns a list of filenames on the remote host, either from the
format, \ie as a list of filenames. current directory (if \var{dir} is not specified), or from the
directory specified by \var{dir}.
\end{desc} \end{desc}
\defun{ftp-dir} {connection} {status} \defun{ftp-dir}{connection [dir]}{status}
\begin{desc} \begin{desc}
Provide a listing of the current directory's contents, in long This returns a list of long-form file name entries on the remote
format. Most servers (\Unix, MS Windows, MacOS) use a standard host, either from the current directory (if \var{dir} is not
format with one file per line, with the file size and other specified), or from the directory specified by \var{dir}. (Note
information, but other servers (VMS, \ldots) use their own format. that the format for the long-form entries is not specified by the
FTP standard.)
\end{desc} \end{desc}
\defun{ftp-get} {connection remote-file [local-file]} {status $|$ string} \defun{ftp-get}{connection remote-file proc}{undefined}
\begin{desc} \begin{desc}
Download \semvar{remote-file} from the FTP server. If This downloads \var{remote-file} from the FTP server.
\semvar{local-file} is a string, save the data to \ex{Ftp-get} establishes a data conneciton to the server, attaches
\semvar{local-file} on the local host; otherwise save to a local an input port to the data connection, and calls \var{proc} on that
file named \semvar{remote-file}. \semvar{remote-file} and port.
\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} \end{desc}
\defun{ftp-put} {connection local-file [remote-file]} {status} \defun{ftp-put}{connection remote-file proc}{undefined}
\begin{desc} \begin{desc}
Upload \semvar{local-file} to the FTP server. If This uploads \var{remote-file} to the FTP server. \ex{Ftp-put}
\semvar{remote-file} is specified, then save the data to establishes a data conneciton to the server, attaches an output port
\semvar{remote-file} on the remote host; otherwise save to a remote to the data connection, and calls \var{proc} on that port.
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} \end{desc}
\defun{ftp-append}{connection local-file [remote-file]}{status} \defun{ftp-append}{connection remote-file proc}{undefined}
\begin{desc} \begin{desc}
Does the same as \ex{ftp-get}, but appends the data to the remote This appends data to \var{remote-file} on the FTP server.
file, if it exists. \ex{Ftp-append} establishes a data conneciton to the server,
attaches an output port to the data connection, and calls \var{proc}
on that port.
\end{desc} \end{desc}
\defun{ftp-rmdir} {connection dir} {status} \defun{ftp-rmdir}{connection dir}{undefined}
\begin{desc} \begin{desc}
Remove the directory \semvar{dir} from the remote host (assuming This removes the directory \var{dir} from the remote host (assuming
sufficient permissions). sufficient permissions).
\end{desc} \end{desc}
\defun{ftp-mkdir} {connection dir} {status} \defun{ftp-mkdir}{connection dir}{undefined}
\begin{desc} \begin{desc}
Create a new directory named \semvar{dir} on the remote host This create a new directory named \var{dir} on the remote host
(assuming sufficient permissions). (assuming sufficient permissions).
\end{desc} \end{desc}
\defun{ftp-modification-time} {connection file} {date} \defun{ftp-modification-time}{connection file}{date}
\begin{desc} \begin{desc}
Request the time of the last modification of \semvar{file} on the This requests the time of the last modification of \var{file} on the
remote host, and on success return a Scsh date record. This command 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 is not part of RFC~959 and is not implemented by all servers, but is
useful for mirroring. useful for mirroring.)
\end{desc} \end{desc}
\defun{ftp-size} {connection file} {integer} \defun{ftp-size}{connection file}{integer}
\begin{desc} \begin{desc}
Return the size of \semvar{file} in bytes. This returns the size of \var{file} in bytes. (This command is not
part of RFC~959 and is not implemented by all servers.)
\end{desc} \end{desc}
\defun{ftp-abort} {connection} {status} \defun{ftp-quit}{connection}{undefined}
\begin{desc} \begin{desc}
Abort the current data transfer. Not particularly useful with this This closes the connection to the remote host. The \var{connection}
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. object is useless after a quit command.
\end{desc} \end{desc}
\defun{ftp-quot}{connection command}{status} \defun{ftp-quot}{connection command}{status}
\begin{desc} \begin{desc}
Send a \semvar{command} verbatim to the remote server and wait for a This sends a \var{command} verbatim to the remote server and wait
response. for a response. The response text is returned verbatim.
\end{desc} \end{desc}
\defun{ftp-error?}{thing}{boolean} \defun{ftp-error?}{thing}{boolean}
\begin{desc} \begin{desc}
Returns \sharpt, if \semvar{thing} is a \ex{ftp-error} object, This returns \sharpt if \var{thing} is a \ex{ftp-error} object,
otherwise \sharpf. otherwise \sharpf.
\end{desc} \end{desc}
\subsubsection*{Unimplemented} \defun{copy-port->port-binary}{input-port oputput-port}{undefined}
\defunx{copy-port->port-ascii}{input-port oputput-port}{undefined}
The following rfc959 commands are not implemented: \defunx{copy-ascii-port->port}{input-port oputput-port}{undefined}
\begin{desc}
\begin{tabular}{ll} These procedures are useful for downloading and uploading data to an
\ex{ACCT} & account; this is ignored by most servers) \\ FTP connection via \ex{ftp-get}, \ex{ftp-get}, and \ex{ftp-append}.
\ex{SMNT} & structure mount, for mounting another filesystem \\ They all copy data from one port to another.
\ex{REIN} & reinitialize connection \\ \ex{Copy-port->port-binary} copies verbatim, while the other two
\ex{LOGOUT} & quit without interrupting ongoing transfers \\ perform CR/LF conversion for ASCII data transfers.
\ex{STRU} & file structure \\ \ex{Copy-port->port-ascii} adds CR/LFs at line endings on output,
\ex{ALLO} & allocate space on server \\ whereas \ex{Copy-ascii-port->port} removes CR/LFs at line endings
\end{tabular} end replaces them by ordinary LFs.
\end{desc}
\section{What programmers want to know}
\section{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: %%% Local Variables:
%%% mode: latex %%% mode: latex