From 4bcf374d8ec2cc43f9427576d047a0b50a9c7dcd Mon Sep 17 00:00:00 2001 From: sperber Date: Thu, 16 Jan 2003 14:12:11 +0000 Subject: [PATCH] Reasonably complete and up-to-date docs for FTP. --- doc/latex/ftp.tex | 290 ++++++++++++++-------------------------------- 1 file changed, 86 insertions(+), 204 deletions(-) diff --git a/doc/latex/ftp.tex b/doc/latex/ftp.tex index 9156060..0246ae6 100644 --- a/doc/latex/ftp.tex +++ b/doc/latex/ftp.tex @@ -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 [ arg ] } -Replies from the server are of the form - \codex{xyz Informative message } -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- Start of multiline message -[ + More information ]* -xyz End of multiline message % -\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