1ftp(n) ftp client ftp(n)
2______________________________________________________________________________
6
8 ftp - Client-side tcl implementation of the ftp protocol
9
11 package require Tcl 8.2
12 package require ftp ?2.4.13?
14 ::ftp::Open server user passwd ?options?
16 ::ftp::Close handle
18 ::ftp::Cd handle directory
20 ::ftp::Pwd handle
22 ::ftp::Type handle ?ascii|binary|tenex?
24 ::ftp::List handle ?pattern?
26 ::ftp::NList handle ?directory?
28 ::ftp::FileSize handle file
30 ::ftp::ModTime handle file
32 ::ftp::Delete handle file
34 ::ftp::Rename handle from to
36 ::ftp::Put handle (local | -data data | -channel chan) ?remote?
38 ::ftp::Append handle (local | -data data | -channel chan) ?remote?
40 ::ftp::Get handle remote ?(local | -variable varname | -channel chan)?
42 ::ftp::Reget handle remote ?local? ?from? ?to?
44 ::ftp::Newer handle remote ?local?
46 ::ftp::MkDir handle directory
48 ::ftp::RmDir handle directory
50 ::ftp::Quote handle arg1 arg2 ...
52 ::ftp::DisplayMsg handle msg ?state?
54______________________________________________________________________________
56
58 The ftp package provides the client side of the ftp protocol as speci‐
59 fied in RFC 959 (http://www.rfc-editor.org/rfc/rfc959.txt). The pack‐
60 age implements both active (default) and passive ftp sessions.
61 A new ftp session is started with the ::ftp::Open command. To shutdown
63 an existing ftp session use ::ftp::Close. All other commands are
64 restricted to usage in an an open ftp session. They will generate
65 errors if they are used out of context. The ftp package includes file
66 and directory manipulating commands for remote sites. To perform the
67 same operations on the local site use commands built into the core,
68 like cd or file.
69 The output of the package is controlled by two state variables,
71 ::ftp::VERBOSE and ::ftp::DEBUG. Setting ::ftp::VERBOSE to "1" forces
72 the package to show all responses from a remote server. The default
73 value is "0". Setting ::ftp::DEBUG to "1" enables debugging and forces
74 the package to show all return codes, states, state changes and "real"
75 ftp commands. The default value is "0".
76 The command ::ftp::DisplayMsg is used to show the different messages
78 from the ftp session. The setting of ::ftp::VERBOSE determines if this
79 command is called or not. The current implementation of the command
80 uses the log package of tcllib to write the messages to their final
81 destination. This means that the behaviour of ::ftp::DisplayMsg can be
82 customized without changing its implementation. For more radical
83 changes overwriting its implementation by the application is of course
84 still possible. Note that the default implementation honors the option
85 -output to ::ftp::Open for a session specific log command.
86 Caution: The default implementation logs error messages like all other
88 messages. If this behaviour is changed to throwing an error instead all
89 commands in the API will change their behaviour too. In such a case
90 they will not return a failure code as described below but pass the
91 thrown error to their caller.
92
94 ::ftp::Open server user passwd ?options?
95 This command is used to start a FTP session by establishing a
96 control connection to the FTP server. The defaults are used for
97 any option not specified by the caller.
98 The command takes a host name server, a user name user and a
100 password password as its parameters and returns a session handle
101 that is an integer number greater than or equal to "0", if the
102 connection is successfully established. Otherwise it returns
103 "-1". The server parameter must be the name or internet address
104 (in dotted decimal notation) of the ftp server to connect to.
105 The user and passwd parameters must contain a valid user name
106 and password to complete the login process.
107 The options overwrite some default values or set special abili‐
109 ties:
110 -blocksize size
112 The blocksize is used during data transfer. At most size
113 bytes are transfered at once. The default value for this
114 option is 4096. The package will evaluate the -progress
115 callback for the session after the transfer of each
116 block.
117 -timeout seconds
119 If seconds is non-zero, then ::ftp::Open sets up a time‐
120 out which will occur after the specified number of sec‐
121 onds. The default value is 600.
122 -port number
124 The port number specifies an alternative remote port on
125 the ftp server on which the ftp service resides. Most ftp
126 services listen for connection requests on the default
127 port 21. Sometimes, usually for security reasons, port
128 numbers other than 21 are used for ftp connections.
129 -mode mode
131 The transfer mode option determines if a file transfer
132 occurs in active or passive mode. In passive mode the
133 client will ask the ftp server to listen on a data port
134 and wait for the connection rather than to initiate the
135 process by itself when a data transfer request comes in.
136 Passive mode is normally a requirement when accessing
137 sites via a firewall. The default mode is active.
138 -progress callback
140 This callback is evaluated whenever a block of data was
141 transfered. See the option -blocksize for how to specify
142 the size of the transfered blocks.
143 When evaluating the callback one argument is appended to
145 the callback script, the current accumulated number of
146 bytes transferred so far.
147 -command callback
149 Specifying this option places the connection into asyn‐
150 chronous mode. The callback is evaluated after the com‐
151 pletion of any operation. When an operation is running no
152 further operations must be started until a callback has
153 been received for the currently executing operation.
154 When evaluating the callback several arguments are
156 appended to the callback script, namely the keyword of
157 the operation that has completed and any additional argu‐
158 ments specific to the operation. If an error occurred
159 during the execution of the operation the callback is
160 given the keyword error.
161 -output callback
163 This option has no default. If it is set the default
164 implementation of ::ftp::DisplayMsg will use its value as
165 command prefix to log all internal messages. The callback
166 will have three arguments appended to it before evalua‐
167 tion, the id of the session, the message itself, and the
168 connection state, in this order.
169 ::ftp::Close handle
171 This command terminates the specified ftp session. If no file
172 transfer is in progress, the server will close the control con‐
173 nection immediately. If a file transfer is in progress however,
174 the control connection will remain open until the transfers com‐
175 pletes. When that happens the server will write the result
176 response for the transfer to it and close the connection after‐
177 ward.
178 ::ftp::Cd handle directory
180 This command changes the current working directory on the ftp
181 server to a specified target directory. The command returns 1
182 if the current working directory was successfully changed to the
183 specified directory or 0 if it fails. The target directory can
184 be
185 · a subdirectory of the current directory,
187 · Two dots, .. (as an indicator for the parent directory
189 of the current directory)
190 · or a fully qualified path to a new working directory.
192 ::ftp::Pwd handle
194 This command returns the complete path of the current working
195 directory on the ftp server, or an empty string in case of an
196 error.
197 ::ftp::Type handle ?ascii|binary|tenex?
199 This command sets the ftp file transfer type to either ascii,
200 binary, or tenex. The command always returns the currently set
201 type. If called without type no change is made.
202 Currently only ascii and binary types are supported. There is
204 some early (alpha) support for Tenex mode. The type ascii is
205 normally used to convert text files into a format suitable for
206 text editors on the platform of the destination machine. This
207 mainly affects end-of-line markers. The type binary on the other
208 hand allows the undisturbed transfer of non-text files, such as
209 compressed files, images and executables.
210 ::ftp::List handle ?pattern?
212 This command returns a human-readable list of files. Wildcard
213 expressions such as "*.tcl" are allowed. If pattern refers to a
214 specific directory, then the contents of that directory are
215 returned. If the pattern is not a fully-qualified path name,
216 the command lists entries relative to the current remote direc‐
217 tory. If no pattern is specified, the contents of the current
218 remote directory is returned.
219 The listing includes any system-dependent information that the
221 server chooses to include. For example most UNIX systems produce
222 output from the command ls -l. The command returns the retrieved
223 information as a tcl list with one item per entry. Empty lines
224 and UNIX's "total" lines are ignored and not included in the
225 result as reported by this command.
226 If the command fails an empty list is returned.
228 ::ftp::NList handle ?directory?
230 This command has the same behavior as the ::ftp::List command,
231 except that it only retrieves an abbreviated listing. This means
232 only file names are returned in a sorted list.
233 ::ftp::FileSize handle file
235 This command returns the size of the specified file on the ftp
236 server. If the command fails an empty string is returned.
237 ATTENTION! It will not work properly when in ascii mode and is
239 not supported by all ftp server implementations.
240 ::ftp::ModTime handle file
242 This command retrieves the time of the last modification of the
243 file on the ftp server as a system dependent integer value in
244 seconds or an empty string if an error occurred. Use the built-
245 in command clock to convert the retrieves value into other for‐
246 mats.
247 ::ftp::Delete handle file
249 This command deletes the specified file on the ftp server. The
250 command returns 1 if the specified file was successfully deleted
251 or 0 if it failed.
252 ::ftp::Rename handle from to
254 This command renames the file from in the current directory of
255 the ftp server to the specified new file name to. This new file
256 name must not be the same as any existing subdirectory or file
257 name. The command returns 1 if the specified file was success‐
258 fully renamed or 0 if it failed.
259 ::ftp::Put handle (local | -data data | -channel chan) ?remote?
261 This command transfers a local file local to a remote file
262 remote on the ftp server. If the file parameters passed to the
263 command do not fully qualified path names the command will use
264 the current directory on local and remote host. If the remote
265 file name is unspecified, the server will use the name of the
266 local file as the name of the remote file. The command returns 1
267 to indicate a successful transfer and 0 in the case of a fail‐
268 ure.
269 If -data data is specified instead of a local file, the system
271 will not transfer a file, but the data passed into it. In this
272 case the name of the remote file has to be specified.
273 If -channel chan is specified instead of a local file, the sys‐
275 tem will not transfer a file, but read the contents of the chan‐
276 nel chan and write this to the remote file. In this case the
277 name of the remote file has to be specified. After the transfer
278 chan will be closed.
279 ::ftp::Append handle (local | -data data | -channel chan) ?remote?
281 This command behaves like ::ftp::Puts, but appends the trans‐
282 fered information to the remote file. If the file did not exist
283 on the server it will be created.
284 ::ftp::Get handle remote ?(local | -variable varname | -channel chan)?
286 This command retrieves a remote file remote on the ftp server
287 and stores its contents into the local file local. If the file
288 parameters passed to the command are not fully qualified path
289 names the command will use the current directory on local and
290 remote host. If the local file name is unspecified, the server
291 will use the name of the remote file as the name of the local
292 file. The command returns 1 to indicate a successful transfer
293 and 0 in the case of a failure. The command will throw an error
294 if the directory the file local is to be placed in does not
295 exist.
296 If -variable varname is specified, the system will store the
298 retrieved data into the variable varname instead of a file.
299 If -channel chan is specified, the system will write the
301 retrieved data into the channel chan instead of a file. The sys‐
302 tem will not close chan after the transfer, this is the respon‐
303 sibility of the caller to ::ftp::Get.
304 ::ftp::Reget handle remote ?local? ?from? ?to?
306 This command behaves like ::ftp::Get, except that if local file
307 local exists and is smaller than remote file remote, the local
308 file is presumed to be a partially transferred copy of the
309 remote file and the transfer is continued from the apparent
310 point of failure. The command will throw an error if the direc‐
311 tory the file local is to be placed in does not exist. This com‐
312 mand is useful when transferring very large files over networks
313 that tend to drop connections.
314 Specifying the additional byte offsets from and to will cause
316 the command to change its behaviour and to download exactly the
317 specified slice of the remote file. This mode is possible only
318 if a local destination is explicitly provided. Omission of to
319 leads to downloading till the end of the file.
320 ::ftp::Newer handle remote ?local?
322 This command behaves like ::ftp::Get, except that it retrieves
323 the remote file only if the modification time of the remote file
324 is more recent than the file on the local system. If the file
325 does not exist on the local system, the remote file is consid‐
326 ered newer. The command will throw an error if the directory the
327 file local is to be placed in does not exist.
328 ::ftp::MkDir handle directory
330 This command creates the specified directory on the ftp server.
331 If the specified path is relative the new directory will be cre‐
332 ated as a subdirectory of the current working directory. Else
333 the created directory will have the specified path name. The
334 command returns 1 to indicate a successful creation of the
335 directory and 0 in the case of a failure.
336 ::ftp::RmDir handle directory
338 This command removes the specified directory on the ftp server.
339 The remote directory has to be empty or the command will fail.
340 The command returns 1 to indicate a successful removal of the
341 directory and 0 in the case of a failure.
342 ::ftp::Quote handle arg1 arg2 ...
344 This command is used to send an arbitrary ftp command to the
345 server. It cannot be used to obtain a directory listing or for
346 transferring files. It is included to allow an application to
347 execute commands on the ftp server which are not provided by
348 this package. The arguments are sent verbatim, i.e. as is, with
349 no changes.
350 In contrast to the other commands in this package this command
352 will not parse the response it got from the ftp server but
353 return it verbatim to the caller.
354 ::ftp::DisplayMsg handle msg ?state?
356 This command is used by the package itself to show the different
357 messages from the ftp sessions. The package itself declares this
358 command very simple, writing the messages to stdout (if
359 ::ftp::VERBOSE was set, see below) and throwing tcl errors for
360 error messages. It is the responsibility of the application to
361 overwrite it as needed. A state variable for different states
362 assigned to different colors is recommended by the author. The
363 package log is useful for this.
364 ::ftp::VERBOSE
366 A state variable controlling the output of the package. Setting
367 ::ftp::VERBOSE to "1" forces the package to show all responses
368 from a remote server. The default value is "0".
369 ::ftp::DEBUG
371 A state variable controlling the output of ftp. Setting
372 ::ftp::DEBUG to "1" enables debugging and forces the package to
373 show all return codes, states, state changes and "real" ftp com‐
374 mands. The default value is "0".
375
377 The correct execution of many commands depends upon the proper behavior
378 by the remote server, network and router configuration.
379 An update command placed in the procedure ::ftp::DisplayMsg may run
381 into persistent errors or infinite loops. The solution to this problem
382 is to use update idletasks instead of update.
383
385 This document, and the package it describes, will undoubtedly contain
386 bugs and other problems. Please report such in the category ftp of the
387 Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
388 report any ideas for enhancements you may have for either package
389 and/or documentation.
390 When proposing code changes, please provide unified diffs, i.e the out‐
392 put of diff -u.
393 Note further that attachments are strongly preferred over inlined
395 patches. Attachments can be made by going to the Edit form of the
396 ticket immediately after its creation, and then using the left-most
397 button in the secondary navigation bar.
398
400 ftpd, mime, pop3, smtp
401
403 ftp, internet, net, rfc 959
404
406 Networking
407tcllib 2.4.13 ftp(n)