_________________________________________________________________
ftp - Client-side tcl implementation of the ftp protocol
package require Tcl
package require ftp ?2.2.1?
ftp::Open server user passwd ?options?
ftp::Close handle
ftp::Cd handle directory
ftp::Pwd handle
ftp::Type handle ?ascii|binary|tenex?
ftp::List handle ?directory?
ftp::NList handle ?directory?
ftp::FileSize handle file
ftp::ModTime handle file
ftp::Delete handle file
ftp::Rename handle from to
ftp::Put handle (local | -data data) ?remote?
ftp::Append handle (local | -data data) ?remote?
ftp::Get handle remote ?(local | -variable varname)?
ftp::Reget handle remote ?local?
ftp::Newer handle remote ?local?
ftp::MkDir handle directory
ftp::RmDir handle directory
ftp::Quote handle arg1 arg2 ...
ftp::DisplayMsg handle msg ?state?
_________________________________________________________________
The ftp library 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 Open command. To shutdown an existing ftp session use 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 procedure DisplayMsg is used to show the different messages from the ftp session. The package itself declares this command very simple, writing the messages to stdout (if VERBOSE was set, s.a.) and throwing tcl errors for error messages. It is the responsibility of the application to overwrite it as needed. A state variable for different states assigned to different colors is recommended by the author. The log package can be useful for this.
ftp::Open server user passwd ?options?
This command is used to start a FTP session by
establishing a control connection to the FTP
server. The defaults are used for any option not
specified by the caller.
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:
The package will evaluate the -progress callback for the session after the transfer of each block.
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.
ftp::Close handle
This command terminates the specified ftp session.
If no file transfer is in progress, the server will
close the control connection immediately. If a file
transfer is in progress however, the control connection
will remain open until the transfers completes.
When that happens the server will write the
result response for the transfer to it and close
the conenction afterward.
ftp::Cd handle directory
This command changes the current working directory
on the ftp server to a specified target directory.
The command returns 1 if the current working directory
was successfully changed to the specified
directory or 0 if it fails. The target directory
can be
ftp::Pwd handle
This command returns the complete path of the current
working directory on the ftp server, or an
empty string in case of an error.
ftp::Type handle ?ascii|binary|tenex?
This command sets the ftp file transfer type to
either ascii, binary, or tenex. The command always
returns the currently set type. If called without
type no change is made.
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.
ftp::List handle ?directory?
This commands lists the contents of the specified a
directory or other group of files. If no directory
is specified the current remote directory is used
instead. Wildcard expressions such as *.tcl are
allowed. A directory or file name must be fully
qualified, otherwise the commands lists the entries
in the current remote directory.
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.
ftp::NList handle ?directory?
This command has the same behavior as the ftp::List
command, except that it only retrieves an abbreviated
listing. This means only file names are
returned in a sorted list.
ftp::FileSize handle file
This command returns the size of the specified file
on the ftp server. If the command fails an empty
string is returned.
ATTENTION! It will not work properly when in ascii mode and is not supported by all ftp server implementations.
ftp::ModTime handle file
This command retrieves the time of the last modification
of the file on the ftp server as a system
dependent integer value in seconds or an empty
string if an error occured. Use the built-in command
clock to convert the retrieves value into
other formats.
ftp::Delete handle file
This command deletes the specified file on the ftp
server. The command returns 1 if the specified file
was successfully deleted or 0 if it failed.
ftp::Rename handle from to
This command renames the file from in the current
directory of the ftp server to the specified new
file name to. This new file name must not be the
same as any existing subdirectory or file name.
The command returns 1 if the specified file was
successfully renamed or 0 if it failed.
ftp::Put handle (local | -data data) ?remote? This command transfers a local file local to a remote file remote on the ftp server. If the file parameters passed to the command do not fully qualified path names the command will use the current directory on local and remote host. If the remote file name is unspecified, the server will use the name of the local file as the name of the remote file. The command returns 1 to indicate a sucessful transfer and 0 in the case of a failure.
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.
ftp::Append handle (local | -data data) ?remote? This command behaves like ftp::Puts, but appends the transfered information to the remote file. If the file did not exist on the server it will be created.
ftp::Get handle remote ?(local | -variable varname)? This command retrieves a remote file remote on the ftp server and stores its contents into the local file local. If the file parameters passed to the command do not fully qualified path names the command will use the current directory on local and remote host. If the local file name is unspecified, the server will use the name of the remote file as the name of the local file. The command returns 1 to indicate a sucessful transfer and 0 in the case of a failure.
If -variable varname is specified, the system will store the retrieved data into the variable varname instead of a file.
ftp::Reget handle remote ?local?
This command behaves like ftp::Get, except that if
local file local exists and is smaller than remote
file remote, the local file is presumed to be a
partially transferred copy of the remote file and
the transfer is continued from the apparent point
of failure. This command is useful when transferring
very large files over networks that tend to
drop connections.
ftp::Newer handle remote ?local?
This command behaves like ftp::Get, except that it
retrives the remote file only if the modification
time of the remote file is more recent than the
file on the local system. If the file does not
exist on the local system, the remote file is
considered newer.
ftp::MkDir handle directory
This command creates the specified directory on the
ftp server. If the specified path is relative the
new directory will be created as a subdirectory of
the current working directory. Else the created
directory will have the specified path name. The
command returns 1 to indicate a sucessful creation
of the directory and 0 in the case of a failure.
ftp::RmDir handle directory
This command removes the specified directory on the
ftp server. The remote directory has to be empty or
the command will fail. The command returns 1 to
indicate a sucessful removal of the directory and 0
in the case of a failure.
ftp::Quote handle arg1 arg2 ...
This command is used to send an arbitrary ftp command
to the server. It cannot be used to obtain a
directory listing or for transferring files. It is
included to allow an application to execute commands
on the ftp server which are not provided by
this package. The arguments are sent verbatim,
i.e. as is, with no changes.
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.
ftp::DisplayMsg handle msg ?state?
This command is used by the package itself to show
the different messages from the ftp sessions. The
package itself declares this command very simple,
writing the messages to stdout (if VERBOSE was set,
see below) and throwing tcl errors for error messages.
It is the responsibility of the application
to overwrite it as needed. A state variable for
different states assigned to different colors is
recommended by the author. The log package can be
useful for this.
ftp::VERBOSE
A state variable controlling the output of the
package. Setting ftp::VERBOSE to 1 forces the package
to show all responses from a remote server. The
default value is 0.
ftp::DEBUG
A state variable controlling the output of ftp.
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 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 DisplayMsg may run into persistent errors or infinite loops. The solution to this problem is to use update idletasks instead of update.
ftpd, smtp, pop3, mime
ftp, rfc959, internet, net