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 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 73 insertions(+), 45 deletions(-) (limited to 'Doc/Zsh/mod_zftp.yo') 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. -- cgit 1.4.1