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