Overview
| Artifact ID: | fb0c4f1b45c92a781aa2ec33b2a37b70f4e19729 |
|---|---|
| Ticket: | 446584ffffffffffffffffffffffffffffffffff |
| Date: | 2001-09-13 02:03:20 |
| User: | andreas_kupries |
| Artifact Attached: | 0668af682dfb3a048b05102d8acee9d7662df276 |
| Filename: | ftp.n |
| Description: | Manpage 'ftp', nroff |
Content:
'\" '\" Copyright (c) 2000 Andreas Kupries '\" All right reserved '\" '\" CVS: $Id$ ftp.n '\" .so man.macros .TH "ftp" n 2.2 tcllib "ftp client" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME ftp \- Client-side tcl implementation of the ftp protocol .SH "SYNOPSIS" package require \fBTcl\fR .sp package require \fBftp ?2.2?\fR .sp \fBftp::Open\fR \fIserver\fR \fIuser\fR \fIpasswd\fR ?\fIoptions\fR?\fR .sp \fBftp::Close\fR \fIhandle\fR\fR .sp \fBftp::Cd\fR \fIhandle\fR \fIdirectory\fR\fR .sp \fBftp::Pwd\fR \fIhandle\fR\fR .sp \fBftp::Type\fR \fIhandle\fR ?\fIascii|binary|tenex\fR?\fR .sp \fBftp::List\fR \fIhandle\fR ?\fIdirectory\fR?\fR .sp \fBftp::NList\fR \fIhandle\fR ?\fIdirectory\fR?\fR .sp \fBftp::FileSize\fR \fIhandle\fR \fIfile\fR\fR .sp \fBftp::ModTime\fR \fIhandle\fR \fIfile\fR\fR .sp \fBftp::Delete\fR \fIhandle\fR \fIfile\fR\fR .sp \fBftp::Rename\fR \fIhandle\fR \fIfrom\fR \fIto\fR\fR .sp \fBftp::Put\fR \fIhandle\fR (\fIlocal\fR | -data \fIdata\fR) ?\fIremote\fR?\fR .sp \fBftp::Append\fR \fIhandle\fR (\fIlocal\fR | -data \fIdata\fR) ?\fIremote\fR?\fR .sp \fBftp::Get\fR \fIhandle\fR \fIremote\fR ?(\fIlocal\fR | -variable \fIvarname\fR)?\fR .sp \fBftp::Reget\fR \fIhandle\fR \fIremote\fR ?\fIlocal\fR?\fR .sp \fBftp::Newer\fR \fIhandle\fR \fIremote\fR ?\fIlocal\fR?\fR .sp \fBftp::MkDir\fR \fIhandle\fR \fIdirectory\fR\fR .sp \fBftp::RmDir\fR \fIhandle\fR \fIdirectory\fR\fR .sp \fBftp::Quote\fR \fIhandle\fR \fIarg1\fR \fIarg2\fR \fI...\fR\fR .sp \fBftp::DisplayMsg\fR \fIhandle\fR \fImsg\fR ?\fIstate\fR?\fR .sp .BE .SH "DESCRIPTION" .PP The ftp library package provides the client side of the ftp protocol. The package implements both active (default) and passive ftp sessions. .PP A new ftp session is started with the \fBOpen\fR command. To shutdown an existing ftp session use \fBClose\fR. 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 \fBcd\fR or \fBfile\fR. .PP The output of the package is controlled by two state variables, \fIftp::VERBOSE\fR and \fIftp::DEBUG\fR. Setting \fIftp::VERBOSE\fR to \fI1\fR forces the package to show all responses from a remote server. The default value is \fI0\fR. Setting \fIftp::DEBUG\fR to \fI1\fR enables debugging and forces the package to show all return codes, states, state changes and "real" ftp commands. The default value is \fI0\fR. .PP The procedure \fBDisplayMsg\fR is used to show the different messages from the ftp session. The package itself declares this command very simple, writing the messages to \fIstdout\fR (if \fIVERBOSE\fR 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 \fBlog\fR package can be useful for this. .SH "API" .TP \fBftp::Open\fR \fIserver\fR \fIuser\fR \fIpasswd\fR ?\fIoptions\fR?\fR 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. .sp The command takes a host name \fIserver\fR, a user name \fIuser\fR and a password \fIpassword\fR as its parameters and returns a session handle that is an integer number greater than or equal to \fI0\fR, if the connection is successfully established. Otherwise it returns \fI-1\fR. The \fIserver\fR parameter must be the name or internet address (in dotted decimal notation) of the ftp server to connect to. The \fIuser\fR and \fIpasswd\fR parameters must contain a valid user name and password to complete the login process. .sp The options overwrite some default values or set special abilities: .RS .TP -blocksize size The blocksize is used during data transfer. At most \fIsize\fR bytes are transfered at once. The default value for this option is 4096. The package will evaluate the \fB-progress callback\fR for the session after the transfer of each block. .TP -timeout seconds If \fIseconds\fR is non-zero, then \fBftp::Open\fR sets up a timeout which will occur after the specified number of seconds. The default value is 600. .TP -port number The port \fInumber\fR 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. .TP -mode mode The transfer \fImode\fR option determines if a file transfer occurs in \fBactive\fR or \fBpassive\fR 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 \fBactive\fR. .TP -progress callback This \fIcallback\fR is evaluated whenever a block of data was transfered. See the option \fB-blocksize\fR for how to specify the size of the transfered blocks. .sp When evaluating the \fIcallback\fR one argument is appended to the callback script, the current accumulated number of bytes transferred so far. .TP -command callback Specifying this option places the connection into asynchronous mode. The \fIcallback\fR 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. .sp When evaluating the \fIcallback\fR 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 \fBerror\fR. .RE .TP \fBftp::Close\fR \fIhandle\fR\fR 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. .TP \fBftp::Cd\fR \fIhandle\fR \fIdirectory\fR\fR This command changes the current working directory on the ftp server to a specified target \fIdirectory\fR. 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 .RS .TP * a subdirectory of the current directory, .TP * \fB..\fR (as an indicator for the parent directory of the current directory) .TP * or a fully qualified path to a new working directory. .RE .TP \fBftp::Pwd\fR \fIhandle\fR\fR This command returns the complete path of the current working directory on the ftp server, or an empty string in case of an error. .TP \fBftp::Type\fR \fIhandle\fR ?\fIascii|binary|tenex\fR?\fR This command sets the ftp file transfer type to either \fBascii\fR, \fBbinary\fR, or \fBtenex\fR. The command always returns the currently set type. If called without type no change is made. .sp Currently only \fBascii\fR and \fBbinary\fR types are supported. There is some early (alpha) support for Tenex mode. The type \fBascii\fR 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 \fBbinary\fR on the other hand allows the undisturbed transfer of non-text files, such as compressed files, images and executables. .TP \fBftp::List\fR \fIhandle\fR ?\fIdirectory\fR?\fR 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 \fI*.tcl\fR are allowed. A directory or file name must be fully qualified, otherwise the commands lists the entries in the current remote directory. .sp The listing includes any system-dependent information that the server chooses to include. For example most UNIX systems produce output from the command \fBls -l\fR. 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. .sp If the command fails an empty list is returned. .TP \fBftp::NList\fR \fIhandle\fR ?\fIdirectory\fR?\fR This command has the same behavior as the \fBftp::List\fR command, except that it only retrieves an abbreviated listing. This means only file names are returned in a sorted list. .TP \fBftp::FileSize\fR \fIhandle\fR \fIfile\fR\fR This command returns the size of the specified \fIfile\fR on the ftp server. If the command fails an empty string is returned. .sp \fBATTENTION!\fR It will not work properly when in ascii mode and is not supported by all ftp server implementations. .TP \fBftp::ModTime\fR \fIhandle\fR \fIfile\fR\fR This command retrieves the time of the last modification of the \fIfile\fR 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 \fBclock\fR to convert the retrieves value into other formats. .TP \fBftp::Delete\fR \fIhandle\fR \fIfile\fR\fR This command deletes the specified \fIfile\fR on the ftp server. The command returns 1 if the specified file was successfully deleted or 0 if it failed. .TP \fBftp::Rename\fR \fIhandle\fR \fIfrom\fR \fIto\fR\fR This command renames the file \fIfrom\fR in the current directory of the ftp server to the specified new file name \fIto\fR. 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. .TP \fBftp::Put\fR \fIhandle\fR (\fIlocal\fR | -data \fIdata\fR) ?\fIremote\fR?\fR This command transfers a local file \fIlocal\fR to a remote file \fIremote\fR 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. .sp If \fB-data \fIdata\fR\fR is specified instead of a local file, the system will not transfer a file, but the \fIdata\fR passed into it. In this case the name of the remote file has to be specified. .TP \fBftp::Append\fR \fIhandle\fR (\fIlocal\fR | -data \fIdata\fR) ?\fIremote\fR?\fR This command behaves like \fBftp::Puts\fR, but appends the transfered information to the remote file. If the file did not exist on the server it will be created. .TP \fBftp::Get\fR \fIhandle\fR \fIremote\fR ?(\fIlocal\fR | -variable \fIvarname\fR)?\fR This command retrieves a remote file \fIremote\fR on the ftp server and stores its contents into the local file \fIlocal\fR. 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. .sp If \fB-variable \fIvarname\fR\fR is specified, the system will store the retrieved data into the variable \fIvarname\fR instead of a file. .TP \fBftp::Reget\fR \fIhandle\fR \fIremote\fR ?\fIlocal\fR?\fR This command behaves like \fBftp::Get\fR, except that if local file \fIlocal\fR exists and is smaller than remote file \fIremote\fR, 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. .TP \fBftp::Newer\fR \fIhandle\fR \fIremote\fR ?\fIlocal\fR?\fR This command behaves like \fBftp::Get\fR, 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. .TP \fBftp::MkDir\fR \fIhandle\fR \fIdirectory\fR\fR This command creates the specified \fIdirectory\fR 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. .TP \fBftp::RmDir\fR \fIhandle\fR \fIdirectory\fR\fR 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. .TP \fBftp::Quote\fR \fIhandle\fR \fIarg1\fR \fIarg2\fR \fI...\fR\fR 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. .sp 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. .TP \fBftp::DisplayMsg\fR \fIhandle\fR \fImsg\fR ?\fIstate\fR?\fR 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 \fIstdout\fR (if \fIVERBOSE\fR 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 \fBlog\fR package can be useful for this. .TP \fBftp::VERBOSE\fR A state variable controlling the output of the package. Setting \fIftp::VERBOSE\fR to \fI1\fR forces the package to show all responses from a remote server. The default value is \fI0\fR. .TP \fBftp::DEBUG\fR A state variable controlling the output of ftp. Setting \fIftp::DEBUG\fR to \fI1\fR enables debugging and forces the package to show all return codes, states, state changes and "real" ftp commands. The default value is \fI0\fR. .SH "BUGS" .PP The correct execution of many commands depends upon the proper behavior by the remote server, network and router configuration. .PP An update command placed in the procedure \fBDisplayMsg\fR may run into persistent errors or infinite loops. The solution to this problem is to use \fBupdate idletasks\fR instead of \fBupdate\fR. .SH "SEE ALSO" ftpd, smtp, pop3, mime .SH "KEYWORDS" ftp, rfc..., internet, net