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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

290
doc/latex/ftp.tex
View File

@ -1,278 +1,160 @@
\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}
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.
The \ex{ftp} structure lets you transfer files between networked
machines from the Scheme Shell, using the File Transfer Protocol as
described in RFC~959.
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.
directory we have moved to. These procedures return the extracted
information, or, if the server's response doesn't match the expected
code from the server, a catchable \ex{ftp-error} is raised.
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.
%{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}
\defun{ftp-connect}{host login password passive? [log-port]}{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})!
Open a command connection with the remote machine \var{host} and
login on that server with \var{login} and \var{password}.
\var{Login} and \var{password} can be \sharpf, in which case the
information is extracted from the user's \ex{.netrc} file if necessary.
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}
\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}
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''
This change the transfer mode for future file transfers. The
transfer mode is specfified by \var{ftp-type} which can be created
with the \ex{ftp-type} macro. \synvar{Name} must be either
\ex{binary} for binary data or \ex{ascii} for text.
\end{desc}
\defun{ftp-type} {connection type} {status}
\defun{ftp-rename}{connection old new}{undefined}
\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.
This changes the name of \var{old} on the remote host to \var{new}
(assuming sufficient permissions). \var{Old} and \var{new} are
strings.
\end{desc}
\defun{ftp-rename} {connection oldname newname} {status}
\defun{ftp-delete}{connection file}{undefined}
\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
This deletes \var{file} from the remote host (assuming the user has
appropriate permissions).
\end{desc}
\defun{ftp-cd} {connection dir} {status}
\defun{ftp-cd}{connection dir}{undefined}
\begin{desc}
Change the current directory on the server.
This changes the current directory on the server.
\end{desc}
\defun{ftp-cdup} {connection} {status}
\defun{ftp-cdup}{connection}{undefined}
\begin{desc}
Move to the parent directory on the server.
This move to the parent directory on the server.
\end{desc}
\defun{ftp-pwd} {connection} {string}
\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}
\defun{ftp-ls}{connection [dir]}{list}
\begin{desc}
Provide a listing of the current directory's contents, in short
format, \ie as a list of filenames.
This returns a list of filenames on the remote host, either from the
current directory (if \var{dir} is not specified), or from the
directory specified by \var{dir}.
\end{desc}
\defun{ftp-dir} {connection} {status}
\defun{ftp-dir}{connection [dir]}{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.
This returns a list of long-form file name entries on the remote
host, either from the current directory (if \var{dir} is not
specified), or from the directory specified by \var{dir}. (Note
that the format for the long-form entries is not specified by the
FTP standard.)
\end{desc}
\defun{ftp-get} {connection remote-file [local-file]} {status $|$ string}
\defun{ftp-get}{connection remote-file proc}{undefined}
\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.
This downloads \var{remote-file} from the FTP server.
\ex{Ftp-get} establishes a data conneciton to the server, attaches
an input port to the data connection, and calls \var{proc} on that
port.
\end{desc}
\defun{ftp-put} {connection local-file [remote-file]} {status}
\defun{ftp-put}{connection remote-file proc}{undefined}
\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.
This uploads \var{remote-file} to the FTP server. \ex{Ftp-put}
establishes a data conneciton to the server, attaches an output port
to the data connection, and calls \var{proc} on that port.
\end{desc}
\defun{ftp-append}{connection local-file [remote-file]}{status}
\defun{ftp-append}{connection remote-file proc}{undefined}
\begin{desc}
Does the same as \ex{ftp-get}, but appends the data to the remote
file, if it exists.
This appends data to \var{remote-file} on the FTP server.
\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}
\defun{ftp-rmdir} {connection dir} {status}
\defun{ftp-rmdir}{connection dir}{undefined}
\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).
\end{desc}
\defun{ftp-mkdir} {connection dir} {status}
\defun{ftp-mkdir}{connection dir}{undefined}
\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).
\end{desc}
\defun{ftp-modification-time} {connection file} {date}
\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
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
is not part of RFC~959 and is not implemented by all servers, but is
useful for mirroring.
useful for mirroring.)
\end{desc}
\defun{ftp-size} {connection file} {integer}
\defun{ftp-size}{connection file}{integer}
\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}
\defun{ftp-abort} {connection} {status}
\defun{ftp-quit}{connection}{undefined}
\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}
This closes the connection to the remote host. The \var{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.
This sends a \var{command} verbatim to the remote server and wait
for a response. The response text is returned verbatim.
\end{desc}
\defun{ftp-error?}{thing}{boolean}
\begin{desc}
Returns \sharpt, if \semvar{thing} is a \ex{ftp-error} object,
otherwise \sharpf.
This returns \sharpt if \var{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}
\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}
\defun{copy-port->port-binary}{input-port oputput-port}{undefined}
\defunx{copy-port->port-ascii}{input-port oputput-port}{undefined}
\defunx{copy-ascii-port->port}{input-port oputput-port}{undefined}
\begin{desc}
These procedures are useful for downloading and uploading data to an
FTP connection via \ex{ftp-get}, \ex{ftp-get}, and \ex{ftp-append}.
They all copy data from one port to another.
\ex{Copy-port->port-binary} copies verbatim, while the other two
perform CR/LF conversion for ASCII data transfers.
\ex{Copy-port->port-ascii} adds CR/LFs at line endings on output,
whereas \ex{Copy-ascii-port->port} removes CR/LFs at line endings
end replaces them by ordinary LFs.
\end{desc}
%%% Local Variables:
%%% mode: latex