ftp(3tcl)
NAME
ftp - Client-side tcl implementation of the ftp protocol
SYNOPSIS
package require Tcl 8.2 package require ftp ?2.4.13? ::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
::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".
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 [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation.
SEE ALSO
ftpd, mime, pop3, smtp
KEYWORDS
ftp, internet, net, rfc 959
CATEGORY
Networking
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
