diff options
Diffstat (limited to 'Doc/Zsh/zftpsys.yo')
| -rw-r--r-- | Doc/Zsh/zftpsys.yo | 435 |
1 files changed, 435 insertions, 0 deletions
diff --git a/Doc/Zsh/zftpsys.yo b/Doc/Zsh/zftpsys.yo new file mode 100644 index 000000000..f20a0a6c3 --- /dev/null +++ b/Doc/Zsh/zftpsys.yo @@ -0,0 +1,435 @@ +texinode(Zftp Function System)()(Completion System)(Top) +chapter(Zftp Function System) +cindex(zftp, function system) +sect(Description) + +This describes the set of shell functions supplied with the source +distribution as an interface to the tt(zftp) builtin command, allowing you +to perform FTP operations from the shell command line or within functions +or scripts. The interface is similar to a traditional FTP client (e.g. the +manref(ftp)(1) command itself), but as it is entirely done within the shell +all the familar completion, editing and globbing features, and so on, are +present, and macros are particularly simple to write as they are just +ordinary shell functions. + +The prerequisite is that the tt(zftp) command, as described in +ifzman(\ +zmanref(zshmodules) +)\ +ifnzman(\ +noderef(The zftp Module) +), must be available in the +version of tt(zsh) installed at your site. If the shell is configured to +load new commands at run time, it probably is: typing tt(zmodload zftp) +will make sure (if that runs silently, it has worked). If this is not the +case, it is possible tt(zftp) was linked into the shell anyway: to test +this, type tt(which zftp) and if tt(zftp) is available you will get the +message tt(zftp: shell built-in command). + +Commands given directly with tt(zftp) builtin may be interspersed between +the functions in this suite; in a few cases, using tt(zftp) directly may +cause some of the status information stored in shell parameters to become +invalid. Note in particular the description of the variables +tt($ZFTP_TMOUT), tt($ZFTP_PREFS) and tt($ZFTP_VERBOSE) for tt(zftp). + +startmenu() +menu(Installation) +menu(Zftp Functions) +menu(Miscellaneous Features) +endmenu() + +texinode(Installation)(Zftp Functions)()(Zftp Function System) +sect(Installation) + +You should make sure all the functions from the tt(Functions/Zftp) +directory of the source distribution are available; they all begin with the +two letters tt(zf). They may already have been installed on your system; +otherwise, you will need to find them and copy them. The directory should +appear as one of the elements of the tt($fpath) array, and the functions +should be autoloaded. Finally, to initialise the use of the system you +need to call the tt(zfinit) function. The following code in your +tt(.zshrc) will arrange for this; assume the functions are stored in the +directory tt(~/myfns): + +tt(indent( +nofill(fpath=(~/myfns $fpath)) +nofill(autoload ~/myfns/zf*(:t)) +nofill(zfinit) +)) + +Note that tt(zfinit) assumes you are using the tt(zmodload) method to +load the tt(zftp) command. If it is already built into the shell, change +tt(zfinit) to tt(zfinit -n). + +texinode(Zftp Functions)(Miscellaneous Features)(Installation)(Zftp Function System) +sect(Functions) + +The sequence of operations in performing a file transfer is essentially the +same as that in a standard FTP client. + +subsect(Opening a connection) +startitem() +item(tt(zfparams [ var(host) [ var(user) [ var(password) ... ] ] ]))( +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. +) +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 +given as `tt(?)' it will be prompted for. If var(host) is not present, use +a previously stored set of parameters. + +If the command was successful, and the terminal is an tt(xterm), a summary +will appear in the title bar, giving the local tt(host:directory) and the +remote tt(host:directory); this is handled by the function tt(zftp_chpwd), +described below. + +Normally, the var(host), var(user) and var(password) are internally +recorded for later re-opening, either by a tt(zfopen) with no arguments, or +automatically (see below). With the option tt(-1), no information is +stored. +) +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 +generated from var(user)tt(@)tt(host); this is then stored in the shell +parameter tt($EMAIL_ADDR) which can alternatively be set manually to a +suitable string. +) +enditem() + +subsect(Directory management) +startitem() +xitem(tt(zfcd [ var(dir) ])) +xitem(tt(zfcd -)) +item(tt(zfcd var(old) var(new)))( +Change the current directory on the remote server: this is implemented to +have many of the features of the shell builtin tt(cd). + +In the first form with var(dir) present, change to the directory var(dir). +The command tt(zfcd ..) is treated specially, so is guaranteed to work on +non-UNIX servers (note this is handled internall by tt(zftp)). If var(dir) +is omitted, has the effect of tt(zfcd ~). + +The second form changes to the directory previously current. + +The third form attempts to change the current directory by replacing the +first occurrence of the string var(old) with the string var(new) in the +current directory. + +Note that in this command, and indeed anywhere a remote filename is +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 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. +) +item(tt(zfhere))( +Change directory on the remote server to the one corresponding to the +current local directory, with special handling of tt(~) as in tt(zfcd). +For example, if the current local directory is tt(~/foo/bar), then +tt(zfhere) performs the effect of tt(zfcd ~/foo/bar). +) +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. + +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 +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. +) +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 +are passed directory to the server. No pager and no caching is used. +) +enditem() + +subsect(Status commands) +startitem() +item(tt(zftype) [ var(type) ])( +With no arguments, show the type of data to be transferred, usually ASCII +or binary. With an argument, change the type: the types tt(A) or +tt(ASCII) for ASCII data and tt(B) or tt(BINARY), tt(I) or tt(IMAGE) for +binary data are understood case-insensitively. +) +item(tt(zfstat) [ -v ])( +Show the status of the current or last connection, as well as the status of +some of tt(zftp)'s status variables. With the tt(-v) option, a more +verbose listing is produced by querying the server for its version of +events, too. +) +enditem() + +subsect(Retrieving files) +The commands for retrieving files all take at least two options. tt(-G) +suppresses remote filename expansion which would otherwise be performed +(see below for a more detailed description of that). tt(-t) attempts +to set the modification time of the local file to that of the remote file: +this requires version 5 of tt(perl), see the description of the function +tt(zfrtime) below for more information. + +startitem() +item(tt(zfget [ -Gt ] var(file1) ...))( +Retrieve all the listed files var(file1) ... one at a time from the remote +server. If a file contains a `tt(/)', the full name is passed to the +remote server, but the file is stored locally under the name given by the +part after the final `tt(/)'. +) +item(tt(zfuget [ -Gvst ] var(file1) ...))( +As tt(zfget), but only retrieve files where the version on the remote +server is newer (has a later modification time), or where the local file +does not exist. If the remote file is older but the files have different +sizes, or if the sizes are the same but the remote file is newer, the user +will usually be queried. With the option tt(-s), the command runs silently +and will always retrieve the file in either of those two cases. With the +option tt(-v), the command prints more information about the files while it +is working out whether or not to transfer them. +) +item(tt(zfcget [ -Gt ] var(file1) ...))( +As tt(zfget), but if any of the local files exists, and is shorter than +the corresponding remote file, the command assumes that it is the result of +a partially completed transfer and attempts to transfer the rest of the +file. This is useful on a poor connection which keeps failing. + +Note that this requires a commonly implemented, but non-standard, version +of the FTP protocol, so is not guaranteed to work on all servers. +) +xitem(tt(zfgcp [ -Gt ] var(remote-file) var(local-file))) +item(tt(zfgcp [ -Gt ] var(rfile1) ... var(ldir)))( +This retrieves files from the remote server with arguments behaving +similarly to the tt(cp) command. + +In the first form, copy var(remote-file) from the server to the local file +var(local-file). + +In the second form, copy all the remote files var(rfile1) ... into the +local directory var(ldir) retaining the same basenames. This assumes UNIX +directory semantics. +) +enditem() + +subsect(Sending files) +startitem() +item(tt(zfput var(file1) ...))( +Send all the var(file1) ... given separately to the remote server. If a +filename contains a `tt(/)', the full filename is used locally to find the +file, but only the basename is used for the remote file name. +) +item(tt(zfuput [ -vs ] var(file1) ...))( +As tt(zfput), but only send files which are newer than their local +equivalents, or if the remote file does not exist. The logic is the same +as for tt(zfuget), but reversed between local and remote files. +) +item(tt(zfcput var(file1) ...))( +As tt(zfput), but if any remote file already exists and is shorter than the +local equivalent, assume it is the result of an incomplete transfer and +send the rest of the file to append to the existing part. As the FTP +append command is part of the standard set, this is in principle more +likely to work than tt(zfcget). +) +xitem(tt(zfpcp var(local-file) var(remote-file))) +item(tt(zfpcp var(lfile1) ... var(rdir)))( +This sends files to the remote server with arguments behaving similarly to +the tt(cp) command. + +With two arguments, copy var(local-file) to the server as +var(remote-file). + +With more than two arguments, copy all the local files var(lfile1) ... into +the existing remote directory var(rdir) retaining the same basenames. This +assumes UNIX directory semantics. + +A problem arises if you attempt to use tt(zfpcp) var(lfile1) var(rdir), +i.e. the second form of copying but with two arguments, as the command has +no simple way of knowing if var(rdir) corresponds to a directory or a +filename. It attempts to resolve this in various ways. First, if the +var(rdir) argument is tt(.) or tt(..) or ends in a slash, it is assumed to +be a directory. Secondly, if the operation of copying to a remote file in +the first form failed, and the remote server sends back the expected +failure code 553 and a reply including the string `tt(Is a directory)', +then tt(zfpcp) will retry using the second form. +) +enditem() + +subsect(Closing the connectino) +startitem() +item(tt(zfclose))( +Close the connection. +) +enditem() + +subsect(Other functions) +Mostly, these functions will not be called directly (apart from +tt(zfinit)), but are described here for completeness. You may wish to +alter tt(zftp_chpwd) and tt(zftp_progress), in particular. + +startitem() +item(tt(zfinit [ -n ]))( +As decribed above, this is used to initialise the zftp function system. +The tt(-n) option should be used if the zftp command is already built into +the shell. +) +item(tt(zfautocheck [ -dn ]))( +This function is called to implement automatic reopening behaviour, as +described in more detail below. The options must appear in the first +argument; tt(-n) prevents the command from changing to the old directory, +while tt(-d) prevents it from setting the variable tt(do_close), which it +otherwise does as a flag for automatically closing the connection after a +transfer. The host and directory for the last session are stored in the +variable tt($zflastsession), but the internal host/user/password parameters +must also be correctly set. +) +item(tt(zfcd_match var(prefix) var(suffix)))( +This performs matching for completion of remote directory names. If the +remote server is UNIX, it will attempt to persuade the server to list the +remote directory with subdirectories marked, which usually works but is not +guaranteed. On other hosts it simply calls tt(zfget_match) and hence +completes all files, not just directories. On some systems, directories +may not even look like filenames. +) +item(tt(zfget_match var(prefix) var(suffix)))( +This performs matching for completion of remote filenames. It caches files +for the current directory (only) in the shell parameter tt($zftp_fcache). +It is in the form to be called by the tt(-K) option of tt(compctl), but +also works when called from a widget-style completion function with +var(prefix) and var(suffix) set appropriately. +) +item(tt(zfrglob var(varname)))( +Perform remote globbing, as describes in more detail below. var(varname) +is the name of a variable containing the pattern to be expanded; if there +were any matches, the same variable will be set to the exanded set of +filenames on return. +) +item(tt(zfrtime var(lfile) var(rfile) [ var(time) ]))( +Set the local file var(lfile) to have the same modification time as the +remote file var(rfile), or the explicit time var(time) in FTP format +tt(CCYYMMDDhhmmSS) for the GMT timezone. + +Currently this requires tt(perl) version 5 to perform the conversion from +GMT to local time. This is unfortunately difficult to do using shell code +alone. +) +item(tt(zftp_chpwd))( +This function is called every time a connection is opened, or closed, or +the remote directory changes. This version alters the title bar of an +tt(xterm) or tt(sun-cmd) terminal emulator to reflect the local and remote +hostnames and current directories. It works best when combined with the +function tt(chpwd). In particular, a function of the form + +tt(indent( +nofill(chpwd() {) +nofill( if [[ -n $ZFTP_USER ]]; then) +nofill( zftp_chpwd) +nofill( else) +nofill( # usual chpwd e.g put host:directory in title bar) +nofill( fi) +nofill(}) +)) + +fits in well. +) +item(tt(zftp_progress))( +This function shows the status of the transfer as the percentage of the +total so far transferred. It will not write anything unless the output is +going to a terminal; however, if you transfer files in the background, you +should tt(unfunction) this first. (Background file transfers don't work on +all OSes.) Note also that if you alter it, any output em(must) be to +standard error, as standard output may be a file being received. +) +enditem() + +texinode(Miscellaneous Features)()(Zftp Functions)(Zftp Function System) +sect(Miscellaneous Features) + +subsect(Remote globbing) + +The commands for retrieving files usually perform filename expansion +(globbing) on their arguments; this can be turned off by passing the option +tt(-G) to each of the commands. Normally this operates by retrieving a +complete list of files for the directory in question, then matching these +locally against the pattern supplied. This has the advantage that the full +range of zsh patterns (respecting the setting of the option +tt(EXTENDED_GLOB)) can be used. However, it means that the directory part +of a filename will not be expanded and must be given exactly. If the +remote server does not support the UNIX directory semantics, directory +handling is problematic and it is recommended that globbing only be used +within the current directory. The list of files in the current directory, +if retrieved, will be cached, so that subsequent globs in the same +directory without an interventing tt(zfcd) are fast. + +If the variable tt($zfrglob) is set to a non-zero length, globbing is +instead performed on the remote host: the server is asked for a list of +matching files. This is highly dependent on how the server is implemented, +though typically UNIX servers will provide support for basic glob +patterns. This may in some cases be faster, as it avoids retrieving the +entire list of directory contents. + +subsect(Automatic and temporary reopening) + +As described for the tt(zfopen) command, a subsequent tt(zfopen) with no +parameters will reopen the connection to the last host (this includes +connections made with the tt(zfanon) command). Opened in this fashion, the +connection starts in the default remote directory and will remain open +until explicitly closed. + +Automatic re-opening is also available. If a connection is not currently +open and a command requiring a connection is given, the last connection is +implicitly reopened. In this case the directory which was current when the +connection was closed again becomes the current directory (unless, of +course, the command given changes it). Automatic reopening will also take +place if the connection was close by the remote server for whatever reason +(e.g. a timeout). It is not available if the tt(-1) option to tt(zfopen) +or tt(zfanon) was used. + +Furthermore, if the command issued is a file transfer, the connection will +be closed after the transfer is finished, hence providing a one-shot mode +for transfers. This does not apply to directory changing or listing +commands; for example a tt(zfdir) may reopen a connection but will leave it +open. Also, automatic closure will only ever happen in the same command as +automatic opening, i.e a tt(zfdir) directly followed by a tt(zfget) will +never close the connection automatically. + +Information about the previous connection is given by the tt(zfstat) +function. So, for example, if that reports: + +tt(indent( +nofill(Not connected.) +nofill(Last session: ftp.bar.com:/pub/textfiles) +)) + +then the command tt(zfget file.txt) will attempt to reopen a connection to +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. + +subsect(Completion) + +Completion of remote files and directories 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 should automatically be +available. |