1file(n)                      Tcl Built-In Commands                     file(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       file - Manipulate file names and attributes
9

SYNOPSIS

11       file option name ?arg arg ...?
12______________________________________________________________________________
13

DESCRIPTION

15       This   command   provides  several  operations  on  a  file's  name  or
16       attributes.  Name is the name of a file; if it  starts  with  a  tilde,
17       then  tilde  substitution is done before executing the command (see the
18       manual entry for filename for details).  Option indicates  what  to  do
19       with  the file name.  Any unique abbreviation for option is acceptable.
20       The valid options are:
21
22       file atime name ?time?
23              Returns a decimal string giving the time at which file name  was
24              last  accessed.   If  time is specified, it is an access time to
25              set for the file.  The time is measured in  the  standard  POSIX
26              fashion  as seconds from a fixed starting time (often January 1,
27              1970).  If the file does not exist or its access time cannot  be
28              queried or set then an error is generated.  On Windows, FAT file
29              systems do not support access time.
30
31       file attributes name
32
33       file attributes name ?option?
34
35       file attributes name ?option value option value...?
36              This subcommand returns or sets platform specific values associ‐
37              ated  with a file. The first form returns a list of the platform
38              specific flags and their values. The  second  form  returns  the
39              value  for  the specific option. The third form sets one or more
40              of the values. The values are as follows:
41
42              On Unix, -group gets or sets the group  name  for  the  file.  A
43              group  id  can  be  given to the command, but it returns a group
44              name. -owner gets or sets the user name  of  the  owner  of  the
45              file.  The  command returns the owner name, but the numerical id
46              can be passed when  setting  the  owner.  -permissions  sets  or
47              retrieves  the octal code that chmod(1) uses.  This command does
48              also  has  limited  support  for  setting  using  the   symbolic
49              attributes for chmod(1), of the form [ugo]?[[+-=][rwxst],[...]],
50              where multiple symbolic attributes can be  separated  by  commas
51              (example:  u+s,go-rw  add  sticky  bit for user, remove read and
52              write permissions for group and other).  A simplified  ls  style
53              string,  of  the  form rwxrwxrwx (must be 9 characters), is also
54              supported (example: rwxr-xr-t is equivalent to 01755).  On  ver‐
55              sions  of  Unix supporting file flags, -readonly gives the value
56              or sets or clears the readonly attribute of the file,  i.e.  the
57              user immutable flag uchg to chflags(1).
58
59              On  Windows,  -archive gives the value or sets or clears the ar‐
60              chive attribute of the file. -hidden gives the value or sets  or
61              clears  the  hidden attribute of the file. -longname will expand
62              each path element to its long version. This attribute cannot  be
63              set.  -readonly  gives  the value or sets or clears the readonly
64              attribute of the file. -shortname gives  a  string  where  every
65              path  element  is  replaced  with its short (8.3) version of the
66              name. This attribute cannot be set. -system  gives  or  sets  or
67              clears the value of the system attribute of the file.
68
69              On  Mac  OS X and Darwin, -creator gives or sets the Finder cre‐
70              ator type of the file. -hidden gives or sets or clears the  hid‐
71              den attribute of the file. -readonly gives or sets or clears the
72              readonly attribute of the file. -rsrclength gives the length  of
73              the resource fork of the file, this attribute can only be set to
74              the value 0, which results in the resource fork  being  stripped
75              off the file.
76
77       file channels ?pattern?
78              If pattern is not specified, returns a list of names of all reg‐
79              istered open channels in this interpreter.  If pattern is speci‐
80              fied,  only those names matching pattern are returned.  Matching
81              is determined using the same rules as for string match.
82
83       file copy ?-force? ?--? source target
84
85       file copy ?-force? ?--? source ?source ...? targetDir
86              The first form makes a copy of  the  file  or  directory  source
87              under  the  pathname target. If target is an existing directory,
88              then the second form is used.  The  second  form  makes  a  copy
89              inside  targetDir of each source file listed.  If a directory is
90              specified as a source, then the contents of the  directory  will
91              be recursively copied into targetDir. Existing files will not be
92              overwritten unless the -force option is specified (when Tcl will
93              also  attempt  to  adjust permissions on the destination file or
94              directory if that is necessary to allow the  copy  to  proceed).
95              When  copying  within  a  single filesystem, file copy will copy
96              soft links (i.e.  the  links  themselves  are  copied,  not  the
97              things  they  point to).  Trying to overwrite a non-empty direc‐
98              tory, overwrite a directory with a file,  or  overwrite  a  file
99              with  a  directory  will all result in errors even if -force was
100              specified.  Arguments are  processed  in  the  order  specified,
101              halting  at  the  first  error,  if  any.  A -- marks the end of
102              switches; the argument following the -- will  be  treated  as  a
103              source even if it starts with a -.
104
105       file delete ?-force? ?--? ?pathname ... ?
106              Removes  the  file or directory specified by each pathname argu‐
107              ment.  Non-empty directories will be removed only if the  -force
108              option  is  specified.   When  operating  on symbolic links, the
109              links themselves will be deleted, not the objects they point to.
110              Trying to delete a non-existent file is not considered an error.
111              Trying to delete a read-only file will  cause  the  file  to  be
112              deleted,  even  if  the  -force  flags is not specified.  If the
113              -force option is specified on a directory, Tcl will attempt both
114              to  change  permissions and move the current directory “pwd” out
115              of the given path if that is necessary to allow the deletion  to
116              proceed.   Arguments are processed in the order specified, halt‐
117              ing at the first error, if any.  A -- marks the end of switches;
118              the argument following the -- will be treated as a pathname even
119              if it starts with a -.
120
121       file dirname name
122              Returns a name comprised of all of the path components  in  name
123              excluding the last element.  If name is a relative file name and
124              only contains one path  element,  then  returns  “.”.   If  name
125              refers to a root directory, then the root directory is returned.
126              For example,
127
128                     file dirname c:/
129
130              returns c:/.
131
132              Note that tilde substitution will only be  performed  if  it  is
133              necessary to complete the command. For example,
134
135                     file dirname ~/src/foo.c
136
137              returns ~/src, whereas
138
139                     file dirname ~
140
141              returns /home (or something similar).
142
143       file executable name
144              Returns 1 if file name is executable by the current user, 0 oth‐
145              erwise. On Windows, which does not have an executable attribute,
146              the command treats all directories and any files with extensions
147              exe, com, cmd or bat as executable.
148
149       file exists name
150              Returns 1 if file name exists and the current  user  has  search
151              privileges for the directories leading to it, 0 otherwise.
152
153       file extension name
154              Returns  all  of  the characters in name after and including the
155              last dot in the last element of name.  If there is no dot in the
156              last element of name then returns the empty string.
157
158       file isdirectory name
159              Returns 1 if file name is a directory, 0 otherwise.
160
161       file isfile name
162              Returns 1 if file name is a regular file, 0 otherwise.
163
164       file join name ?name ...?
165              Takes  one  or more file names and combines them, using the cor‐
166              rect path separator for the current platform.  If  a  particular
167              name  is  relative,  then it will be joined to the previous file
168              name argument.  Otherwise, any earlier arguments  will  be  dis‐
169              carded, and joining will proceed from the current argument.  For
170              example,
171
172                     file join a b /foo bar
173
174              returns /foo/bar.
175
176              Note that any of the names can contain separators, and that  the
177              result  is always canonical for the current platform: / for Unix
178              and Windows.
179
180       file link ?-linktype? linkName ?target?
181              If only one argument is given, that argument is  assumed  to  be
182              linkName,  and  this command returns the value of the link given
183              by linkName (i.e. the name  of  the  file  it  points  to).   If
184              linkName  is  not  a  link  or its value cannot be read (as, for
185              example, seems to be the case with hard links, which  look  just
186              like ordinary files), then an error is returned.
187
188              If  2 arguments are given, then these are assumed to be linkName
189              and target. If linkName already exists, or if  target  does  not
190              exist,  an error will be returned.  Otherwise, Tcl creates a new
191              link called linkName which points  to  the  existing  filesystem
192              object  at  target (which is also the returned value), where the
193              type of the link is platform-specific (on Unix a  symbolic  link
194              will  be  the  default).   This is useful for the case where the
195              user wishes to create a link in a cross-platform way,  and  does
196              not care what type of link is created.
197
198              If  the user wishes to make a link of a specific type only, (and
199              signal an error if for some reason that is not  possible),  then
200              the  optional -linktype argument should be given.  Accepted val‐
201              ues for -linktype are “-symbolic” and “-hard”.
202
203              On Unix, symbolic links can be made to relative paths, and those
204              paths must be relative to the actual linkName's location (not to
205              the cwd), but on all other platforms where  relative  links  are
206              not  supported,  target  paths will always be converted to abso‐
207              lute, normalized form before the link is created (and  therefore
208              relative  paths  are  interpreted as relative to the cwd).  Fur‐
209              thermore, “~user” paths are always expanded  to  absolute  form.
210              When  creating  links  on filesystems that either do not support
211              any links, or do not support the  specific  type  requested,  an
212              error  message  will  be  returned.  Most Unix platforms support
213              both symbolic and hard links (the latter for files  only).  Win‐
214              dows  supports  symbolic  directory links and hard file links on
215              NTFS drives.
216
217       file lstat name varName
218              Same as stat option (see below) except  uses  the  lstat  kernel
219              call  instead of stat.  This means that if name refers to a sym‐
220              bolic link the information returned in varName is for  the  link
221              rather  than the file it refers to.  On systems that do not sup‐
222              port symbolic links this option behaves exactly the same as  the
223              stat option.
224
225       file mkdir ?dir ...?
226              Creates  each directory specified.  For each pathname dir speci‐
227              fied, this command will create all non-existing parent  directo‐
228              ries  as well as dir itself.  If an existing directory is speci‐
229              fied, then no action is taken and no error is returned.   Trying
230              to overwrite an existing file with a directory will result in an
231              error.  Arguments are processed in the order specified,  halting
232              at the first error, if any.
233
234       file mtime name ?time?
235              Returns  a decimal string giving the time at which file name was
236              last modified.  If time is specified, it is a modification  time
237              to  set  for  the  file (equivalent to Unix touch).  The time is
238              measured in the standard POSIX fashion as seconds from  a  fixed
239              starting  time  (often  January  1, 1970).  If the file does not
240              exist or its modified time cannot be  queried  or  set  then  an
241              error is generated.
242
243       file nativename name
244              Returns  the  platform-specific name of the file. This is useful
245              if the filename is needed to pass to a  platform-specific  call,
246              such  as  to  a  subprocess via exec under Windows (see EXAMPLES
247              below).
248
249       file normalize name
250              Returns a unique normalized path representation  for  the  file-
251              system  object  (file, directory, link, etc), whose string value
252              can be used as a unique identifier for it.  A normalized path is
253              an  absolute path which has all “../” and “./” removed.  Also it
254              is one which is in the “standard” format for  the  native  plat‐
255              form.   On  Unix, this means the segments leading up to the path
256              must be free of symbolic links/aliases (but the very  last  path
257              component  may be a symbolic link), and on Windows it also means
258              we want the long form with that  form's  case-dependence  (which
259              gives us a unique, case-dependent path).  The one exception con‐
260              cerning the last link in the path is necessary, because  Tcl  or
261              the  user may wish to operate on the actual symbolic link itself
262              (for example file delete, file rename, file copy are defined  to
263              operate  on  symbolic  links,  not on the things that they point
264              to).
265
266       file owned name
267              Returns 1 if file name is owned by the current  user,  0  other‐
268              wise.
269
270       file pathtype name
271              Returns  one  of  absolute,  relative,  volumerelative.  If name
272              refers to a specific file on a specific volume,  the  path  type
273              will  be absolute. If name refers to a file relative to the cur‐
274              rent working directory, then the path type will be relative.  If
275              name  refers to a file relative to the current working directory
276              on a specified volume, or to a  specific  file  on  the  current
277              working volume, then the path type is volumerelative.
278
279       file readable name
280              Returns 1 if file name is readable by the current user, 0 other‐
281              wise.
282
283       file readlink name
284              Returns the value of the symbolic link given by name  (i.e.  the
285              name  of the file it points to).  If name is not a symbolic link
286              or its value cannot be read, then an error is returned.  On sys‐
287              tems  that  do  not  support symbolic links this option is unde‐
288              fined.
289
290       file rename ?-force? ?--? source target
291
292       file rename ?-force? ?--? source ?source ...? targetDir
293              The first form takes the file or directory specified by pathname
294              source and renames it to target, moving the file if the pathname
295              target specifies a name in a different directory.  If target  is
296              an existing directory, then the second form is used.  The second
297              form moves each source file or directory into the directory tar‐
298              getDir. Existing files will not be overwritten unless the -force
299              option is specified.  When operating inside a single filesystem,
300              Tcl  will rename symbolic links rather than the things that they
301              point to.  Trying to overwrite a non-empty directory,  overwrite
302              a  directory  with  a  file, or a file with a directory will all
303              result in errors.  Arguments are processed in the  order  speci‐
304              fied, halting at the first error, if any.  A -- marks the end of
305              switches; the argument following the -- will  be  treated  as  a
306              source even if it starts with a -.
307
308       file rootname name
309              Returns  all  of  the characters in name up to but not including
310              the last “.”  character in the last component of name.   If  the
311              last  component  of  name  does  not contain a dot, then returns
312              name.
313
314       file separator ?name?
315              If no argument is given, returns the character which is used  to
316              separate  path segments for native files on this platform.  If a
317              path is given, the filesystem responsible for that path is asked
318              to  return  its  separator character.  If no file system accepts
319              name, an error is generated.
320
321       file size name
322              Returns a decimal string giving the size of file name in  bytes.
323              If the file does not exist or its size cannot be queried then an
324              error is generated.
325
326       file split name
327              Returns a list whose elements are the path components  in  name.
328              The  first  element  of the list will have the same path type as
329              name.  All other elements will  be  relative.   Path  separators
330              will  be discarded unless they are needed to ensure that an ele‐
331              ment is unambiguously relative.  For example, under Unix
332
333                     file split /foo/~bar/baz
334
335              returns “/  foo  ./~bar  baz” to ensure that later commands that
336              use  the third component do not attempt to perform tilde substi‐
337              tution.
338
339       file stat  name varName
340              Invokes the stat kernel call on  name,  and  uses  the  variable
341              given  by  varName  to hold information returned from the kernel
342              call.  VarName is treated as an array variable, and the  follow‐
343              ing  elements  of that variable are set: atime, ctime, dev, gid,
344              ino, mode, mtime, nlink, size, type, uid.  Each  element  except
345              type  is  a  decimal  string with the value of the corresponding
346              field from the stat return structure; see the manual  entry  for
347              stat  for  details on the meanings of the values.  The type ele‐
348              ment gives the type of the file in the same form returned by the
349              command file type.  This command returns an empty string.
350
351       file system name
352              Returns a list of one or two elements, the first of which is the
353              name of the filesystem to use for the file, and the  second,  if
354              given,  an arbitrary string representing the filesystem-specific
355              nature or type of the location within  that  filesystem.   If  a
356              filesystem  only  supports  one type of file, the second element
357              may not be supplied.  For example the native files have a  first
358              element  “native”,  and  a  second element which when given is a
359              platform-specific type name for the file's system (e.g.  “NTFS”,
360              “FAT”,  on Windows).  A generic virtual file system might return
361              the list “vfs ftp” to represent a file  on  a  remote  ftp  site
362              mounted  as  a  virtual  filesystem  through an extension called
363              “vfs”.  If the file does not belong to any filesystem, an  error
364              is generated.
365
366       file tail name
367              Returns  all  of the characters in the last filesystem component
368              of name.  Any trailing directory separator in name  is  ignored.
369              If name contains no separators then returns name.  So, file tail
370              a/b, file tail a/b/ and file tail b all return b.
371
372       file tempfile ?nameVar? ?template?
373              Creates a temporary file and returns a read-write channel opened │
374              on  that file.  If the nameVar is given, it specifies a variable │
375              that the name of the temporary file will  be  written  into;  if │
376              absent, Tcl will attempt to arrange for the temporary file to be │
377              deleted once it is  no  longer  required.  If  the  template  is │
378              present,  it  specifies parts of the template of the filename to │
379              use when creating it (such as the directory, base-name or exten‐ │
380              sion)  though  some  platforms  may  ignore some or all of these │
381              parts and use a built-in default instead.                        │
382
383              Note that temporary files are only ever created  on  the  native │
384              filesystem.  As  such,  they  can be relied upon to be used with │
385              operating-system native APIs and external programs that  require │
386              a filename.                                                      │
387
388       file type name
389              Returns a string giving the type of file name, which will be one
390              of file, directory, characterSpecial, blockSpecial, fifo,  link,
391              or socket.
392
393       file volumes
394              Returns the absolute paths to the volumes mounted on the system,
395              as a proper Tcl list.  Without any virtual  filesystems  mounted
396              as  root  volumes,  on UNIX, the command will always return “/”,
397              since all filesystems are locally mounted.  On Windows, it  will
398              return  a  list of the available local drives (e.g.  “a:/ c:/”).
399              If any virtual filesystem has mounted additional  volumes,  they
400              will be in the returned list.
401
402       file writable name
403              Returns 1 if file name is writable by the current user, 0 other‐
404              wise.
405

