diff options
Diffstat (limited to 'Doc/Zsh/mod_zftp.yo')
| -rw-r--r-- | Doc/Zsh/mod_zftp.yo | 421 |
1 files changed, 421 insertions, 0 deletions
diff --git a/Doc/Zsh/mod_zftp.yo b/Doc/Zsh/mod_zftp.yo new file mode 100644 index 000000000..a15be60d6 --- /dev/null +++ b/Doc/Zsh/mod_zftp.yo @@ -0,0 +1,421 @@ +texinode(The zftp Module)(The zle Module)(The stat Module)(Zsh Modules) +sect(The zftp Module) +The tt(zftp) module makes available one builtin command: + +startitem() +findex(zftp) +cindex(FTP) +cindex(files, transferring) +item(tt(zftp) var(subcommand) [ var(args) ])( +The tt(zftp) module is a client for FTP (file transfer protocol). It +is implemented as a builtin to allow full use of shell command line +editing, file I/O, and job control mechanisms. Often, users will +access it via shell functions providing higher level abilities such as +username and password lookup. However, it is entirely usable in its +own right. + +All commands consist of the command name tt(zftp) followed by the name +of a subcommand. These are listed below. The return status of each +subcommand is supposed to reflect the success or failure of the remote +operation. See a description of the variable tt(ZFTP_VERBOSE) for +more information on how responses from the server may be printed. +) +enditem() + +subsect(Subcommands) +cindex(zftp, subcommands) + +startitem() +cindex(FTP, starting a session) +item(tt(open) var(host) [ var(user) [ var(password) [ var(account) ] ] ])( +Open a new FTP session to var(host), which may be the name of a TCP/IP +connected host or an IP number in the standard dot notation. +Remaining arguments are passed to the tt(login) subcommand. Note that +if no arguments beyond var(host) are supplied, tt(open) will em(not) +automatically call tt(login). If no arguments at all are supplied, +tt(open) will use the parameters set by the tt(params) subcommand. + +After a successful open, the shell variables tt(ZFTP_HOST), +tt(ZFTP_IP) and tt(ZFTP_SYSTEM) are available; see `Variables' +below. +) +xitem(tt(login) [ var(name) [ var(password) [ var(account) ] ] ]) +item(tt(user) [ var(name) [ var(password) [ var(account) ] ] ])( +Login the user var(name) with parameters var(password) and var(account). +Any of the parameters can be omitted, and will be read from standard +input if needed (var(name) is always needed). If +standard input is a terminal, a prompt for each one will be printed on +standard error and var(password) will not be echoed. If any of the +parameters are not used, a warning message is printed. + +After a successful login, the shell variables tt(ZFTP_USER), +tt(ZFTP_ACCOUNT) and tt(ZFTP_PWD) are available; see `Variables' +below. + +This command may be re-issued when a user is already logged in, and +the server will first be reinitialized for a new user. +) +xitem(tt(params) [ var(host) [ var(user) [ var(password) \ +[ var(account) ] ] ] ]) +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. + +If instead a single `tt(-)' is given, the existing parameters, if any, +are deleted. In that case, calling tt(open) with no arguments will +cause an error. + +The list of parameters is not deleted after a tt(close), however it +will be deleted if the tt(zftp) module is unloaded. + +For example, + +nofill(tt(zftp params ftp.elsewhere.xx 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, + +nofill(tt(zftp params ftp.soreeyes.ca bubble squeak)) +nofill(tt(LPAR()zftp open; zftp get foo >bar; zftp close)tt(RPAR() &)) + +--- here, the connection is restricted to a background subshell and +you are free to open a simultaneous connection in the foreground. +) +item(tt(cd) var(directory))( +Change the remote directory to var(directory). Also alters the shell +variable tt(ZFTP_PWD). +) +item(tt(cdup))( +Change the remote directory to the one higher in the directory tree. +Note that tt(cd ..) will also work correctly on non-UNIX systems. +) +item(tt(dir) [ var(args...) ])( +Give a (verbose) listing of the remote directory. The var(args) are +passed directly to the server. The command's behaviour is implementation +dependent, but a UNIX server will typically interpret var(args) as +arguments to the tt(ls) command and with no arguments return the +result of `tt(ls -l)'. The directory is listed to standard output. +) +item(tt(ls) [ var(args) ])( +Give a (short) listing of the remote directory. With no var(args), +produces a raw list of the files in the directory, one per line. +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 +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)'). + +The FTP default for a transfer is ASCII. However, if tt(zftp) finds +that the remote host is a UNIX machine with 8-bit byes, it will +automatically switch to using binary for file transfers upon +tt(open). This can subsequently be overridden. + +The transfer type is only passed to the remote host when a data +connection is established; this command involves no network overhead. +) +item(tt(ascii))( +The same as tt(type A). +) +item(tt(binary))( +The same as tt(type I). +) +item(tt(mode) [ tt(S) | tt(B) ])( +Set the mode type to stream (tt(S)) or block (tt(B)). Stream mode is +the default; block mode is not widely supported. +) +xitem(tt(remote) var(files...)) +item(tt(local) [ var(files...) ])( +Print the size and last modification time of the remote or local +files. If there is more than one item on the list, the name of the +file is printed first. The first number is the file size, the second +is the last modification time of the file in the format +tt(CCYYMMDDhhmmSS) consisting of year, month, date, hour, minutes and +seconds in GMT. Note that this format, including the length, is +guaranteed, so that time strings can be directly compared via the +tt([[) builtin's tt(<) and tt(>) operators, even if they are too long +to be represented as integers. + +Not all servers support the commands for retrieving this information. +In that case, the tt(remote) command will print nothing and return +status 2, compared with status 1 for a file not found. + +The tt(local) command (but not tt(remote)) may be used with no +arguments, in which case the information comes from examining file +descriptor zero. This is the same file as seen by a tt(put) command +with no further redirection. +) +item(tt(get) var(file) [...])( +Retrieve all var(file)s from the server, concatenating them +and sending them to standard output. +) +item(tt(put) var(file) [...])( +For each var(file), read a file from standard input and send that to +the remote host with the given name. +) +item(tt(append) var(file) [...])( +As tt(put), but if the remote var(file) already exists, data is +appended to it instead of overwriting it. +) +xitem(tt(getat) var(file) var(point)) +xitem(tt(putat) var(file) var(point)) +item(tt(appendat) var(file) var(point))( +Versions of tt(get), tt(put) and tt(append) which will start the +transfer at the given var(point) in the remote var(file). This is +useful for appending to an incomplete local file. However, note that +this ability is not universally supported by servers (and is not quite +the behaviour specified by the standard). +) +item(tt(delete) var(file) [...])( +Delete the list of files on the server. +) +item(tt(mkdir) var(directory))( +Create a new directory var(directory) on the server. +) +item(tt(rmdir) var(directory))( +Delete the diretory var(directory) on the server. +) +item(tt(rename) var(old-name) var(new-name))( +Rename file var(old-name) to var(new-name) on the server. +) +item(tt(site) var(args...))( +Send a host-specific command to the server. You will probably +only need this if instructed by the server to use it. +) +item(tt(quote) var(args...))( +Send the raw FTP command sequence to the server. You should be +familiar with the FTP command set as defined in RFC959 before doing +this. Useful comands may include tt(STAT) and tt(HELP). Note also +the mechanism for returning messages as described for the variable +tt(ZFTP_VERBOSE) below, in particular that all messages from the +control connection are sent to standard error. +) +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). +) +enditem() + +subsect(Parameters) +cindex(zftp, parameters) +The following shell parameters are used by tt(zftp). Currently none +of them are special. + +startitem() +item(tt(ZFTP_TMOUT))( +Integer. The time in seconds to wait for a network operation to +complete before returning an error. If this is not set when the +module is loaded, it will be given the default value 60. A value of +zero turns off timeouts. If a timeout occurs on the control +connection it will be closed. Use a larger value if this occurs too +frequently. +) +vindex(ZFTP_IP) +item(tt(ZFTP_IP))( +Readonly. The IP address of the current connection in dot notation. +) +vindex(ZFTP_HOST) +item(tt(ZFTP_HOST))( +Readonly. The hostname of the current remote server. If the host was +opened as an IP number, tt(ZFTP_HOST) contains that instead; this +saves the overhead for a name lookup, as IP numbers are most commonly +used when a nameserver is unavailable. +) +vindex(ZFTP_SYSTEM) +item(tt(ZFTP_SYSTEM))( +Readonly. The system type string returned by the server in response +to an FTP tt(SYST) request. The most interesting case is a string +beginning tt("UNIX Type: L8"), which ensures maximum compatibility +with a local UNIX host. +) +vindex(ZFTP_TYPE) +item(tt(ZFTP_TYPE))( +Readonly. The type to be used for data transfers , either `tt(A)' or +`tt(I)'. Use the tt(type) subcommand to change this. +) +vindex(ZFTP_USER) +item(tt(ZFTP_USER))( +Readonly. The username currently logged in, if any. +) +vindex(ZFTP_ACCT) +item(tt(ZFTP_ACCT))( +Readonly. The account name of the current user, if any. Most servers +do not require an account name. +) +vindex(ZFTP_PWD) +item(tt(ZFTP_PWD))( +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. +) +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. +) +vindex(ZFTP_PREFS) +item(tt(ZFTP_PREFS))( +A string of preferences for altering aspects of tt(zftp)'s behaviour. +Each preference is a single character. The following are defined: + +startitem() +item(tt(P))( +Passive: attempt to make the remote server initiate data transfers. +This is slightly more efficient than sendport mode. If the letter +tt(S) occurs later in the string, tt(zftp) will use sendport mode if +passive mode is not available. +) +item(tt(S))( +Sendport: initiate transfers by the FTP tt(PORT) command. If this +occurs before any tt(P) in the string, passive mode will never be +attempted. +) +item(tt(D))( +Dumb: use only the bare minimum of FTP commands. This prevents +the variables tt(ZFTP_SYSTEM) and tt(ZFTP_PWD) from being set, and +will mean all connections default to ASCII type. It may prevent +tt(ZFTP_SIZE) from being set during a transfer if the server +does not send it anyway (many servers do). +) +enditem() + +If tt(ZFTP_PREFS) is not set when tt(zftp) is loaded, it will be set to a +default of `tt(PS)', i.e. use passive mode if available, otherwise +fall back to sendport mode. +) +vindex(ZFTP_VERBOSE) +item(tt(ZFTP_VERBOSE))( +A string of digits between 0 and 5 inclusive, specifying which +responses from the server should be printed. All responses go to +standard error. If any of the numbers 1 to 5 appear in the string, +raw responses from the server with reply codes beginning with that +digit will be printed to standard error. The first digit of the three +digit reply code is defined by RFC959 to correspond to: + +startitem() +item(1.)( +A positive prelimnary reply. +) +item(2.)( +A positive completion reply. +) +item(3.)( +A positive intermediate reply. +) +item(4.)( +A transient negative completion reply. +) +item(5.)( +A permanent negative completion reply. +) +enditem() + +It should be noted that, for unknown reasons, the reply `Service not +available', which forces termination of a connection, is classified as +421, i.e. `transient negative', an interesting interpretation of the word +`transient'. + +The code 0 is special: it indicates that all but the last line of +multiline replies read from the server will be printed to standard +error in a processed format. By convention, servers use this +mechanism for sending information for the user to read. The +appropriate reply code, if it matches the same response, takes +priority. + +If tt(ZFTP_VERBOSE) is not set when tt(zftp) is loaded, it will be +set to the default value tt(450), i.e., messages destined for the user +and all errors will be printed. A null string is valid and +specifies that no messages should be printed. +) +enditem() + +subsect(Functions) +cindex(zftp, functions) + +startitem() +findex(zftp_chpwd) +item(tt(zftp_chpwd))( +If this function is set by the user, it is called every time the +directory changes on the server, including when a user is logged +in, or when a connection is closed. In the last case, tt($ZFTP_PWD) +will be unset; otherwise it will reflect the new directory. +) +findex(zftp_progress) +item(tt(zftp_progress))( +If this function is set by the user, it will be called during +a tt(get), tt(put) or tt(append) operation each time sufficient data +has been received from the host. During a tt(get), the data is sent +to standard output, so it is vital that this function should write +to standard error or directly to the terminal, em(not) to standard +output. + +When it is called with a transfer in progress, the following +additional shell parameters are set: + +startitem() +vindex(ZFTP_FILE) +item(tt(ZFTP_FILE))( +The name of the remote file being transferred from or to. +) +vindex(ZFTP_TRANSFER) +item(tt(ZFTP_TRANSFER))( +A tt(G) for a tt(get) operation and a tt(P) for a tt(put) operation. +) +vindex(ZFTP_SIZE) +item(tt(ZFTP_SIZE))( +The total size of the complete file being transferred: +the same as the first value provided by the +tt(remote) and tt(local) subcommands for a particular file. +If the server cannot supply this value for a remote file being +retrieved, it will not be set. If input is from a pipe the value may +be incorrect and correspond simply to a full pipe buffer. +) +vindex(ZFTP_COUNT) +item(tt(ZFTP_COUNT))( +The amount of data so far transferred; a number between zero and +tt($ZFTP_SIZE), if that is set. This number is always available. +) +enditem() + +The function is initially called with tt(ZFTP_TRANSFER) set +appropriately and tt(ZFTP_COUNT) set to zero. After the transfer is +finished, the function will be called one more time with +tt(ZFTP_TRANSFER) set to tt(GF) or tt(PF), in case it wishes to tidy +up. It is otherwise never called twice with the same value of +tt(ZFTP_COUNT). + +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. +) + +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). + +enditem() |