1ftp(n)                            ftp client                            ftp(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       ftp - Client-side tcl implementation of the ftp protocol
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require ftp  ?2.4.13?
14
15       ::ftp::Open server user passwd ?options?
16
17       ::ftp::Close handle
18
19       ::ftp::Cd handle directory
20
21       ::ftp::Pwd handle
22
23       ::ftp::Type handle ?ascii|binary|tenex?
24
25       ::ftp::List handle ?pattern?
26
27       ::ftp::NList handle ?directory?
28
29       ::ftp::FileSize handle file
30
31       ::ftp::ModTime handle file
32
33       ::ftp::Delete handle file
34
35       ::ftp::Rename handle from to
36
37       ::ftp::Put handle (local | -data data | -channel chan) ?remote?
38
39       ::ftp::Append handle (local | -data data | -channel chan) ?remote?
40
41       ::ftp::Get handle remote ?(local | -variable varname | -channel chan)?
42
43       ::ftp::Reget handle remote ?local? ?from? ?to?
44
45       ::ftp::Newer handle remote ?local?
46
47       ::ftp::MkDir handle directory
48
49       ::ftp::RmDir handle directory
50
51       ::ftp::Quote handle arg1 arg2 ...
52
53       ::ftp::DisplayMsg handle msg ?state?
54
55______________________________________________________________________________
56

DESCRIPTION

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
62       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
70       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
77       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
87       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

API

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
99              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
108              The  options overwrite some default values or set special abili‐
109              ties:
110
111              -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
118              -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
123              -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
130              -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
139              -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
144                     When evaluating the callback one argument is appended  to
145                     the  callback  script,  the current accumulated number of
146                     bytes transferred so far.
147
148              -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
155                     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
162              -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
170       ::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
179       ::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
186              ·      a subdirectory of the current directory,
187
188              ·      Two dots, ..  (as an indicator for the  parent  directory
189                     of the current directory)
190
191              ·      or a fully qualified path to a new working directory.
192
193       ::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
198       ::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
203              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
211       ::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
220              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
227              If the command fails an empty list is returned.
228
229       ::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
234       ::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
238              ATTENTION!  It  will not work properly when in ascii mode and is
239              not supported by all ftp server implementations.
240
241       ::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
248       ::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
253       ::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
260       ::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
270              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
274              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
280       ::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
285       ::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
297              If -variable varname is specified, the  system  will  store  the
298              retrieved data into the variable varname instead of a file.
299
300              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
305       ::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
315              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
321       ::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
329       ::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
337       ::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
343       ::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
351              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
355       ::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
365       ::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
370       ::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

BUGS

377       The correct execution of many commands depends upon the proper behavior
378       by the remote server, network and router configuration.
379
380       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

BUGS, IDEAS, FEEDBACK

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
391       When proposing code changes, please provide unified diffs, i.e the out‐
392       put of diff -u.
393
394       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

SEE ALSO

400       ftpd, mime, pop3, smtp
401

KEYWORDS

403       ftp, internet, net, rfc 959
404

CATEGORY

406       Networking
407
408
409
410tcllib                              2.4.13                              ftp(n)
Impressum