summary refs log tree commit diff
path: root/Doc/Zsh/mod_zftp.yo
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/Zsh/mod_zftp.yo')
-rw-r--r--Doc/Zsh/mod_zftp.yo421
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()