ftp(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

✨ ftp(n) — ftp client ✨

okay so this is the page for ftp, straight out of the ftp(n) manual — the "ftp client" one. Buckle up bestie, it's a long one, and we're doing it in two parts 💖

🌸 NAME 🌸

ftp — Client-side tcl implementation of the ftp protocol 🦋

🎀 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 is literally the client side of the ftp protocol, exactly as specified in RFC 959 (<http://www.rfc-editor.org/rfc/rfc959.txt> — no, that's the real URL, it's fine). And the tea? It implements both active (that's the default, btw) and passive ftp sessions. Versatile queen 👑

A brand new ftp session gets started with ::ftp::Open. To shut an existing ftp session down you use ::ftp::Close. Every other command? Restricted to an open ftp session only. Use them out of context and they will generate errors — like, they will not play with you, periodt. The ftp package also comes with file and directory manipulating commands for remote sites. Wanna do the same operations on your local site instead? Use the 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:

  • Set ::ftp::VERBOSE to "1" and the package is forced to show all responses from a remote server. The default value is "0".
  • Set ::ftp::DEBUG to "1" and debugging turns on, forcing the package to show all return codes, states, state changes and "real" ftp commands. The default value is "0".

The command ::ftp::DisplayMsg is what shows the different messages from the ftp session. Whether it actually gets called is decided by the setting of ::ftp::VERBOSE. The current implementation of this command uses the log package of tcllib to write the messages to their final destination. Which means — icon behaviour — the behaviour of ::ftp::DisplayMsg can be customized without ever changing its implementation. And for more radical changes, overwriting its implementation from 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 handle 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 transfer completes. When that happens the server will write the result response for the transfer to it and close the connection afterward. Bye bestie, gate closed 🚪

🌈 ::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. Neat and tidy, love that for us 💅

🌈 ::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 one yeets a file off the ftp server, no cap. It hands back 1 if the file got successfully deleted, or 0 if it failed. That's the whole arc 💅
  • ::ftp::Rename handle from to — renames the file from in the current directory of the ftp server to the new file name to. Lowkey important: that new name must not be the same as any existing subdirectory or file name. It returns 1 if the file was successfully renamed, or 0 if it failed.
  • ::ftp::Put handle (local | -data data | -channel chan) ?remote? — this is the upload queen 👑. It transfers a local file local to a remote file remote on the ftp server. If the file paths you pass in aren't fully qualified path names, the command just uses the current directory on both the local and the remote host. And if you don't specify a remote file name at all, the server uses the name of the local file as the name of the remote file. Returns 1 for a successful transfer, 0 if it failed.
    • -data data — instead of a local file, you pass data, and the system doesn't transfer a file at all, it transfers the data you passed in. In this case the name of the remote file has to be specified — no remote name, no party 🙈
    • -channel chan — instead of a local file, the system reads the contents of the channel chan and writes this to the remote file. Same deal: the name of the remote file has to be specified. And after the transfer, chan will be closed. Periodt.
  • ::ftp::Append handle (local | -data data | -channel chan) ?remote? — behaves like ::ftp::Puts, but it appends the transferred information to the remote file instead of overwriting. If the file didn't exist on the server yet, it will be created. Baby's first file, iconic ✨
  • ::ftp::Get handle remote ?(local | -variable varname | -channel chan)? — the download bestie 🫶. It retrieves a remote file remote on the ftp server and stores its contents into the local file local. If the file paths you pass in aren't fully qualified path names, the command uses the current directory on the local and remote host. If you leave the local file name unspecified, the server uses the name of the remote file as the name of the local file. Returns 1 for a successful transfer, 0 if it failed. Also: it will throw an error if the directory that the file local is supposed to go in doesn't exist. So like, make the folder first, bestie 😭
    • -variable varname — the system stores the retrieved data into the variable varname instead of into a file. Cute.
    • -channel chan — the system writes the retrieved data into the channel chan instead of into a file. Note that the system will not close chan after the transfer — that's the responsibility of the caller to ::ftp::Get. You closed it, you own it 💀
  • ::ftp::Reget handle remote ?local? ?from? ?to? — behaves like ::ftp::Get, except that if the local file local exists and is smaller than the 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. It will throw an error if the directory the file local is to be placed in does not exist. This one is highkey a lifesaver when you're transferring very large files over networks that tend to drop connections. The comeback kid, fr fr 🔥
    • If you specify the additional byte offsets from and to, the command changes its behaviour and downloads exactly the specified slice of the remote file. Heads up: this mode is possible only if a local destination is explicitly provided. And if you omit to, it just downloads till the end of the file. Slice it, serve it 🍓
  • ::ftp::Newer handle remote ?local? — behaves like ::ftp::Get, except 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 doesn't exist on the local system, the remote file is considered newer. Also throws an error if the directory the file local is to be placed in does not exist. Only the freshest, ngl 🌸
  • ::ftp::MkDir handle directory — creates the specified directory on the ftp server. If the specified path is relative, the new directory gets created as a subdirectory of the current working directory. Otherwise the created directory will have the specified path name. Returns 1 for a successful creation of the directory, 0 if it failed. New folder who dis 💖
  • ::ftp::RmDir handle directory — removes the specified directory on the ftp server. Big caveat: the remote directory has to be empty or the command will fail. Returns 1 for a successful removal of the directory, 0 if it failed. Empty it out first, bestie 🧚
  • ::ftp::Quote handle arg1 arg2 ... — this one is the wildcard of the group. It sends an arbitrary ftp command to the server. It cannot be used to obtain a directory listing or for transferring files — sorry babes. It's included so an application can execute commands on the ftp server that aren't provided by this package. The arguments are sent verbatim, i.e. as is, with no changes. Exactly what you typed, character for character 💅
    • And in contrast to the other commands in this package, this command will not parse the response it got from the ftp server — it just returns it verbatim to the caller. Raw, unfiltered, main character energy 🌈
  • ::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 simply: it writes the messages to stdout (if ::ftp::VERBOSE was set, see below) and throws tcl errors for error messages. It's the responsibility of the application to overwrite it as needed. The author recommends a state variable for different states assigned to different colors — and the package log is useful for this. Go on, give it a glow-up 🎀
  • ::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". Turn it on when you want to see everything, every little thing 👀

💀 BUGS 💀

The correct execution of many commands depends upon the proper behavior by the remote server, network and router configuration. So like, it's not always you, sometimes it's them 🙈

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. Write that down, bestie — update idletasks, not update. Save yourself the loop 💀

🫶 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](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas for enhancements you may have for either package and/or documentation. We love a bug report that's actually helpful ✨

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. Do it right, do it cute 🎀

👑 SEE ALSO 👑

ftpd, mime, pop3, smtp

⭐ KEYWORDS ⭐

ftp, internet, net, rfc 959

🌸 CATEGORY 🌸

Networking

okay bestie that's the whole page, we ate and left no crumbs 🍓 this was tcllib version 2.4.14, the ftp(n) manual page, and yeah — you're officially the ftp main character now. go forth and transfer responsibly 💖✨

📦 where this page comes from