 |
ActiveTcl User Guide
|
 |
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
ftp(n) 2.4 "ftp client"
ftp - Client-side tcl implementation of the ftp protocol
package require Tcl 8.2
package require ftp ?2.4?
package require ftp::geturl ?0.2?
The ftp package provides the client side of the ftp protocol as
specified in RFC 959 (http://www.rfc-editor.org/rfc/rfc959.txt).
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.
- ::ftp::geturl url
- This command lives in its own package, ::ftp::geturl, and can be used by the generic command ::uri::geturl to retrieve the contents of ftp urls.
Internally it uses the ftp commands described below to fulfill the
request.
The contents of an ftp url are defined as follows:
- file
- The contents of the specified file itself.
- directory
- A listing of the contents of the directory in key value
notation where the file name is the key and its attributes the
associated value.
- link
- The attributes of the link, including the path it refers
to.
- ::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:
- -blocksize size
- The blocksize is used during data transfer. At most size bytes are transfered at once. The default value for
this option is 4096. The package will evaluate the -progress callback for the session after the transfer of
each block.
- -timeout seconds
- If seconds is non-zero, then ::ftp::Open sets up a timeout which will occur after the
specified number of seconds. The default value is 600.
- -port number
- The port number specifies an alternative
remote port on the ftp server on which the ftp service resides.
Most ftp services listen for connection requests on the default
port 21. Sometimes, usually for security reasons, port numbers
other than 21 are used for ftp connections.
- -mode mode
- The transfer mode option determines if a
file transfer occurs in active or
passive mode. In passive mode the client will ask
the ftp server to listen on a data port and wait for the connection
rather than to initiate the process by itself when a data transfer
request comes in. Passive mode is normally a requirement when
accessing sites via a firewall. The default mode is
active.
- -progress callback
- This callback is evaluated whenever a block
of data was transfered. See the option -blocksize
for how to specify the size of the transfered blocks.
When evaluating the callback one argument is
appended to the callback script, the current accumulated number of
bytes transferred so far.
- -command callback
- Specifying this option places the connection into asynchronous
mode. The callback is evaluated after the
completion of any operation. When an operation is running no
further operations must be started until a callback has been
received for the currently executing operation.
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 occurred during the execution of the
operation the callback is given the keyword
error.
- -output callback
- This option has no default. If it is set the default
implementation of ::ftp::DisplayMsg will use its
value as command prefix to log all internal messages. The callback
will have three arguments appended to it before evaluation, the id
of the session, the message itself, and the connection state, in
this order.
- ::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 connection
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
- a subdirectory of the current directory,
- Two dots, .. (as an indicator for the parent
directory of the current directory)
- or a fully qualified path to a new working directory.
- ::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 ?pattern?
- This command returns a human-readable list of files. Wildcard
expressions such as "*.tcl" are allowed. If pattern refers to a specific directory, then the
contents of that directory are returned. If the pattern is not a fully-qualified path name, the command
lists entries relative to the current remote directory. If no pattern is specified, the contents of the current
remote directory is returned.
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 occurred.
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 | -channel chan) ?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 successful 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.
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.
- ::ftp::Append handle (local | -data data | -channel chan) ?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 | -channel
chan)?
- 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
are 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
successful transfer and 0 in the case of a failure. The command
will throw an error if the directory the file local is to be placed in does not exist.
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.
- ::ftp::Reget handle remote ?local? ?from? ?to?
- 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. The
command will throw an error if the directory the file local is to be placed in does not exist. This command is
useful when transferring very large files over networks that tend
to drop connections.
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.
- ::ftp::Newer handle remote ?local?
- This command behaves like ::ftp::Get, except
that it retrieves 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. The command will throw an error if the directory
the file local is to be placed in does not
exist.
- ::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 successful 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 successful 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 contrast 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 ::ftp::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 package log is
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 ::ftp::DisplayMsg may run into persistent errors or
infinite loops. The solution to this problem is to use update idletasks instead of update.
ftpd , mime , pop3
, smtp
ftp , internet , net , rfc
959