ftp(n) ftp client ftp(n) 







ftp - Client-side tcl implementation of the ftp protocol








package require Tcl 8.2


package require ftp ?2.4.9?


::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?












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::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 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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  

  
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.

  

  

  
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.








This document, and the package it describes, will undoubtedly
    contain bugs and other problems. Please report such in the category
    ftp of the Tcllib SF Trackers
    [http://sourceforge.net/tracker/?group_id=12883]. Please also report any
    ideas for enhancements you may have for either package and/or
  documentation.








ftpd, mime, pop3, smtp








ftp, internet, net, rfc 959








Networking







  

    2.4.9
    ftp