From b67e4abb100f67ca05809baab37700eb5ee0a342 Mon Sep 17 00:00:00 2001 From: Tanaka Akira Date: Fri, 10 Sep 1999 13:57:31 +0000 Subject: manual/7767 --- Doc/Zsh/mod_zftp.yo | 118 ++++++++++++++++++++++++++++++------------------- Doc/Zsh/zftpsys.yo | 123 ++++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 168 insertions(+), 73 deletions(-) (limited to 'Doc') 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 -- cgit 1.4.1