manual/7767

2 files changed, 168 insertions, 73 deletions

diff --git a/Doc/Zsh/mod_zftp.yo b/Doc/Zsh/mod_zftp.yo
index f5d165083..e5dc8ec2f 100644
--- a/Doc/Zsh/mod_zftp.yo
+++ b/Doc/Zsh/mod_zftp.yo
@@ -63,13 +63,20 @@ xitem(tt(params) [ var(host) [ var(user) [ var(password) \
 item(tt(params) tt(-))(
 Store the given parameters for a later tt(open) command with no
 arguments.  Only those given on the command line will be remembered.
-Any of the parameters may, however, be specified as a `tt(?)', which
-may need to be quoted to protect it from shell expansion:  in this case,
-the appropriate parameter will be read from stdin as with the
-tt(login) subcommand, including special handling of var(password).
-
 If no arguments are given, the parameters currently set are printed,
-although the password will appear as a line of stars.
+although the password will appear as a line of stars; the return value is
+one if no parameters were set, zero otherwise.
+
+Any of the parameters may be specified as a `tt(?)', which
+may need to be quoted to protect it from shell expansion.  In this case,
+the appropriate parameter will be read from stdin as with the
+tt(login) subcommand, including special handling of var(password).  If the
+`tt(?)' is followed by a string, that is used as the prompt for reading the
+parameter instead of the default message (any necessary punctuation and
+whitespace should be included at the end of the prompt).  The first letter
+of the parameter (only) may be quoted with a `tt(\)'; hence an argument
+tt("\\$word") guarantees that the string from the shell parameter tt($word)
+will be treated literally, whether or not it begins with a `tt(?)'.
 
 If instead a single `tt(-)' is given, the existing parameters, if any,
 are deleted.  In that case, calling tt(open) with no arguments will
@@ -80,20 +87,10 @@ will be deleted if the tt(zftp) module is unloaded.
 
 For example,
 
-example(zftp params ftp.elsewhere.xx juser '?')
+example(zftp params ftp.elsewhere.xx juser '?Password for juser: ')
 
 will store the host tt(ftp.elsewhere.xx) and the user tt(juser) and
-then prompt the user for the corresponding password.
-
-This command may also be used to set up a transfer which then takes
-place completely in the background, freeing tt(zftp) for concurrent
-foreground use.  For example,
-
-example(zftp params ftp.soreeyes.ca bubble squeak
-(zftp open; zftp get foo >bar; zftp close) &)
-
---- here, the connection is restricted to a background subshell and
-you are free to open a simultaneous connection in the foreground.
+then prompt the user for the corresponding password with the given prompt.
 )
 item(tt(test))(
 Test the connection; if the server has reported
@@ -105,16 +102,11 @@ mechanism, or error messages if the connection closes.  There is no
 network overhead for this test.
 
 The test is only supported on systems with either the tt(select(2)) or
-tt(poll(2)) system calls; otherwise the message tt(not
-supported on this system) is printed instead.
+tt(poll(2)) system calls; otherwise the message `tt(not
+supported on this system)' is printed instead.
 
-It is useful to put the code
-
-example([[ -n $ZFTP_HOST ]] && zftp test)
-
-into the shell function tt(precmd) for testing the connection before
-every prompt.  However, tt(zftp) will call tt(test) at the start of any
-other subcommand when a connection is open.
+The tt(test) subcommand will automatically be called at the start of any
+other subcommand for the current session when a connection is open.
 )
 item(tt(cd) var(directory))(
 Change the remote directory to var(directory).  Also alters the shell
@@ -138,7 +130,7 @@ Otherwise, up to vagaries of the server implementation, behaves
 similar to tt(dir).
 )
 item(tt(type) [ var(type) ])(
-Change the type for transfer to var(type), or print the current type
+Change the type for the transfer to var(type), or print the current type
 if var(type) is absent.  The allowed values are `tt(A)' (ASCII),
 `tt(I)' (Image, i.e. binary), or `tt(B)' (a synonym for `tt(I)').
 
@@ -230,7 +222,32 @@ xitem(tt(close))
 item(tt(quit))(
 Close the current data connection.  This unsets the shell parameters
 tt(ZFTP_HOST), tt(ZFTP_IP), tt(ZFTP_SYSTEM), tt(ZFTP_USER),
-tt(ZFTP_ACCOUNT) and tt(ZFTP_PWD).
+tt(ZFTP_ACCOUNT), tt(ZFTP_PWD), tt(ZFTP_TYPE) and tt(ZFTP_MODE).
+)
+item(tt(session) [ var(sessname) ])(
+Allows multiple FTP sessions to be used at once.  The name of the session
+is an arbitrary string of characters; the default session is called
+`tt(default)'.  If this command is called without an argument, it will list
+all the current sessions; with an argument, it will either switch to the
+existing session called var(sessname), or create a new session of that name.
+
+Each session remembers the status of the connection, the set of
+connection-specific shell parameters (the same set as are unset when a
+connection closes, as given in the description of tt(close)), and any user
+parameters specified with the tt(params) subcommand.  Changing to a
+previous session restores those values; changing to a new session
+initialises them in the same way as if tt(zftp) had just been loaded.  The
+name of the current session is given by the parameter tt(ZFTP_SESSION).
+)
+item(tt(rmsession) [ var(sessname) ])(
+Delete a session; if a name is not given, the current session is deleted.
+If the current session is deleted, the earliest existing session becomes
+the new current session, otherwise the current session is not changed.
+If the session being deleted is the only one, a new session called
+`tt(default)' is created and becomes the current session; note that this is
+a new session even if the session being deleted is also called
+`tt(default)'. It is recommended that sessions not be deleted while
+background commands which use tt(zftp) are still active.
 )
 enditem()
 
@@ -276,8 +293,8 @@ vindex(ZFTP_USER)
 item(tt(ZFTP_USER))(
 Readonly.  The username currently logged in, if any.
 )
-vindex(ZFTP_ACCT)
-item(tt(ZFTP_ACCT))(
+vindex(ZFTP_ACCOUNT)
+item(tt(ZFTP_ACCOUNT))(
 Readonly.  The account name of the current user, if any.  Most servers
 do not require an account name.
 )
@@ -288,12 +305,19 @@ Readonly.  The current directory on the server.
 vindex(ZFTP_CODE)
 item(tt(ZFTP_CODE))(
 Readonly.  The three digit code of the last FTP reply from the server
-as a string.  This can still be read after the connection is closed.
+as a string.  This can still be read after the connection is closed, and
+is not changed when the current session changes.
 )
 vindex(ZFTP_REPLY)
 item(tt(ZFTP_REPLY))(
 Readonly.  The last line of the last reply sent by the server.  This
-can still be read after the connection is closed.
+can still be read after the connection is closed, and is not changed when
+the current session changes.
+)
+vindex(ZFTP_SESSION)
+item(tt(ZFTP_SESSION))(
+Readonly.  The name of the current FTP session; see the description of the
+tt(session) subcommand.
 )
 vindex(ZFTP_PREFS)
 item(tt(ZFTP_PREFS))(
@@ -430,21 +454,25 @@ Sometimes the progress meter may cause disruption.  It is up to the
 user to decide whether the function should be defined and to use
 tt(unfunction) when necessary.
 )
+enditem()
 
 subsect(Problems)
 cindex(zftp, problems)
 
-With the exception noted for the tt(params) subcommand, a connection
-may not be opened in the left hand side of a pipe as this occurs in a
-subshell and the file information is not updated in the main shell.
-In the case of type or mode changes or closing the connection in a
-subshell, the information is returned but variables are not updated
-until the next call to tt(zftp).  Other status changes in subshells
-will not be reflected by changes to the variables (but should
-be otherwise harmless).
+A connection may not be opened in the left hand side of a pipe as this
+occurs in a subshell and the file information is not updated in the main
+shell.  In the case of type or mode changes or closing the connection in a
+subshell, the information is returned but variables are not updated until
+the next call to tt(zftp).  Other status changes in subshells will not be
+reflected by changes to the variables (but should be otherwise harmless).
 
-On some operating systems, the control connection is not valid after a
-fork(), so that operations in subshells or on the left hand side of a
-pipeline are not possible.
+Deleting sessions while a tt(zftp) command is active in the background can
+have unexpected effects, even if it does not use the session being deleted.
+This is because all shell subprocesses share information on the state of
+all connections, and deleting a session changes the ordering of that
+information.
 
-enditem()
+On some operating systems, the control connection is not valid after a
+fork(), so that operations in subshells, on the left hand side of a
+pipeline, or in the background are not possible, as they should be.  This
+is presumably a bug in the operating system.
diff --git a/Doc/Zsh/zftpsys.yo b/Doc/Zsh/zftpsys.yo
index 3c8f90cdd..89d39b985 100644
--- a/Doc/Zsh/zftpsys.yo
+++ b/Doc/Zsh/zftpsys.yo
@@ -54,7 +54,7 @@ following code in your tt(.zshrc) will arrange for this; assume the
 functions are stored in the directory tt(~/myfns):
 
 example(fpath=(~/myfns $fpath)
-autoload zfinit
+autoload -U zfinit
 zfinit)
 
 Note that tt(zfinit) assumes you are using the tt(zmodload) method to
@@ -67,7 +67,10 @@ texinode(Zftp Functions)(Miscellaneous Features)(Installation)(Zftp Function Sys
 sect(Functions)
 
 The sequence of operations in performing a file transfer is essentially the
-same as that in a standard FTP client.
+same as that in a standard FTP client.  Note that, due to a quirk of the
+shell's tt(getopts) builtin, for those functions that handle options you
+must use `tt(-)tt(-)' rather than `tt(-)' to ensure the remaining arguments
+are treated literally (a single `tt(-)' is treated as an argument).
 
 subsect(Opening a connection)
 startitem()
@@ -77,16 +80,20 @@ Set or show the parameters for a future tt(zfopen) with no arguments.  If
 no arguments are given, the current parameters are displayed (the password
 will be shown as a line of asterisks).  If a host is given, and either the
 var(user) or var(password) is not, they will be prompted for; also, any
-parameter given as `tt(?)' will be prompted for.
-
-As tt(zfopen) calls tt(zfparams) to store the parameters, this usually need
-not be called directly.
+parameter given as `tt(?)' will be prompted for, and if the `tt(?)' is
+followed by a string, that will be used as the prompt.  As tt(zfopen) calls
+tt(zfparams) to store the parameters, this usually need not be called
+directly.
+
+A single argument `tt(-)' will delete the stored parameters.  This will
+also cause the memory of the last directory (and so on) on the other host
+to be deleted.
 )
 findex(zfopen)
 item(tt(zfopen [ -1 ] [ var(host) [ var(user) [ var(password) [ var(account) ] ] ] ]))(
 If var(host) is present, open a connection to that host under username
 var(user) with password var(password) (and, on the rare occasions when it
-is necessary account var(account)).  If a necessary parameter is missing or
+is necessary, account var(account)).  If a necessary parameter is missing or
 given as `tt(?)' it will be prompted for.  If var(host) is not present, use
 a previously stored set of parameters.
 
@@ -106,12 +113,12 @@ var(host), then change directory to var(path) (which must be a directory,
 not a file).  The `tt(ftp://)' can be omitted; the trailing `tt(/)' is enough
 to trigger recognition of the var(path).  Note prefixes other than
 `tt(ftp:)' are not recognized, and that all characters after the first
-slash beyond tt(host) are significant in var(path).
+slash beyond var(host) are significant in var(path).
 )
 findex(zfanon)
 item(tt(zfanon [ -1 ] var(host)))(
 Open a connection var(host) for anonymous FTP.  The username used is
-tt(anonymous).  The password (which will be reported the first time) is
+`tt(anonymous)'.  The password (which will be reported the first time) is
 generated as var(user)tt(@)var(host); this is then stored in the shell
 parameter tt($EMAIL_ADDR) which can alternatively be set manually to a
 suitable string.
@@ -143,12 +150,12 @@ expected, the string which on the local host corresponds to `tt(~)' is
 converted back to a `tt(~)' before being passed to the remote machine.
 This is convenient because of the way expansion is performed on the command
 line before tt(zfcd) receives a string.  For example, suppose the command
-is `tt(zfcd ~/foo)'.  The shell will expand this to a full path as in
+is `tt(zfcd ~/foo)'.  The shell will expand this to a full path such as
 `tt(zfcd /home/user2/pws/foo)'.  At this stage, tt(zfcd) recognises the
-initial path as `tt(~)', and the directory sent to the remote host is
-tt(~/foo), so that the `tt(~)' will be expanded by the server to the
-correct remote host directory.  Other named directories of the form
-`tt(~name)' are not treated in this fashion.
+initial path as corresponding to `tt(~)' and will send the directory to
+the remote host as tt(~/foo), so that the `tt(~)' will be expanded by the
+server to the correct remote host directory.  Other named directories of
+the form `tt(~name)' are not treated in this fashion.
 )
 findex(zfhere)
 item(tt(zfhere))(
@@ -162,21 +169,23 @@ item(tt(zfdir [ -rfd ] [ - ] [ var(dir-options) ] [ var(dir) ]))(
 Produce a long directory listing.  The arguments var(dir-options) and
 var(dir) are passed directly to the server and their effect is
 implementation dependent, but specifying a particular remote directory
-var(dir) is usually possible.  The output is passed through pager.
+var(dir) is usually possible.  The output is passed through a pager
+given by the environment variable tt($PAGER) or defaulting to `tt(more)'.
 
 The directory is usually cached for re-use.  In fact, two caches are
 maintained.  One is for use when there is no var(dir-options) or var(dir),
 i.e. a full listing of the current remote directory; it is flushed
 when the current remote directory changes.  The other is
 kept for repeated use of tt(zfdir) with the same arguments; for example,
-repeated use of tt(zfdir /pub/gnu) will only require the directory to be
+repeated use of `tt(zfdir /pub/gnu)' will only require the directory to be
 retrieved on the first call.  Alternatively, this cache can be re-viewed with
 the tt(-r) option.  As relative directories will confuse
-tt(zfdir), the tt(-f) option can be used to force the cache to be flushed.
-Also, the option tt(-d) will delete both caches without showing a directory
-listing.
+tt(zfdir), the tt(-f) option can be used to force the cache to be flushed
+before the directory is listed.  The option tt(-d) will delete both
+caches without showing a directory listing; it will also delete the cache
+of file names in the current remote directory, if any.
 )
-findex(zfdir)
+findex(zfls)
 item(tt(zfls) [ var(ls-options) ] [ var(dir) ])(
 List files on the remote server.  With no arguments, this will produce a
 simple list of file names for the current remote directory.  Any arguments
@@ -311,6 +320,49 @@ Close the connection.
 )
 enditem()
 
+subsect(Session management)
+startitem()
+findex(zfsession)
+item(tt(zfsession) [ tt(-lvod) ] [ var(sessname) ])(
+Allows you to manage multiple FTP sessions at once.  By default,
+connections take place in a session called `tt(default)'; by giving the
+command `tt(zfsession) var(sessname)' you can change to a new or existing
+session with a name of your choice.  The new session remembers its own
+connection, as well as associated shell parameters, and also the host/user
+parameters set by tt(zfparams).  Hence you can have different sessions set
+up to connect to different hosts, each remembering the appropriate host,
+user and password.
+
+With no arguments, tt(zfsession) prints the name of the current session;
+with the option tt(-l) it lists all sessions which currently exist, and
+with the option tt(-v) it gives a verbose list showing the host and
+directory for each session, where the current session is marked with an
+asterisk.  With tt(-o), it will switch to the most recent previous session.
+
+With tt(-d), the given session (or else the current one) is removed;
+everything to do with it is completely forgotten.  If it was the only
+session, a new session called `tt(default)' is created and made current.
+It is safest not to delete sessions while background commands using
+tt(zftp) are active.
+)
+findex(zftransfer)
+item(tt(zftransfer) var(sess1)tt(:)var(file1) var(sess2)tt(:)var(file2))(
+Transfer files between two sessions; no local copy is made.  The file
+is read from the session var(sess1) as var(file1) and written to session
+var(sess1) as file var(file2); var(file1) and var(file2) may be relative to
+the current directories of the sesssion.  Either var(sess1) or var(sess2)
+may be omitted (though the colon should be retained if there is a
+possibility of a colon appearing in the file name) and defaults to the
+current session; var(file2) may be omitted or may end with a slash, in
+which case the basename of var(file1) will be added.  The sessions
+var(sess1) and var(sess2) must be distinct.
+
+The operation is performed using pipes, so it is required that the
+connections still be valid in a subshell, which is not the case under some
+operating systems.
+)
+enditem()
+
 subsect(Bookmarks)
 The two functions tt(zfmark) and tt(zfgoto) allow you to `bookmark' the
 present location (host, user and directory) of the current FTP connection
@@ -329,16 +381,18 @@ closed; it is an error if there is none.  Any existing bookmark
 under the same name will be silently replaced.
 
 If not given an argument, list the existing bookmarks and the points to
-which they refer in the form var(user)tt(@)var(host)tt(:)var(directory).
+which they refer in the form var(user)tt(@)var(host)tt(:)var(directory);
+this is the format in which they are stored, and the file may be edited
+directly.
 )
 findex(zfgoto)
 item(tt(zfgoto [ -n ] )var(bookmark))(
 Return to the location given by var(bookmark), as previously set by
 tt(zfmark).  If the location has user `tt(ftp)' or `tt(anonymous)', open
 the connection with tt(zfanon), so that no password is required.  If the
-user and host parameters match those currently stored, those will be used,
-and again no password is required.  Otherwise a password will be prompted
-for.
+user and host parameters match those stored for the current session, if
+any, those will be used, and again no password is required.  Otherwise a
+password will be prompted for.
 
 With the option tt(-n), the bookmark is taken to be a nickname stored by
 the tt(ncftp) program in its bookmark file, which is assumed to be
@@ -434,6 +488,11 @@ error, as standard output may be a file being received.  The form of the
 progess meter, or whether it is used at all, can be configured without
 altering the function, as described in the next section.
 )
+findex(zffcache)
+item(tt(zffcache))(
+This is used to implement caching of files in the current directory for
+each session separately.  It is used by tt(zfget_match) and tt(zfrglob).
+)
 enditem()
 
 texinode(Miscellaneous Features)()(Zftp Functions)(Zftp Function System)
@@ -446,7 +505,10 @@ pindex(zfconfig)
 The tt(zfinit) function defines an associative array tt(zfconfig).
 Elements of this may subsequently be set to change the behaviour of the
 tt(zftp) functions using standard syntax (for example,
-`tt(zfconfig[progress]=percent)'.  The following keys are understood.
+`tt(zfconfig[progress]=percent)'.  tt(zfconfig) may also contain
+various other values used by the function system, so it should not be used
+as the target of an assignment for a complete array.  The following keys
+are understood.
 
 startitem()
 item(tt(progress))(
@@ -525,7 +587,8 @@ never close the connection automatically.
 Information about the previous connection is given by the tt(zfstat)
 function.  So, for example, if that reports:
 
-example(Not connected.
+example(Session:        default
+Not connected.
 Last session:   ftp.bar.com:/pub/textfiles)
 
 then the command tt(zfget file.txt) will attempt to reopen a connection to
@@ -533,10 +596,14 @@ tt(ftp.bar.com), retrieve the file tt(/pub/textfiles/file.txt), and
 immediately close the connection again.  On the other hand, tt(zfcd ..)
 will open the connection in the directory tt(/pub) and leave it open.
 
+Note that all the above is local to each session; if you return to a
+previous session, the connection for that session is the one which will be
+reopened.
+
 subsect(Completion)
 
-Completion of local and remote files, directories and bookmarks is
-supported.  The older, tt(compctl)-style completion is defined when
+Completion of local and remote files, directories, sessions and bookmarks
+is supported.  The older, tt(compctl)-style completion is defined when
 tt(zfinit) is called; support for the new widget-based completion system is
 provided in the function tt(Completion/Builtins/_zftp), which should be
 installed with the other functions of the completion system and hence