xemacs-beta: man/efs.texi comparison

comparison man/efs.texi @ 42:8b8b7f3559a2 r19-15b104

Import from CVS: tag r19-15b104

author	cvs
date	Mon, 13 Aug 2007 08:54:51 +0200
parents
children	8d2a9b52c682

comparison

equal deleted inserted replaced

-:5d6df4963a99
+:8b8b7f3559a2
+\input texinfo   @c -*-texinfo-*-
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename efs.info
+@settitle EFS
+@comment %**end of header (This is for running Texinfo on a region.)
+@synindex fn vr
+@node Top, What is EFS?, (dir), (dir)
+@comment  node-name,  next,  previous,  up
+@ifinfo
+@unnumbered EFS
+This file documents EFS, a system for transparent file-transfer
+between remote hosts using the FTP protocol within Emacs.
+This info is for version 1.15 of EFS.
+Documentation version: 1.0
+Copyright @copyright{} 1991, 1992 Free Software Foundation, Inc.
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries a copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+@end ifinfo
+@titlepage
+@sp5
+@center @titlefont{EFS}
+@center version 1.15
+@sp2
+@center A transparent remote file system, by Sandy Rutherford and Andy Norman
+@sp7
+@center This documentation based on ange-ftp documentation by David Smith
+@center and on documentation in the EFS source code
+@center It was put together by Mike Sperber.
+This documentation is definitely incomplete and parts of it may be
+outright incorrect or out-of-date.
+@center info-version 1.0
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991, 1992 Free Software Foundation, Inc.
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+@end titlepage
+@menu
+* What is EFS?::
+* Installing EFS::              Where to find it, and how to use it.
+* Using EFS::                   EFS -- a users' guide.
+* Getting help::                Mailing lists and newsgroups.
+* Bugs::                        Known bugs, and a wish list.
+Indices:
+* Concept Index::
+* Variable and command index::
+@end menu
+@node What is EFS?, Installing EFS, Top, Top
+@comment  node-name,  next,  previous,  up
+@chapter Introducing EFS
+EFS is a system for transparent file-transfer between remote UNIX,
+Guardian, DOS, Macintosh, KA9Q, Netware, NOS/VE, Plan 9, TI Explorer,
+Twenex, TOPS 20, VOS, MPE, MVS, VMS, CMS or MTS hosts using FTP. This
+means that you can edit, copy and otherwise manipulate files on any
+machine you have access to from within Emacs as if it were a local
+file. EFS works by introducing an extended filename syntax, and
+overloading functions such as @code{insert-file-contents} so that
+accessing a remote file causes appropriate commands to be sent to an FTP
+process. EFS includes and enhanced version of Dired to facilitate
+directory browsing and multiple file transfer from remote hosts.
+The authors of EFS are Sandy Rutherford (@code{sandy@@math.ubc.ca}) and
+Andy (Ange) Norman (@code{ange@@hplb.hpl.hp.com}).  EFS is partly based
+on an earlier package called ange-ftp.  The integration of EFS 1.15 into
+XEmacs and numerous bug fixes were done by Mike Sperber
+(@code{sperber@@informatik.uni-tuebingen.de}).
+@ifinfo
+Many people have sent in enhancements for ange-ftp and EFS.
+Members of the ange-ftp and EFS Hall of Fame include:
+@itemize @bullet
+@item
+Many thanks to Roland McGrath for improving the filename syntax handling,
+for suggesting many enhancements and for numerous cleanups to the code.
+@item
+Thanks to Jamie Zawinski for bugfixes and for ideas such as gateways.
+@item
+Thanks to Ken Laprade for improved @file{.netrc} parsing and password
+reading, and Dired/shell autoloading.
+@item
+Thanks to Sebastian Kremer for tree dired support and for many ideas and
+bugfixes.
+@item
+Thanks to Joe Wells for bugfixes, non-UNIX system support, VOS support,
+and hostname completion.
+@item
+Thanks to Nakagawa Takayuki for many good ideas, filename-completion, help
+with file-name expansion, efficiency worries, stylistic concerns and many
+bugfixes.
+@item
+Also, thanks to Rob Austein, Doug Bagley, Andy Caiger, Jim Franklin,
+Noah Friedman, Aksnes Knut-Havard, Elmar Heeb, John Interrante, Roland
+McGrath, Jeff Morgenthaler, Mike Northam, Jens Petersen, Jack Repenning,
+Joerg-Martin Schwarz, Michael Sperber, Svein Tjemsland, Andy Whitcroft,
+Raymond A. Wiker and many others whose names have been forgotten who
+have helped to debug and fix problems.
+@end itemize
+@end ifinfo
+Finally, this info file was put together by Mike Sperber
+(@code{sperber@@informatik.uni-tuebingen.de}) from an ange-ftp info file
+written by Dave Smith (@code{dsmith@@stats.adelaide.edu.au}) and the EFS
+source code.
+@node Installing EFS, Using EFS, What is EFS?, Top
+@comment  node-name,  next,  previous,  up
+@chapter Installing EFS
+At the time of writing of this documentation, the version of EFS
+distributed with XEmacs (this means the EFS running on XEmacs
+19.15/20.1) is the latest version available.  It includes many bugfixes
+and some enhancements over the last separately released version of EFS,
+1.15.  This situation will change once a new version of EFS is
+available.
+Generally, EFS is pretty easy to get hold of. FTP is the probably the
+simplest method, but other options such as mail are available.
+Once you have the Emacs-Lisp source, there are a few customisations you
+might need to make. The ideal configuration is to have the FTP process running
+on the same machine as you are running Emacs on, but this is not always
+possible since some machines cannot access hosts outside the local
+network. In this case, the FTP process needs to be run on a machine
+which @emph{does} have access to the local world --- this is called the
+@strong{gateway host}. EFS has facilities to make use of a
+gateway host when accessing remote hosts.
+@menu
+* Obtaining source code::       Where to find the EFS source.
+* Installing source::           Where to put it, how to load it.
+* Using a gateway::             If your local machine has limited access.
+* Setting up a gateway::
+* Gateway types::
+* Gateway problems::
+* Other options::               More user variables to twiddle.
+@end menu
+@node Obtaining source code, Installing source, Installing EFS, Installing EFS
+@section How to get the EFS source code
+@comment  node-name,  next,  previous,  up
+The latest separately distributed version of EFS should always be
+available from Andy Norman's home page at
+@example
+http://www-uk.hpl.hp.com/people/ange/efs
+@end example
+There are also some ftp locations:
+@table @b
+@item Switzerland
+@example
+/anonymous@@itp.ethz.ch:/sandy/efs/
+@end example
+@item Massachusetts, USA
+@example
+/anonymous@@alpha.gnu.ai.mit.edu:/efs/
+@end example
+@item California, USA
+@example
+/anonymous@@ftp.hmc.edu:/pub/emacs/packages/efs/
+@end example
+@end table
+Failing these, someone on the EFS mailing list (@xref{Getting help}) may
+be able to help you find the latest version.
+@node Installing source, Using a gateway, Obtaining source code, Installing EFS
+@comment  node-name,  next,  previous,  up
+@section Installing the source
+For byte compiling the EFS package, a @file{Makefile} is provided.  You
+should follow the instructions at the top of the @file{Makefile}.  If
+you have any problems, please let us know so that we can fix them for
+other users. Don't even consider using eFS without byte compiling it. It
+will be far too slow.
+If you decide to byte compile efs by hand, it is important that the file
+@file{efs-defun.el} be byte compiled first, followed by @file{efs.el}.
+The other files may be byte compiled in any order.
+To use EFS, simply put the byte compiled files in your load path
+and add
+@example
+(require 'efs)
+@end example
+in your @file{.emacs} file.  Note this takes awhile, and some users have
+found this to be unbearably slow.  Therefore ...
+If you would like efs to be autoloaded when you attempt to access
+a remote file, put
+@example
+(require 'efs-auto)
+@end example
+in your @file{.emacs} file. Note that there are some limitations associated
+with autoloading EFS. A discussion of them is given at the top of
+@file{efs-auto.el}.
+Note that, in XEmacs, EFS automatically loads @file{efs-auto} when the
+user accesses a remote file.  Therefore, no additional @code{require}
+statements should be necessary to use EFS.  Just fire away ...
+The above instructions should allow you to access all hosts that your
+local machine can access. If your local host has limited access,
+however, you may wish to have EFS working through a gateway
+machine. If so, read on. Otherwise, @xref{Using EFS} to get started
+using EFS.
+@node Using a gateway, Setting up a gateway, Installing source, Installing EFS
+@comment  node-name,  next,  previous,  up
+@section Using a gateway
+Sometimes it is necessary for the FTP process to be run on a different
+machine than the machine running Emacs.  This can happen when the
+local machine has restrictions on what hosts it can access.
+Suppose you are running Emacs (and EFS, of course) on a machine X
+(let's call it the `local host') and you want to access a file on a
+machine Z (which we will call the `remote host'). Unfortunately, X does
+not have FTP access to Z: when you try a manual FTP something like
+the following happens:
+@example
+X$ ftp Z.foo.bar.com
+ftp: connect: Host is unreachable
+@end example
+@noindent
+However, X @emph{does} have access to a machine Y (the `gateway
+machine') which @emph{can} access Z. Fortunately, you have an account on
+the gateway machine, and so the solution is to login to Y, ftp to Z,
+download the file you want from Z to Y, and then copy it from Y to the
+local host, X. This can get a bit tedious, to say the least, but
+fortunately EFS can do all the hard work for you.
+@node Setting up a gateway, Gateway types, Using a gateway, Installing EFS
+@comment  node-name,  next,  previous,  up
+@section Setting up a gateway
+@enumerate
+@item
+Set the variable @code{efs-gateway-host} to the name of a machine
+@vindex efs-gateway-host
+that doesn't have the access restrictions.  If you need to use a
+nonstandard port to access this host for gateway use, then specify
+@code{efs-gateway-host} as @code{<hostname>#<port>}.
+@item
+Set the variable @code{efs-ftp-local-host-regexp} to a regular
+expression
+@vindex efs-ftp-local-host-regexp
+that matches hosts that can be contacted from running a local ftp
+process, but fails to match hosts that can't be accessed locally.
+For example:
+@example
+"\\.hp\\.com$\\|^[^.]*$"
+@end example
+will match all hosts that are in the @t{.hp.com} domain, or don't have
+an explicit domain in their name, but will fail to match hosts with
+explicit domains or that are specified by their ip address.
+@item
+Set the variable @code{efs-local-host-regexp} to machines that you have
+@vindex efs-local-host-regexp
+direct TCP/IP access.  In other words, you must be able to ping these
+hosts.  Usually, @code{efs-ftp-local-host-regexp} and
+@code{efs-local-host-regexp} will be the same.  However, they will
+differ for so-called transparent gateways.  See below for more
+details.
+@item
+Set the variable @code{efs-gateway-tmp-name-template} to the name of
+@vindex efs-gateway-tmp-name-template
+a directory plus an identifying filename prefix for making temporary
+files on the gateway.  For example: @code{"/tmp/hplose/ange/efs"}
+@item
+If the gateway and the local host share cross-mounted directories,
+set the value of @code{efs-gateway-mounted-dirs-alist} accordingly. It
+@vindex efs-gateway-mounted-dirs-alist
+is particularly useful, but not mandatory, that the directory
+of @code{efs-gateway-tmp-name-template} be cross-mounted.
+@vindex efs-gateway-tmp-name-template
+@item
+Set the variable @code{efs-gateway-type} to the type gateway that you have.
+This variable is a list, the first element of which is a symbol
+denoting the type of gateway.
+@end enumerate
+@node Gateway types, Gateway problems, Setting up a gateway, Installing EFS
+@comment  node-name,  next,  previous,  up
+@section Supported gateway types
+@vindex efs-gateway-type
+@table @samp
+@item local
+This means that your local host is itself the gateway.  However,
+it is necessary to use a different FTP client to gain access to
+the outside world.  If the name of the FTP client were @t{xftp}, you might
+set @code{efs-gateway-type} to
+@example
+(list 'local "xftp" efs-ftp-program-args)
+@end example
+If @t{xftp} required special arguments, then give them in place of
+@t{efs-ftp-program-args}.
+@vindex efs-ftp-program-args
+@item proxy
+This indicates that your gateway works by first FTP'ing to it, and
+then issuing a @code{USER} command of the form
+@example
+USER <username>@@<host>
+@end example
+In this case, you might set @code{efs-gateway-type} to
+@example
+(list 'proxy "ftp" efs-ftp-program-args)
+@end example
+If you need to use a nonstandard client, such as @t{iftp}, give this
+@pindex iftp
+instead of @t{ftp}.  If this client needs to take special arguments,
+give them instead of @t{efs-ftp-program-args}.
+@item remsh
+For this type of gateway, you need to start a remote shell on
+your gateway, using either @t{remsh} or @t{rsh}.  You should set
+@pindex remsh
+@pindex rsh
+@sc{efs-gateway-type} to something like
+@example
+(list 'remsh "remsh" nil "ftp" efs-ftp-program-args)
+@end example
+If you use @t{rsh} instead of @r{remsh}, change the second element from
+@code{"remsh"} to @code{"rsh"}.  Note that the symbol indicating the gateway
+type should still be @code{'remsh}.  If you want to pass arguments
+to the remsh program, give them as the third element.  For example,
+if you need to specify a user, make this @code{(list "-l" "sandy")}.
+If you need to use a nonstandard FTP client, specify that as the fourth
+element.  If your FTP client needs to be given special arguments,
+give them instead of @code{efs-ftp-program-args}.
+@item interactive
+This indicates that you need to establish a login on the gateway,
+using either @t{telnet} or @t{rlogin}.
+@pindex telnet
+@pindex rlogin
+You should set @code{efs-gateway-type} to something like
+@example
+(list 'interactive "rlogin" nil "exec ftp" efs-ftp-program-args)
+@end example
+If you need to use @t{telnet}, then give @code{"telnet"} in place of the second
+element @code{"rlogin"}.  If your login program needs to be given arguments,
+then they should be given in the third slot.  The fourth element
+is for the name of the FTP client program.  Giving this as @code{"exec ftp"},
+instead of @code{"ftp"}, ensures that you are logged out if the FTP client
+dies.  If the FTP client takes special arguments, give these instead
+of @code{efs-ftp-program-args}.  Furthermore, you should see the documentation
+at the top of @file{efs-gwp.el}.  You may need to set the variables
+@code{efs-gwp-setup-term-command}, and @code{efs-gwp-prompt-pattern}.
+@vindex efs-gwp-setup-term-command
+@vindex efs-gwp-prompt-pattern
+@item raptor
+This is a type of gateway where efs is expected to specify a gateway
+user, and send a password for this user using the @code{ACCOUNT} command.
+For example, to log in to @samp{foobar.edu} as sandy, while using the account
+ange on the gateway, the following commands would be sent:
+@example
+open raptorgate.com
+quote USER sandy@@foobar.edu ange
+quote pass <sandy's password on foobar>
+quote account <ange's password on raptorgate>
+@end example
+For such a gateway, you would set @code{efs-gateway-type} to
+@example
+(list 'raptor efs-ftp-program efs-ftp-program-args <GATEWAY USER>)
+@end example
+where @code{<GATEWAY USER>} is the name of your account on the gateway.  In
+the above example, this would be @code{"ange"}.  You can set your gateway
+password by simply setting an account password for the gateway host.
+This can be done with either efs-set-account, or within your .netrc
+file.  If no password is set, you will be prompted for one.
+@item interlock
+This is a type of gateway where you are expected to send a PASS
+command after opening the connection to the gateway.
+The precise login sequence is
+@example
+open interlockgate
+quote PASS <sandy's password on interlockgate>
+quote USER sandy@@foobar.edu
+quote PASS <sandy's password on foobar.edu>
+@end example
+For such a gateway, you should set @code{efs-gateway-type} to
+@example
+(list 'interlock efs-ftp-program efs-ftp-program-args)
+@end example
+If you need to use a nonstandard name for your FTP client,
+then replace @code{efs-ftp-program} with this name.  If your FTP client
+needs to take nonstandard arguments, then replace @code{efs-ftp-program-args}
+with these arguments.
+If your gateway returns both a 220 code and a 331 code to the
+@code{"open interlockgate"} command, then you should add a regular
+expression to @code{efs-skip-msgs} that matches the 220 response.
+Returning two response codes to a single FTP command is not permitted
+in RFC 959.  It is not possible for efs to ignore the 220 by default,
+because than it would hang for interlock installations which do not
+require a password.
+@item kerberos
+With this gateway, you need to authenticate yourself by getting a
+kerberos "ticket" first.  Usually, this is done with the kinit program.
+Once authenticated, you connect to @samp{foobar.com} as user sandy with the
+sequence: (Note that the @code{"-n"} argument inhibits automatic login.
+Although, in manual use you probably don't use it, EFS always uses it.)
+@example
+iftp -n
+open foobar.com
+user sandy@@foobar.com
+@end example
+@pindex iftp
+You should set @code{efs-gateway-type} to something like
+@example
+(list 'kerberos "iftp" efs-ftp-program-args "kinit" <KINIT-ARGS>)
+@end example
+If you use an FTP client other than @t{iftp}, insert its name instead of
+@code{"iftp"} above.  If your FTP client needs special arguments, give
+them as a list of strings in place of @code{efs-ftp-program-args}.  If
+the program that you use to collect a ticket in not called
+@code{"kinit"}, then give its name in place of @code{"kinit"} above.
+@code{<KINIT-ARGS>} should be any arguments that you need to pass to
+your kinit program, given as a list of strings.  Most likely, you will
+give this as nil.
+See the file @file{efs-kerberos.el} for more configuration variables.  If you
+need to adjust any of these variables, please report this to us so that
+we can fix them for other users.
+If EFS detects that you are not authenticated to use the gateway, it
+will run the kinit program automatically, prompting you for a password.
+If you give a password in your @file{.netrc} file for login the value of
+@code{efs-gateway-host} and user @t{kerberos}, then EFS will use this to
+obtain gateway authentication.
+@item Transparent gateways
+If your gateway is completely transparent (for example it uses socks),
+then you should set @code{efs-gateway-type} to @code{nil}.  Also, set
+@code{efs-ftp-local-host-regexp} to @code{".*"}.  However,
+@code{efs-local-host-regexp}, must still be set to a regular expression
+matching hosts in your local domain.  EFS uses this to determine which
+machines that it can open-network-stream to.  Furthermore, you should
+still set @code{efs-gateway-host} to the name of your gateway machine.
+That way EFS will know that this is a special machine having direct
+TCP/IP access to both hosts in the outside world, and hosts in your
+local domain.
+@end table
+@node Gateway problems, Other options, Gateway types, Installing EFS
+@comment  node-name,  next,  previous,  up
+@section Common Problems with Gateways
+@subsection Spurious 220 responses
+Some proxy-style gateways (eg gateway type @code{'proxy} or @code{'raptor}),
+return two 3-digit FTP reply codes to the @code{USER} command.
+For example:
+@example
+open gateway.weird
+220 Connected to gateway.weird
+quote USER sandy@@foobar
+220 Connected to foobar
+331 Password required for sandy
+@end example
+This is wrong, according to the FTP Protocol.  Each command must return
+exactly one 3-digit reply code.  It may be preceded by continuation
+lines.  What should really be returned is:
+@example
+quote USER sandy@@foobar
+331-Connected to foobar.
+331 Password required for sandy.
+@end example
+or even
+@example
+quote USER sandy@@foobar
+331-220 Connected to foobar.
+331 Password required for sandy.
+@end example
+Even though the @samp{"331-220"} looks strange, it is correct protocol,
+and EFS will parse it properly.
+If your gateway is returning a spurious 220 to @code{USER}, a work-around
+is to add a regular expression to @code{efs-skip-msgs} that matches
+@vindex efs-skip-msgs
+this line.  It must not match the 220 line returned to the open
+command.  This work-around may not work, as some system FTP clients
+also get confused by the spurious 220.  In this case, the only
+solution is to patch the gateway server.  In either case, please
+send a bug report to the author of your gateway software.
+@subsection Case-sensitive parsing of FTP commands
+Some gateway servers seem to treat FTP commands case-sensitively.
+This is incorrect, as RFC 959 clearly states that FTP commands
+are always to be case-insensitive.  If this is a problem with your
+gateway server, you should send a bug report to its author.
+If efs is using a case for FTP commands that does not suit your server,
+a possible work-around is to edit the efs source so that the required
+case is used.  However, we will not be making any changes to the
+standard EFS distribution to support this type of server behaviour.
+If you need help changing the efs source, you should enquire with the
+efs-help mailing list.
+@node Other options,  , Gateway problems, Installing EFS
+@comment  node-name,  next,  previous,  up
+@section Other user options
+Here are other user options available in EFS:
+@code{efs-netrc-filename}: The name of a file in @code{netrc(5)}
+format that EFS will use to match hostnames, users and their
+respective passwords.  Hostnames specified here are also used for hostname
+completion.
+The default is @code{"~/.netrc"}.
+@vindex efs-netrc-filename
+@code{efs-default-user}: If this is a string, it is the username to
+use when none is specified in a filename. If @code{nil}, then the
+name under which the user is logged in is used. If non-@code{nil} but
+not a string, the user is prompted for the name. The default is @code{nil}.
+@vindex efs-default-user
+@code{efs-default-password}: The password to use when the user is the
+same as @code{efs-default-user}. The default is @code{nil}.
+@vindex efs-default-password
+@code{efs-default-account}: Account password to use when the user
+is the same as @code{efs-default-user}. The default is @code{nil}.
+@vindex efs-default-account
+@code{efs-dumb-unix-host-regexp}: The FTP servers on some machines have
+problems if the @code{ls} command is used. The usual indication that
+something is wrong is when EFS erroneously thinks that a directory
+is just a plain file. The routine @code{efs-add-host} can
+be called to tell EFS to limit itself to the @code{DIR} command and
+not @code{ls} for a given host (but this change will take effect for the
+current Emacs session only) when called like this:
+@example
+(efs-add-host 'dumb-unix "hostname")
+@end example
+If a large number of machines with similar hostnames have this problem
+then it is easier to change the value of this variable to a regexp which
+matches hostnames which have this problem, particularly since EFS cannot
+automatically detect such hosts. The default is @code{nil}.
+@vindex efs-dumb-unix-host-regexp
+@findex efs-add-host
+@code{efs-binary-file-name-regexp}: By default EFS will
+transfer files in ASCII mode. If a file being transferred matches the
+value of this regexp then the FTP process will be toggled into BINARY
+mode before the transfer and back to ASCII mode after the transfer. The
+default is:
+@example
+(concat "\\." ; the dot
+	  ;; extensions
+	  "\\([zZ]\\|t?gz\\|lzh\\|arc\\|zip\\|zoo\\|ta[rz]\\|dvi\\|sit\\|"
+	  "ps\\|elc\\|gif\\|Z-part-..\\|tpz\\|exe\\|[jm]pg\\|TZ[a-z]?\\|lib\\)"
+	  "\\(~\\|~[0-9]+~\\)?$" ; backups
+	  "\\|"
+	  ;; UPPER CASE LAND
+	  "\\."
+	  "\\(ARC\\|ELC\\|TAGS\\|EXE\\|ZIP\\|DVI\|ZOO\\|GIF\\|T?GZ\\|"
+	  "[JM]PG\\)"
+	  "\\([.#;][0-9]+\\)?$" ; versions
+	  )
+@end example
+@vindex efs-binary-file-name-regexp
+@code{efs-hash-mark-size}: EFS by default requests that the
+FTP process sends hash marks (just @code{#} characters) during transfers
+to keep track of how much data has been sent or received. This variable,
+if non-@code{nil}, should be the number of kilobytes represented by the
+FTP client's hash mark. The default value of 1 doesn't work for me --- I
+use 2 instead.
+@vindex efs-hash-mark-size
+@code{efs-verbose}: If this is @code{t} then EFS will be chatty about
+interaction with the FTP process. The default is @code{t}.
+@vindex efs-process-verbose
+@code{efs-ftp-program-name}: This should be the name of the FTP
+program to run on the local host. The default value of @code{"ftp"}
+should be fine for most systems.
+@vindex efs-ftp-program-name
+@code{efs-make-backup-files}: A list of operating systems for which
+EFS will make Emacs backup files on the remote host. For example,
+@code{'(unix)} makes sense, but @code{'(unix vms)} or @code{'(vms)}
+would be silly, since VMS makes its own backups.  The host type is
+determined by the function @code{efs-host-type}.  Possible host
+types are: @code{dumb-unix}; @code{vos}; @code{vms}; @code{mts}; and
+@code{unix}. The default of @code{nil} means make no backups on remote
+hosts.
+@vindex efs-make-backup-files
+@cindex backup files
+@code{efs-skip-msgs}: A regular expression matching messages from
+the ftp process that can be ignored. The default is
+@example
+(concat
+"^110 \\|" ; Restart marker reply.
+"^125 \\|" ; Data connection already open; transfer starting.
+"^150 ") ; File status OK; about to open connection.
+@end example
+@noindent
+but you might need to tweak it if EFS is giving up when it
+shouldn't.
+@vindex efs-skip-msgs
+@code{efs-fatal-msgs}: A regular expression matching messages from
+the FTP process that indicate something has gone drastically wrong
+attempting the action that was initiated and that the FTP process should
+(or already has) been killed. The default is
+@example
+(concat
+;; RFC959 codes
+"^221 \\|" ; Service closing control connection.
+"^421 \\|" ; Service not available.
+"^425 \\|" ; Can't open data connection.
+"^426 \\|" ; Connection closed, transfer aborted.
+"^451 \\|" ; Requested action aborted, local error in processing.
+;; RFC959 non-compliant codes
+"^552 Maximum Idle Time Exceded\\.$\\|" ; Hellsoft server uses this to
+					   ; indicate a timeout. 552 is
+					   ; supposed to be used for exceeded
+					   ; storage allocation. Note that
+					   ; they also misspelled the error
+					   ; message.
+;; client problems
+"^ftp: \\|^Not connected\\|^rcmd: \\|^No control connection\\|"
+"^unknown host\\|: unknown host$\\|^lost connection\\|"
+"^[Ss]egmentation fault\\|"
+;; Make sure that the "local: " isn't just a message about a file.
+"^local: [^/]\\|"
+;; Gateways
+"^iftp: cannot authenticate to server\\b"
+)
+@end example
+@vindex efs-fatal-msgs
+@code{efs-gateway-fatal-msgs}: Regular expression matching messages
+from the rlogin / telnet process that indicates that logging in to the
+gateway machine has gone wrong. The default is
+@example
+"No route to host\\|Connection closed\\|No such host\\|Login incorrect"
+@end example
+@vindex efs-gateway-fatal-msgs
+@code{efs-tmp-name-template}: This should be a directory and a
+filename prefix indicating where EFS should make temporary files.
+The default of @code{"/tmp/efs"} should be fine for most systems.
+@vindex efs-tmp-name-template
+@cindex temporary files
+@code{efs-retry-time}: Number of seconds to wait before retrying if
+a file or listing doesn't arrive. For slow connections, you might get a
+``listing unreadable'' error messages
+@cindex listing unreadable error
+or an empty buffer for a file that you know has something in it.  The
+solution is to increase the value of @code{efs-retry-time}.  Its default
+value is 5 which is plenty for reasonable connections.  However, for
+some transatlantic connections 20 might be a better value.
+@vindex efs-retry-time
+@node Using EFS, Getting help, Installing EFS, Top
+@comment  node-name,  next,  previous,  up
+@chapter Using EFS
+Once installed, efs operates largely transparently. All files normally
+accessible to you on the internet, become part of a large virtual file
+system. These files are accessed using an extended file name syntax. To
+access file @code{<path>} on remote host @code{<host>} by logging in as
+user @code{<user>}, you simply specify the full path of the file as
+@code{/<user>@@<host>:<path>}. Nearly all Emacs file handling functions
+work for remote files. It is not possible to access remote files using
+shell commands in an emacs *shell* buffer, as such commands are passed
+directly to the shell, and not handled by emacs.
+FTP is the underlying utility that efs uses to operate on remote files.
+For example, if @code{find-file} is given a filename of:
+@example
+/ange@@anorman:/tmp/notes
+@end example
+then EFS will spawn an FTP process, connect to the host 'anorman' as
+user 'ange', get the file @file{/tmp/notes} and pop up a buffer containing the
+contents of that file as if it were on the local file system.  If efs
+needed a password to connect then it would prompt the user in the
+minibuffer. For further discussion of the EFS path syntax, see the
+paragraph on extended file name syntax @ref{Remote filenames}.
+Full file-name completion is supported on every type of remote host.  To
+do filename completion, EFS needs a listing from the remote host.
+Therefore, for very slow connections, it might not save any
+time. However, the listing is cached, so subsequent uses of file-name
+completion will be just as fast as for local file names.
+@menu
+* Ports::                       Using nonstandard ports.
+* Remote filenames::            The EFS extended filename syntax.
+* Passwords::
+* Using Dired::                 Browsing directories.
+* Using a .netrc::              Preventing password pestering.
+* EFS commands::                Interactive commands supplied by EFS.
+* FTP processes::               How EFS does its work
+* Tips::                        Some stuff to help you use EFS
+* DL support::                  Descriptive directory listings
+* Non-Unix Hosts::              Some of what you want to know
+* Completion::                  Works but has its price
+* Accessing the FTP process::   ... manually
+@end menu
+@node Ports, Remote filenames, Using EFS, Using EFS
+@comment  node-name,  next,  previous,  up
+@section Using nonstandard ports
+EFS supports the use of nonstandard ports on remote hosts.  To specify
+that port @code{<port>} should be used, give the host name as
+@code{host#<port>}. Host names may be given in this form anywhere that
+efs normally expects a host name. This includes in the @file{.netrc} file.
+Logically, EFS treats different ports to correspond to different remote
+hosts.
+@node Remote filenames, Passwords, Ports, Using EFS
+@comment  node-name,  next,  previous,  up
+@section Extended filename syntax
+The default full EFS path syntax is
+@example
+/<user>@@<host>#<port>:<path>
+@end example
+Both the @code{#<port>'}and @code{<user>@@} may be omitted.
+If the @code{#<port>} is omitted, then the default port is taken to be 21,
+the usual FTP port. For most users, the port syntax will only
+very rarely be necessary.
+If the @code{<user>@@} is omitted, then EFS will use a default user.  If
+a login token is specified in your @file{.netrc} file, then this will be
+used as the default user for @code{<host>}.  Otherwise, it is determined
+based on the value of the variable @code{efs-default-user}.
+@vindex{efs-default-user}
+This EFS path syntax can be customised to a certain extent by changing a
+number of variables.  To
+undertake such a customization requires some knowledge about the
+internal workings of EFS.
+@node Passwords, Using Dired, Remote filenames, Using EFS
+@comment  node-name,  next,  previous,  up
+@section Passwords
+A password is required for each host / user pair.  This will be prompted
+for when needed, unless already set by calling @code{efs-set-passwd},
+@findex{efs-set-passwd} or specified in a @emph{valid} @file{~/.netrc}
+file.
+When EFS prompts for a password, it provides defaults from its cache of
+currently known passwords.  The defaults are ordered such that passwords
+for accounts which have the same user name as the login which is
+currently underway have priority. You can cycle through your list of
+defaults with @kbd{C-n} to cycle forwards and @kbd{C-p} to cycle
+backwards. The list is circular.
+@subsection Passwords for user @t{anonymous}
+Passwords for the user @t{anonymous} (or @t{ftp}) are handled specially.
+The variable @code{efs-generate-anonymous-password} controls what
+\vindex efs-generate-anonymous-password happens. If the value of this
+variable is a string, then this is used as the password; if
+non-@code{nil}, then a password is created from the name of the user and
+the hostname of the machine on which Emacs is running; if @code{nil}
+(the default) then the user is prompted for a password as normal.
+@subsection Account passwords
+Some FTP servers require an additional password which is sent by the
+@code{ACCOUNT} command.  EFS will detect this and prompt the user for an
+account password if the server expects one.  Also, an account password
+can be set by calling @code{efs-set-account}, or by specifying an
+@findex efs-set-account
+account token in the @file{.netrc} file.
+Some operating systems, such as CMS, require that @code{ACCOUNT} be used
+to give a write access password for minidisks.  @code{efs-set-account} can be
+used to set a write password for a specific minidisk. Also, tokens of
+the form
+@example
+minidisk <minidisk name> <password>
+@end example
+may be added to host lines in your @file{.netrc} file. Minidisk tokens
+must be at the end of the host line, however there may be an arbitrary
+number of them for any given host.
+@node Using Dired, Using a .netrc, Passwords, Using EFS
+@comment  node-name,  next,  previous,  up
+@section Using Dired
+This feature of EFS is particularly useful when file transfers, as
+opposed to file editing, are the order of the day. Simply run
+@code{find-file} on a directory to
+get a listing of the files in that directory. For example, you might
+run @code{find-file} on
+@example
+/anonymous@@archive.site.com:pub
+@end example
+@noindent
+to see what's in the @file{pub} directory of your favourite archive
+@cindex archive sites
+site. This brings up a Dired buffer of all the files in that directory.
+The @kbd{f} command is useful for looking at @file{README} files --- if
+you then decide to save it @kbd{C-x C-w} is useful. You can also use
+this method to copy files, but the @kbd{c} command is easier. The
+@kbd{f} command can also be used to descend the directory tree by
+applying it to directories.
+You can also use Dired to refresh EFS's internal cache. If you
+(or anybody else) has changed a remote directory since you first accessed it
+with EFS, completion is not provided on any new files that EFS
+does not know about. If you have
+(or create) a Dired buffer which contains the modified directory,
+executing @code{revert-buffer}
+@findex revert-buffer
+with a prefix argument (@kbd{C-u g} in the Dired buffer)
+will force a refresh of both the the buffer @emph{and also EFS's
+internal cache}. If you find that filename completion isn't working on a
+@cindex filename completion
+file that you @emph{know} is there, this is how to fix the problem.
+Dired provides facilities for maintaining an
+entire directory tree in a Dired buffer, for marking files which match a
+certain regexp (or you can select files interactively) and then copying
+all those files to your local host (or even a different remote host).
+Another useful feature is Virtual Dired, which allows you to save Dired
+@cindex virtual dired
+buffers of remote hosts, allowing you to browse them at a later date
+without actually needing to connect to the host.
+@node Using a .netrc, EFS commands, Using Dired, Using EFS
+@comment  node-name,  next,  previous,  up
+@section Using a .netrc file
+Being prompted for passwords all the time can get rather annoying, but
+there is a way to fix the problem --- a @file{.netrc} (but @xref{Other
+options} and @code{efs-netrc-filename}
+@vindex efs-netrc-filename
+if you want another
+filename) file in your home directory. Basically, this is a file (in the
+format of Unix @code{netrc(5)}) which
+contains the names of all the machines you regularly login to, as well
+as the username and password you use for that machine. You can also
+supply an account password, if required.
+Your @file{.netrc} file consists of lines of the form
+@example
+machine <machine-name> login <user-name> password <password>
+@end example
+@noindent
+It doesn't all have to be on the one line, though: any @code{login} or
+@code{password} commands in the file refer to the previous
+@code{machine} command. You can also have @code{account
+<account-passwd>} commands if you need special account passwords.
+For example, you might have the following line in your @file{.netrc}:
+@example
+machine Y.local.lan.edu login myname password secret
+@end example
+@noindent
+Then if you run @code{find-file} on the file @file{/Y.local.lan.edu:somefile}
+you will automatically be logged in as user @code{myname} with password
+@code{secret}. You can still login under another name and password, if
+you so desire: just include the @code{user@@} part of the filename.
+You may also include a default option, as follows:
+@example
+default login <user-name> password <password>
+@end example
+@noindent
+which applies to any other machines not mentioned elsewhere in your
+@file{.netrc}. A particularly useful application of this is with
+anonymous logins:
+@cindex anonymous FTP
+@example
+default login myname password myname@@myhost.edu
+@end example
+@noindent
+so that accessing @file{/anyhost:anyfile} will automatically log you in
+anonymously, provided the host is not mentioned in the @file{.netrc}.
+Note also that if the value of @code{efs-default-user} is
+@vindex efs-default-user
+non-@code{nil}, its value will have precedence over the username
+supplied in the default option of the @file{.netrc}.
+The @file{.netrc} file is also useful in another regard: machines
+included in it are provided with hostname completion. That is, for any
+@cindex hostname completion
+machine in the @file{.netrc}, you need only type a slash and the first
+few characters of its name and then press @key{TAB} to be logged in
+automatically with a username and password from the @file{.netrc} file.
+So it's a good idea to put hosts you use regularly in your @file{.netrc}
+as well:
+@example
+machine archive.site.com login anonymous password myname@@X.local.lan.edu
+@end example
+@node EFS commands, FTP processes, Using a .netrc, Using EFS
+@comment  node-name,  next,  previous,  up
+@section EFS commands
+EFS supplies a few interactive commands to make connecting with
+hosts a little easier.
+@noindent
+Command @code{efs-set-user}: Prompts for a hostname and a username.
+Next time access to the host is attempted, EFS will attempt to log
+in again with the new username.
+@findex efs-set-user
+@noindent
+Command @code{efs-set-passwd}: Prompts for a hostname, user and
+password. Future logins to that host as that user will use the given
+password.
+@findex efs-set-passwd
+@noindent
+Command @code{efs-set-account}: Prompts for a hostname, user and
+account. Future logins to that host as that user will use the given
+account.
+@findex efs-set-account
+Note that the effects of the above three commands only last the duration
+of the current Emacs session. To make their effects permanent, you may
+include them as lisp code in your @file{.emacs}:
+@example
+(efs-set-user HOST USER)
+(efs-set-password HOST USER PASSWORD)
+(efs-set-account HOST USER ACCOUNT)
+@end example
+@noindent
+This is an alternative to using a @file{.netrc}; @xref{Using a .netrc}.
+@noindent
+Command @code{efs-kill-ftp-process}: kill the FTP process
+associated with a given buffer's filename (by default the current
+buffer). This is an easy way to achieve a resynch: any future accesses
+to the remote host will cause the FTP process to be recreated.
+@findex efs-kill-ftp-process
+@node FTP processes, Tips, EFS commands, Using EFS
+@comment  node-name,  next,  previous,  up
+@section FTP processes
+When EFS starts up an FTP process, it leaves it running for speed
+purposes.  Some FTP servers will close the connection after a period of
+time, but EFS should be able to quietly reconnect the next time that
+the process is needed.
+The FTP process will be killed should the associated @samp{*ftp user@@host*}
+buffer be deleted.  This should not cause efs any grief.
+@subsection Showing background FTP activity on the mode-line
+After EFS is loaded, the command @code{efs-display-ftp-activity} will cause
+@findex efs-display-ftp-activity
+background FTP activity to be displayed on the mode line. The variable
+@code{efs-mode-line-format} is used to determine how this data is displayed.
+@vindex efs-mode-line-format
+efs does not continuously track the number of active sessions, as this
+would cause the display to change too rapidly. Rather, it uses a heuristic
+algorithm to determine when there is a significant change in FTP activity.
+@subsection File types
+By default EFS will assume that all files are ASCII. If a file
+being transferred matches the value of @code{efs-binary-file-name-regexp}
+@vindex efs-binary-file-name-regexp
+then the file will be assumed to be a binary file, and EFS will
+transfer it using "type image". ASCII files will be transferred
+using a transfer type which efs computes to be correct according
+to its knowledge of the file system of the remote host. The
+command @code{efs-prompt-for-transfer-type} toggles the variable
+@findex efs-prompt-for-transfer-type
+@code{efs-prompt-for-transfer-type}. When this variable is
+@vindex efs-prompt-for-transfer-type
+non-@code{nil}, EFS will prompt the user for the transfer type to use
+for every FTP transfer.  Having this set all the time is annoying, but
+it is useful to give special treatment to a small set of files.  There
+is also a variable @code{efs-text-file-name-regexp}.  This is tested
+@vindex {efs-text-file-name-regexp}
+before @code{efs-binary-file-name-regexp}, so if you set
+@code{efs-text-file-name-regexp} to a non-trivial regular expression,
+and @code{efs-binary-file-name-regexp} to @samp{".*"}, the result will
+to make image the default tranfer type.
+Also, if you set @code{efs-treat-crlf-as-nl},
+@vindex efs-treat-crlf-as-nl
+then EFS will use type image
+to transfer files between hosts whose file system differ only in that
+one specifies end of line as CR-LF, and the other as NL.  This is useful
+if you are transferring files between UNIX and DOS machines, and have a
+package such as @file{dos-mode.el}, that handles the extra @key{^M}'s.
+@subsection Status reports
+Most EFS commands that talk to the FTP process output a status
+message on what they are doing.  In addition, efs can take advantage
+of the FTP client's @code{HASH} command to display the status of transferring
+files and listing directories.  See the documentation for the variables
+@code{efs-hash-mark-size},
+@vindex efs-hash-mark-size
+@code{efs-send-hash}
+@vindex efs-send-hash
+and @code{efs-verbose}
+@vindex efs-verbose
+for more details.
+@subsection Caching of directory information
+EFS keeps an internal cache of file listings from remote hosts.
+If this cache gets out of synch, it can be renewed by reverting a
+dired buffer for the appropriate directory (@code{dired-revert} is usually
+bound to @kbd{g}).
+Alternatively, you can add the following two lines to your @file{.emacs} file
+if you want @kbd{C-r} to refresh EFS's cache whilst doing filename
+completion.
+@example
+(define-key minibuffer-local-completion-map "\C-r" 'efs-re-read-dir)
+(define-key minibuffer-local-must-match-map "\C-r" 'efs-re-read-dir)
+@end example
+@node Tips, DL support, FTP processes, Using EFS
+@comment  node-name,  next,  previous,  up
+@section Tips for using EFS
+@enumerate
+@item
+Beware of compressing files on non-UNIX hosts. EFS will do it by
+copying the file to the local machine, compressing it there, and then
+sending it back. Binary file transfers between machines of different
+architectures can be a risky business. Test things out first on some
+test files. @xref{Bugs} Also, note that EFS sometimes
+copies files by moving them through the local machine. Again,
+be careful when doing this with binary files on non-Unix
+machines.
+@item
+Beware that dired over ftp will use your setting of
+@code{dired-no-confirm}
+@vindex dired-no-confirm
+(list of dired commands for which confirmation is not asked).
+You might want to reconsider your setting of this variable,
+because you might want confirmation for more commands on remote
+direds than on local direds. For example, I strongly recommend
+that you not include compress in this list. If there is enough
+demand it might be a good idea to have an alist
+@code{efs-dired-no-confirm} of pairs @code{( TYPE . LIST )}, where @code{TYPE} is an
+operating system type and @code{LIST} is a list of commands for which
+confirmation would be suppressed.  Then remote dired listings
+would take their (buffer-local) value of @code{dired-no-confirm} from
+this alist. Who votes for this?
+@item
+Some combinations of FTP clients and servers break and get out of sync
+when asked to list a non-existent directory.  Some of the @t{ai.mit.edu}
+machines cause this problem for some FTP clients. Using
+@code{efs-kill-ftp-process}
+@findex efs-kill-ftp-process
+can be used to restart the ftp process, which
+should get things back in synch.
+@item
+Some ftp servers impose a length limit on the password that can
+be sent. If this limit is exceeded they may bomb in an
+incomprehensible way. This sort of behaviour is common with
+MVS servers. Therefore, you should beware of this possibility
+if you are generating a long password (like an email address)
+with @code{efs-generate-anonymous-password}.
+@vindex efs-generate-anonymous-password
+@item
+Some antiquated FTP servers hang when asked for an @code{RNFR} command.
+EFS sometimes uses this to test whether its local cache is stale.
+If your server for @code{HOST} hangs when asked for this command, put
+@example
+(efs-set-host-property HOST 'rnfr-failed t)
+@end example
+in your @code{efs-ftp-startup-function-alist}
+@vindex efs-ftp-startup-function-alist
+entry for @code{HOST}.
+@item
+The FTP servers on some Unix machines have problems if the @code{ls}
+command is used.  EFS will try to correct for this automatically,
+and send the @code{dir} command instead.  If it fails, you can call the
+function @code{efs-add-host},
+@findex efs-add-host
+and give the host type as @code{dumb-unix}.  Note that this change will
+take effect for the current Emacs session only. To make this
+specification for future emacs sessions, put
+@example
+(efs-add-host 'dumb-unix "hostname")
+@end example
+in your @file{.emacs} file. Also, please report any failure to
+automatically recognize dumb unix to the "bugs" address given below, so
+that we can fix the auto recognition code.
+@end enumerate
+@node DL support, Non-Unix Hosts, Tips, Using EFS
+@comment  node-name,  next,  previous,  up
+@section Descriptive directory listings
+Some hosts (such as @code{cs.uwp.edu}) now use descriptive directory
+listings
+@cindex descriptive directory listings
+@cindex extended directory listings
+(which in fact contain @emph{less} information than the
+standard listing!) when issued the @code{ls} command, and EFS has
+been modified to cope with this. EFS can detect such listings, but
+if you regularly use a remote host which uses this extended listing
+format you should set the variable @code{efs-dl-dir-regexp} to a
+@vindex efs-dl-dir-regexp
+regular expression which matches directories using the extended listing
+format. You shouldn't anchor the regexp with @samp{$} -- that way the
+regexp will match subdirectories as well.  Alternatively, you can use
+the interactive command @code{efs-add-dl-dir} to temporarily add a
+@findex efs-add-dl-dir
+remote directory for this Emacs session only.
+Dired has been modified to work with such descriptive listings.
+@node Non-Unix Hosts, Completion, DL support, Using EFS
+@comment  node-name,  next,  previous,  up
+@section Using EFS with non-Unix hosts
+EFS also works with some non-Unix hosts, although not necessarily
+with all the features available with Unix hosts. VMS, CMS, and MTS
+systems will all now work with EFS and Dired.  It also works with a whole
+bunch of others, but documentation for that has not been written yet.
+This section was taken straight from the ange-ftp manual, and is
+therefore in all likelihood out-of-date.
+EFS should be able to automatically detect which type of host you
+are using (VMS, CMS or MTS), but if it is unable to do so you can fix
+the problem by setting the appropriate
+@code{efs-TYPE-host-regexp} variable (where @code{TYPE} is one of
+@samp{vms}, @samp{cms} or @samp{mts}) -- see below. If EFS is unable
+to automatically detect any VMS, CMS or MTS host, please report this as
+a bug: @xref{Bugs}.
+In all cases the file-name conventions of the remote host are converted
+to a UNIX-ish format, and this is the format you should use to find
+files on such hosts.
+@menu
+* VMS support::                 Using EFS with VMS systems
+* CMS support::                 Using EFS with CMS systems
+* MTS support::                 Using EFS with MTS systems
+@end menu
+@node VMS support, CMS support, Non-Unix Hosts, Non-Unix Hosts
+@comment  node-name,  next,  previous,  up
+@subsection VMS support
+@cindex VMS filenames
+VMS filenames are of the form @code{FILE.TYPE;##}, where both
+@code{FILE} and @code{TYPE} can be up to 39 characters long, and
+@code{##} is an integer version number between 1 and 32,767. Valid
+characters in filenames are @samp{A}-@samp{Z}, @samp{0}-@samp{9},
+@samp{_}, @samp{-} and @samp{$}, however @samp{$} cannot begin a
+filename and @samp{-} cannot be used as the first or last character.
+Directories in VMS are converted to the standard UNIX @samp{/} notation.
+For example, the VMS filename
+@example
+PUB$:[ANONYMOUS.SDSCPUB.NEXT]README.TXT;1
+@end example
+would be entered as
+@noindent
+@example
+/PUB$$:/ANONYMOUS/SDSCPUB/NEXT/README.TXT;1
+@end example
+@noindent
+(The double @samp{$} is required to prevent Emacs from attempting to
+expand an environment variable.)  Similarly, to anonymously FTP the file
+@file{[.CSV.POLICY]RULES.MEM;1} from @code{ymir.claremont.edu} you would
+type @kbd{C-x C-f
+/anonymous@@ymir.claremont.edu:CSV/POLICY/RULES.MEM;1}. You can always
+drop off the @samp{;##} part at the end of the filename to get the
+latest version.
+Sandy Rutherford provides some tips for using VMS hosts:
+@itemize @bullet
+@item
+Although VMS is not case sensitive, EMACS running under UNIX is.
+Therefore, to access a VMS file, you must enter the filename with upper
+case letters.
+@item
+To access the latest version of file under VMS, you use the filename
+without the @samp{;} and version number. You should always edit the
+latest version of a file. If you want to edit an earlier version, copy
+it to a new file first. This has nothing to do with EFS, but is
+simply good VMS operating practice. Therefore, to edit @file{FILE.TXT;3}
+(say 3 is latest version), do @kbd{C-x C-f
+/ymir.claremont.edu:FILE.TXT}. If you inadvertently do
+@example
+@kbd{C-x C-f /ymir.claremont.edu:FILE.TXT;3}
+@end example
+@noindent
+you will find that VMS will not allow
+you to save the file because it will refuse to overwrite
+@file{FILE.TXT;3}, but instead will want to create @file{FILE.TXT;4},
+and attach the buffer to this file. To get out of this situation,
+@kbd{M-x write-file /ymir.claremont.edu:FILE.TXT} will attach the buffer
+to latest version of the file. For this reason, in Dired @kbd{f}
+(@code{dired-find-file}),
+@findex dired-find-file
+always loads the file sans version, whereas @kbd{v},
+(@code{dired-view-file}),
+@findex dired-view-file
+always loads the explicit version number. The
+reasoning being that it reasonable to view old versions of a file, but
+not to edit them.
+@item
+VMS filenames often contain @samp{$} characters: make sure you always
+quote these as @samp{$$} and watch out for the Emacs bug which fails to
+quote @samp{$}'s when defaults are presented in the minibuffer: see
+@xref{Bugs}.
+@end itemize
+EFS should automatically detect that you are using a VMS host. If
+it fails to do so (which should be reported as a bug) you can use the
+command @code{efs-add-vms-host}
+@findex efs-add-vms-host
+to inform EFS manually. For a more permanent effect, or
+if you use a VMS host regularly, it's a good idea to set
+@code{efs-vms-host-regexp} to a regular expression matching that
+@vindex efs-vms-host-regexp
+host's name. For instance, if use use @code{ymir.claremont.edu} a lot,
+place the following in your .emacs:
+@example
+(setq efs-vms-host-regexp "^ymir.claremont.edu$")
+@end example
+@node CMS support, MTS support, VMS support, Non-Unix Hosts
+@comment  node-name,  next,  previous,  up
+@subsection CMS support
+EFS has full support, including Dired support, for hosts
+running CMS.
+@cindex CMS filenames
+CMS filenames are entered in a UNIX-y way. Minidisks are
+treated as UNIX directories; for example to access the file @file{READ.ME} in
+minidisk @file{*.311} on @file{cuvmb.cc.columbia.edu}, you would enter
+@example
+/anonymous@@cuvmb.cc.columbia.edu:/*.311/READ.ME
+@end example
+If @file{*.301} is the default minidisk for this account, you could access
+@file{FOO.BAR} on this minidisk as
+@example
+/anonymous@@cuvmb.cc.columbia.edu:FOO.BAR
+@end example
+CMS filenames are of the form @file{FILE.TYPE}, where both @file{FILE}
+and @file{TYPE} can be up to 8 characters. Again, beware that CMS
+filenames are always upper case, and hence must be entered as such.
+Sandy Rutherford provides some tips on using CMS hosts:
+@itemize @bullet
+@item
+CMS machines, with the exception of anonymous accounts, nearly always
+need an account password. To have EFS send an account password,
+you can either include it in your @file{.netrc} (@xref{Using a .netrc}), or use
+@code{efs-set-account}.
+@findex efs-set-account
+@item
+EFS cannot send ``write passwords'' for a minidisk. Hopefully, we
+can fix this.
+@end itemize
+EFS should automatically detect that you are using a CMS host. If
+it fails to do so (which should be reported as a bug) you can use the
+command @code{efs-add-cms-host}
+@findex efs-add-cms-host
+to inform EFS manually. For a more permanent effect, or
+if you use a CMS host regularly, it's a good idea to set
+@code{efs-cms-host-regexp} to a regular expression matching that
+@vindex efs-cms-host-regexp
+host's name.
+@node MTS support,  , CMS support, Non-Unix Hosts
+@comment  node-name,  next,  previous,  up
+@subsection MTS support
+EFS has full support, including Dired support, for hosts
+running the Michigan terminal system, and should be able to
+automatically recognise any MTS machine.
+@cindex MTS filenames
+MTS filenames are entered in a UNIX-y way. For example, if your account
+was @file{YYYY}, the file @file{FILE} in the account @file{XXXX:} on
+@file{mtsg.ubc.ca} would be entered as
+@example
+/YYYY@@mtsg.ubc.ca:/XXXX:/FILE
+@end example
+In other words, MTS accounts are treated as UNIX directories. Of course,
+to access a file in another account, you must have access permission for
+it.  If @file{FILE} were in your own account, then you could enter it in a
+relative path fashion as
+@example
+/YYYY@@mtsg.ubc.ca:FILE
+@end example
+MTS filenames can be up to 12 characters. Like UNIX, the structure of the
+filename does not contain a type (i.e. it can have as many @samp{.}'s as you
+like.) MTS filenames are always in upper case, and hence be sure to enter
+them as such! MTS is not case sensitive, but an EMACS running under UNIX
+is.
+EFS should automatically detect that you are using an MTS host. If
+it fails to do so (which should be reported as a bug) you can use the
+command @code{efs-add-mts-host}
+@findex efs-add-mts-host
+to inform EFS manually. For a more permanent effect, or
+if you use an MTS host regularly, it's a good idea to set
+@code{efs-mts-host-regexp} to a regular expression matching that
+@vindex efs-mts-host-regexp
+host's name.
+@node Completion, Accessing the FTP process, Non-Unix Hosts, Using EFS
+@comment  node-name,  next,  previous,  up
+@section File- and host-name completion
+Full filename completion is supported on all remote UNIX hosts and some
+non-Unix hosts.  Hostnames also have completion if they are mentioned in
+the @file{.netrc} and no username is specified. However using the
+filename completion feature can be a bit of a two edged sword.
+To understand why, we need to discuss how EFS works. Whenever
+EFS is asked to find a remote file (or directory) an @code{ls}
+command is sent to the FTP process to list all the files in the
+directory. This list is maintained in an internal cache, to provide
+filename completion for later requests on that directory. EFS keeps
+this cache up-to-date by monitoring Emacs commands which affect files
+and directories, but if a process outside Emacs (such as another user)
+changes a directory (e.g. a new file is added)
+completion won't work on
+that file since EFS doesn't know about it yet. The solution if to
+force EFS to reread the directory and update it's cache, and the
+easiest way to do that is with Dired --- @xref{Using Dired} to see how.
+Another problem is that the @code{ls} command can take a long time,
+especially when dealing with distant hosts over slow links. So if you're
+after a file in the @file{pub/images} directory but nothing else, it's a
+better idea to type @kbd{pub/images/file @key{TAB}} than @kbd{pub/im @key{TAB}}
+which will force a read of the @file{pub} directory (since
+EFS needs to know how to complete @code{im}). A little extra typing
+can often save a lot of waiting. Don't be afraid to use the @key{TAB}
+key once the directory is cached, though.
+@node Accessing the FTP process,  , Completion, Using EFS
+@comment  node-name,  next,  previous,  up
+@section Accessing the FTP process buffer
+The FTP process used to access the remote files is available for access
+if you wish. It will be in a buffer
+@cindex process buffers
+@cindex buffers
+called @samp{"*ftp @var{remote-file-name}*"},
+i.e. if you found the file
+@example
+/anonymous@@archive.site.com:pub/README
+@end example
+@noindent
+there will be a buffer
+@example
+*ftp anonymous@@archive.site.com*
+@end example
+@noindent
+where all the transfers are taking place. You can have a look at the
+buffer using @kbd{C-x b} as usual, and even type in commands to the FTP
+process under an interface very much like @samp{shell-mode}. There are
+two instances when doing this can be very useful: one is accessing
+non-UNIX hosts, where Dired and filename completion may not work (if EFS
+even works at all).  If you are going to use @code{mget} or @code{mput},
+make sure you type @code{glob} first: EFS turns globbing off by
+default. Don't be afraid of changing directories, either --- EFS always
+uses absolute pathnames when communicating with the FTP process.
+You can kill the FTP process at any time simply by killing this buffer.
+@cindex FTP processes
+@cindex processes
+You can also call @code{efs-kill-ftp-process}.
+@findex efs-kill-ftp-process
+This won't cause EFS any grief whatsoever --- if you later make
+another request to that host, EFS will simply fire up another
+process and create a new buffer to hold it.
+@node Getting help, Bugs, Using EFS, Top
+@comment  node-name,  next,  previous,  up
+@chapter Getting help
+EFS has its own mailing list called @t{efs-help}.  All users of EFS
+are welcome to subscribe (see below) and to discuss aspects of
+EFS.
+To [un]subscribe to @t{efs-help}, or to report mailer problems with the
+list, please mail one of the following addresses:
+@example
+efs-help-request@@cuckoo.hpl.hp.com
+@end example
+or
+@example
+efs-help-request%cuckoo.hpl.hp.com@@hplb.hpl.hp.com
+@end example
+Please don't forget the @t{-request} part.
+For mail to be posted directly to @t{efs-help}, send to one of the
+following addresses:
+@example
+efs-help@@cuckoo.hpl.hp.com
+@end example
+or
+@example
+efs-help%cuckoo.hpl.hp.com@@hplb.hpl.hp.com
+@end example
+Alternatively, there is a mailing list that only gets
+announcements of new EFS releases.  This is called @t{efs-announce},
+and can be subscribed to by e-mailing to the @t{-request} address as
+above.  Please make it clear in the request which mailing list you
+wish to join.
+Mailing list archives are also accessible from this web page:
+@example
+http://www-uk.hpl.hp.com/people/ange/efs
+@end example
+@node Bugs, Concept Index, Getting help, Top
+@comment  node-name,  next,  previous,  up
+@chapter Bugs and Wish List
+If you find any bugs or problems with this package, @strong{please}
+e-mail the authors. Ideas and constructive comments are especially
+welcome. So are any enhancements to EFS, preferably debugged and
+documented. Also welcome are any typo fixes, corrections or additions to
+this manual.
+Here is a list of known bugs:
+If you hit a bug in this list, please report it anyway. Most of
+the bugs here remain unfixed because they are considered too
+esoteric to be a high priority. If one of them gets reported
+enough, we will likely change our view on that.
+@enumerate
+@item
+EFS does not check to make sure that when creating a new file,
+you provide a valid filename for the remote operating system.
+If you do not, then the remote FTP server will most likely
+translate your filename in some way. This may cause EFS to
+get confused about what exactly is the name of the file.
+@item
+For CMS support, we send too many @code{cd}'s. Since @code{cd}'s are
+cheap, I haven't worried about this too much. Eventually, we should have
+some caching of the current minidisk. This is complicated by the fact
+that some CMS servers lie about the current minidisk, so sending
+redundant cd's helps us recover in this case.
+@item
+The code to do compression of files over ftp is not as careful as it
+should be. It deletes the old remote version of the file, before
+actually checking if the local to remote transfer of the compressed file
+succeeds. Of course to delete the original version of the file after
+transferring the compressed version back is also dangerous, because some
+OS's have severe restrictions on the length of filenames, and when the
+compressed version is copied back the @code{"-Z"} or @code{".Z"} may be
+truncated. Then, EFS would delete the only remaining version of the
+file.  Maybe EFS should make backups when it compresses files (of
+course, the backup @code{"~"} could also be truncated off, sigh...).
+Suggestions?
+@item
+If a dir listing is attempted for an empty directory on (at least
+some) VMS hosts, an ftp error is given. This is really an ftp bug, and
+I don't know how to get EFS work to around it.
+@item
+EFS gets confused by directories containing file names with embedded
+newlines. A temporary solution is to add @code{"q"} to your dired
+listing switches. As long as your dired listing switches also contain
+@code{"l"} and either @code{"a"} or @code{"A"}, EFS will use these
+switches to get listings for its internal cache. The "q" switch should
+force listings to be exactly one file per line. You still will not be
+able to access a file with embedded newlines, but at least it won't mess
+up the parsing of the rest of the files.
+@item
+EFS cannot parse symlinks which have an embedded @code{" -> "} in their
+name. It's alright to have an embedded @code{" -> "} in the name of any
+other type of file. A fix is possible, but probably not worth the
+trouble. If you disagree, send us a bug report.
+@item
+EFS doesn't handle context-dep. files in H-switch listings on
+HP's. It wouldn't be such a big roaring deal to fix this. I'm
+waiting until I get an actual bug report though.
+@item
+If a hard link is added or deleted, EFS will not update its
+internal cache of the link count for other names of the file.
+This may cause file-nlinks to return incorrectly. Reverting
+any dired buffer containing other names for the file will
+cause the file data to be updated, including the link counts.
+A fix for this problem is known and will be eventually
+implemented. How it is implemented will depend on how we decide
+to handle inodes. See below.
+@item
+EFS is unable to parse R-switch listings from remote Unix hosts.
+This is inefficient, because EFS will insist on doing individual
+listings of the subdirectories to get its file information.
+This may be fixed if there is enough demand.
+@item
+In file-attributes, EFS returns a fake inode number. Of course
+this is necessary, but this inode number is not even necessarily
+unique.  It is simply the sum of the characters (treated as
+integers) in the host name, user name, and file name. Possible
+ways to get a unique inode number are:
+@enumerate
+@item
+Simply keep a count of all remote file in the cache, and
+return the file's position in this count as a negative number.
+@item
+For unix systems, we could actually get at the real inode number on the
+remote host, by adding an @code{"i"} to the ls switches.  The inode
+numbers would then be removed from the listing returned by @code{efs-ls}, if
+the caller hadn't requested the @code{"i"} switch. We could then make a
+unique number out of the host name and the real inode number.
+@end enumerate
+@item
+EFS tries to determine if a file is readable or writable by comparing
+the file modes, file owner, and user name under which it is logged
+into the remote host. This does not take into account groups.
+We simply assume that the user belongs to all groups. As a result
+we may assume that a file is writable, when in fact it is not.
+Groups are tough to handle correctly over FTP. Suggestions?
+(For new FTP servers, can do a @code{"QUOTE SITE EXEC groups"} to
+handle this.)
+@end enumerate
+@node Concept Index, Variable and command index, Bugs, Top
+@comment  node-name,  next,  previous,  up
+@unnumbered Concept Index
+@printindex cp
+@node Variable and function index,  , Concept Index, Top
+@unnumbered Variable and function index
+@printindex vr
+@contents
+@bye

Mercurial > hg > xemacs-beta

comparison man/efs.texi @ 42:8b8b7f3559a2 r19-15b104