ftp - Client-side tcl implementation of the ftp protocol
SYNOPSIS
package require Tcl 8.2
package require ftp ?2.3.1?
package require ftp::geturl ?0.1?
|
The ftp package provides the client side of the ftp protocol. The package implements both active (default) and passive ftp sessions.
A new ftp session is started with the ::ftp::Open command. To shutdown an existing ftp session use ::ftp::Close. All other commands are restricted to usage in an an open ftp session. They will generate errors if they are used out of context. The ftp package includes file and directory manipulating commands for remote sites. To perform the same operations on the local site use commands built into the core, like cd or file.
The output of the package is controlled by two state variables, ::ftp::VERBOSE and ::ftp::DEBUG. Setting ::ftp::VERBOSE to "1" forces the package to show all responses from a remote server. The default value is "0". Setting ::ftp::DEBUG to "1" enables debugging and forces the package to show all return codes, states, state changes and "real" ftp commands. The default value is "0".
The command ::ftp::DisplayMsg is used to show the different messages from the ftp session. The setting of ::ftp::VERBOSE determines if this command is called or not. The current implementation of the command uses the log package of tcllib to write the messages to their final destination. This means that the behaviour of ::ftp::DisplayMsg can be customized without changing its implementation. For more radical changes overwriting its implementation by the application is of course still possible. Note that the default implementation honors the option -output to ::ftp::Open for a session specific log command.
Caution: The default implementation logs error messages like
all other messages. If this behaviour is changed to throwing an error
instead all commands in the API will change their behaviour too. In
such a case they will not return a failure code as described below but
pass the thrown error to their caller.
The correct execution of many commands depends upon the proper
behavior by the remote server, network and router configuration.
An update command placed in the procedure ::ftp::DisplayMsg may
run into persistent errors or infinite loops. The solution to this
problem is to use update idletasks instead of update.
API
The contents of an ftp url are defined as follows:
The command takes a host name server, a user name user and
a password password as its parameters and returns a session
handle that is an integer number greater than or equal to "0", if the
connection is successfully established. Otherwise it returns "-1".
The server parameter must be the name or internet address (in
dotted decimal notation) of the ftp server to connect to. The
user and passwd parameters must contain a valid user name
and password to complete the login process.
The options overwrite some default values or set special abilities:
When evaluating the callback one argument is appended to the
callback script, the current accumulated number of bytes transferred
so far.
When evaluating the callback several arguments are appended to
the callback script, namely the keyword of the operation that has
completed and any additional arguments specific to the operation. If
an error occured during the execution of the operation the callback is
given the keyword error.
Currently only ascii and binary types are
supported. There is some early (alpha) support for Tenex mode. The
type ascii is normally used to convert text files into a
format suitable for text editors on the platform of the destination
machine. This mainly affects end-of-line markers. The type
binary on the other hand allows the undisturbed transfer of
non-text files, such as compressed files, images and executables.
The listing includes any system-dependent information that the server
chooses to include. For example most UNIX systems produce output from
the command ls -l. The command returns the retrieved
information as a tcl list with one item per entry. Empty lines and
UNIX's "total" lines are ignored and not included in the result as
reported by this command.
If the command fails an empty list is returned.
ATTENTION! It will not work properly when in ascii mode and
is not supported by all ftp server implementations.
If -data data is specified instead of a local file, the
system will not transfer a file, but the data passed into it. In
this case the name of the remote file has to be specified.
If -channel chan is specified instead of a local file,
the system will not transfer a file, but read the contents of the
channel chan and write this to the remote file. In this case the
name of the remote file has to be specified. After the transfer
chan will be closed.
If -variable varname is specified, the system will
store the retrieved data into the variable varname instead of a
file.
If -channel chan is specified, the system will write
the retrieved data into the channel chan instead of a file. The
system will not close chan after the transfer, this is
the responsibility of the caller to ::ftp::Get.
Specifying the additional byte offsets from and to will
cause the command to change its behaviour and to download exactly the
specified slice of the remote file. This mode is possible only if a
local destination is explicitly provided. Omission of to leads
to downloading till the end of the file.
In constrast to the other commands in this package this command will
not parse the response it got from the ftp server but return it
verbatim to the caller.
BUGS
SEE ALSO
ftpd, smtp, pop3, mime
KEYWORDS
ftp, rfc959, internet, net