Tcl Library Source Code

Documentation
Login


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

ftp - Client-side tcl implementation of the ftp protocol

Table Of Contents

SYNOPSIS

package require Tcl 8.5 9
package require ftp ?2.4.14?

::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 ?pattern?
::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 | -channel chan) ?remote?
::ftp::Append handle (local | -data data | -channel chan) ?remote?
::ftp::Get handle remote ?(local | -variable varname | -channel chan)?
::ftp::Reget handle remote ?local? ?from? ?to?
::ftp::Newer handle remote ?local?
::ftp::MkDir handle directory
::ftp::RmDir handle directory
::ftp::Quote handle arg1 arg2 ...
::ftp::DisplayMsg handle msg ?state?

DESCRIPTION

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.

API

BUGS

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.

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category ftp of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

SEE ALSO

ftpd, mime, pop3, smtp

KEYWORDS

ftp, internet, net, rfc 959

CATEGORY

Networking