PORTABILITY ISSUES

407       Unix
408              These commands always operate using  the  real  user  and  group
409              identifiers, not the effective ones.
410
411       Windows
412              The  file owned subcommand uses the user identifier (SID) of the
413              process token, not the thread token which may  be  impersonating
414              some other user.
415

EXAMPLES

417       This  procedure  shows  how  to search for C files in a given directory
418       that have a correspondingly-named object file in the current directory:
419
420              proc findMatchingCFiles {dir} {
421                  set files {}
422                  switch $::tcl_platform(platform) {
423                      windows {
424                          set ext .obj
425                      }
426                      unix {
427                         set ext .o
428                      }
429                  }
430                  foreach file [glob -nocomplain -directory $dir *.c] {
431                      set objectFile [file tail [file rootname $file]]$ext
432                      if {[file exists $objectFile]} {
433                          lappend files $file
434                      }
435                  }
436                  return $files
437              }
438
439       Rename a file and leave a symbolic link pointing from the old  location
440       to the new place:
441
442              set oldName foobar.txt
443              set newName foo/bar.txt
444              # Make sure that where we're going to move to exists...
445              if {![file isdirectory [file dirname $newName]]} {
446                  file mkdir [file dirname $newName]
447              }
448              file rename $oldName $newName
449              file link -symbolic $oldName $newName
450
451       On  Windows,  a file can be “started” easily enough (equivalent to dou‐
452       ble-clicking on it in the Explorer interface) but the  name  passed  to
453       the operating system must be in native format:
454
455              exec {*}[auto_execok start] {} [file nativename ~/example.txt]
456

SEE ALSO

458       filename(n),  open(n),  close(n),  eof(n),  gets(n),  tell(n), seek(n),
459       fblocked(n), flush(n)
460

KEYWORDS

462       attributes, copy files, delete  files,  directory,  file,  move  files,
463       name, rename files, stat, user
464
465
466
467Tcl                                   8.3                              file(n)
Impressum