path: root/Doc/Zsh/mod_zftp.yo

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(test))(
Test the connection; if the server has reported
that it has closed the connection (maybe due to a timeout), return
status 2; if no connection was open anyway, return status 1; else
return status 0.  The tt(test) subcommand is
silent, apart from messages printed by the tt($ZFTP_VERBOSE)
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.

It is useful to put the code

nofill(tt([[ -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.
)
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).

On some operatings 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.

enditem()