1mNAME0m
       file - Manipulate file names and attributes

1mSYNOPSIS0m
       1mfile 4m22moption24m 4mname24m ?4marg24m 4marg24m 4m...24m?


1mDESCRIPTION0m
       This   command   provides  several  operations  on  a  file's  name  or
       attributes.  4mName24m is the name of a file; if it  starts  with  a  tilde,
       then  tilde  substitution is done before executing the command (see the
       manual entry for 1mfilename 22mfor details).  4mOption24m indicates  what  to  do
       with  the file name.  Any unique abbreviation for 4moption24m is acceptable.
       The valid options are:

       1mfile atime 4m22mname24m ?1mtime22m?
              Returns a decimal string giving the time at which file 4mname24m  was
              last  accessed.   If  4mtime24m is specified, it is an access time to
              set for the file.  The time is measured in  the  standard  POSIX
              fashion  as seconds from a fixed starting time (often January 1,
              1970).  If the file doesn't exist or its access time  cannot  be
              queried or set then an error is generated.  On Windows, FAT file
              systems do not support access time.

       1mfile attributes 4m22mname0m

       1mfile attributes 4m22mname24m ?1moption22m?

       1mfile attributes 4m22mname24m ?1moption value option value...22m?
              This subcommand returns or sets platform specific values associ-
              ated  with a file. The first form returns a list of the platform
              specific flags and their values. The  second  form  returns  the
              value  for  the specific option. The third form sets one or more
              of the values. The values are as follows:

              On Unix, 1m-group 22mgets or sets the group  name  for  the  file.  A
              group  id  can  be  given to the command, but it returns a group
              name. 1m-owner 22mgets or sets the user name  of  the  owner  of  the
              file.  The  command returns the owner name, but the numerical id
              can be passed when  setting  the  owner.  1m-permissions  22msets  or
              retrieves  the octal code that chmod(1) uses.  This command does
              also  has  limited  support  for  setting  using  the   symbolic
              attributes for chmod(1), of the form [ugo]?[[+-=][rwxst],[...]],
              where multiple symbolic attributes can be  separated  by  commas
              (example:  1mu+s,go-rw  22madd  sticky  bit for user, remove read and
              write permissions for group and other).  A simplified  1mls  22mstyle
              string,  of  the  form rwxrwxrwx (must be 9 characters), is also
              supported (example: 1mrwxr-xr-t 22mis equivalent to 01755).

              On Windows, 1m-archive 22mgives the value or sets or clears  the  ar-
              chive  attribute of the file. 1m-hidden 22mgives the value or sets or
              clears the hidden attribute of the file. 1m-longname  22mwill  expand
              each  path element to its long version. This attribute cannot be
              set. 1m-readonly 22mgives the value or sets or  clears  the  readonly
              attribute  of  the  file.  1m-shortname 22mgives a string where every
              path element is replaced with its short  (8.3)  version  of  the
              name.  This  attribute  cannot  be set. 1m-system 22mgives or sets or
              clears the value of the system attribute of the file.

              On Macintosh, 1m-creator 22mgives or sets the Finder creator type  of
              the  file.  1m-hidden 22mgives or sets or clears the hidden attribute
              of the file. 1m-readonly 22mgives or  sets  or  clears  the  readonly
              attribute  of the file. Note that directories can only be locked
              if File Sharing is turned on. 1m-type 22mgives  or  sets  the  Finder
              file type for the file.

       1mfile channels ?4m22mpattern24m?
              If  4mpattern24m isn't specified, returns a list of names of all reg-
              istered open channels in this interpreter.  If 4mpattern24m is speci-
              fied,  only those names matching 4mpattern24m are returned.  Matching
              is determined using the same rules as for 1mstring match22m.

       1mfile copy 22m?1m-force22m? ?1m--22m? 4msource24m 4mtarget0m

       1mfile copy 22m?1m-force22m? ?1m--22m? 4msource24m ?4msource24m ...? 4mtargetDir0m
              The first form makes a copy of  the  file  or  directory  4msource0m
              under  the  pathname 4mtarget24m. If 4mtarget24m is an existing directory,
              then the second form is used.  The  second  form  makes  a  copy
              inside  4mtargetDir24m of each 4msource24m file listed.  If a directory is
              specified as a 4msource24m, then the contents of the  directory  will
              be recursively copied into 4mtargetDir24m. Existing files will not be
              overwritten unless the 1m-force 22moption is specified.  When copying
              within a single filesystem, 4mfile24m 4mcopy24m will copy soft links (i.e.
              the links themselves are copied, not the things they point  to).
              Trying to overwrite a non-empty directory, overwrite a directory
              with a file, or overwrite a  file  with  a  directory  will  all
              result  in  errors  even if 4m-force24m was specified.  Arguments are
              processed in the order specified, halting at the first error, if
              any.  A 1m-- 22mmarks the end of switches; the argument following the
              1m-- 22mwill be treated as a 4msource24m even if it starts with a 1m-22m.

       1mfile delete 22m?1m-force22m? ?1m--22m? 4mpathname24m ?4mpathname24m ... ?
              Removes the file or directory specified by each  4mpathname24m  argu-
              ment.   Non-empty directories will be removed only if the 1m-force0m
              option is specified.  When  operating  on  symbolic  links,  the
              links themselves will be deleted, not the objects they point to.
              Trying to delete a non-existent file is not considered an error.
              Trying  to  delete  a  read-only  file will cause the file to be
              deleted, even if the 1m-force 22mflags  is  not  specified.   If  the
              1m-force 22moption is specified on a directory, Tcl will attempt both
              to change permissions and move the current directory  'pwd'  out
              of  the given path if that is necessary to allow the deletion to
              proceed.  Arguments are processed in the order specified,  halt-
              ing at the first error, if any.  A 1m-- 22mmarks the end of switches;
              the argument following the 1m-- 22mwill be treated as a 4mpathname24m even
              if it starts with a 1m-22m.

       1mfile dirname 4m22mname0m
              Returns  a  name comprised of all of the path components in 4mname0m
              excluding the last element.  If 4mname24m is a relative file name and
              only  contains one path element, then returns ``1m.22m'' (or ``1m:22m'' on
              the Macintosh).  If 4mname24m refers to a root  directory,  then  the
              root directory is returned.  For example,
                     1mfile dirname c:/0m
              returns 1mc:/22m.

              Note  that  tilde  substitution  will only be performed if it is
              necessary to complete the command. For example,
                     1mfile dirname ~/src/foo.c0m
              returns 1m~/src22m, whereas
                     1mfile dirname ~0m
              returns 1m/home 22m(or something similar).

       1mfile executable 4m22mname0m
              Returns 1m1 22mif file 4mname24m is executable by the current user, 1m0 22moth-
              erwise.

       1mfile exists 4m22mname0m
              Returns  1m1  22mif  file 4mname24m exists and the current user has search
              privileges for the directories leading to it, 1m0 22motherwise.

       1mfile extension 4m22mname0m
              Returns all of the characters in 4mname24m after  and  including  the
              last dot in the last element of 4mname24m.  If there is no dot in the
              last element of 4mname24m then returns the empty string.

       1mfile isdirectory 4m22mname0m
              Returns 1m1 22mif file 4mname24m is a directory, 1m0 22motherwise.

       1mfile isfile 4m22mname0m
              Returns 1m1 22mif file 4mname24m is a regular file, 1m0 22motherwise.

       1mfile join 4m22mname24m ?4mname24m 4m...24m?
              Takes one or more file names and combines them, using  the  cor-
              rect  path  separator for the current platform.  If a particular
              4mname24m is relative, then it will be joined to  the  previous  file
              name  argument.   Otherwise,  any earlier arguments will be dis-
              carded, and joining will proceed from the current argument.  For
              example,
                     1mfile join a b /foo bar0m
              returns 1m/foo/bar22m.

              Note  that any of the names can contain separators, and that the
              result is always canonical for the current platform: 1m/ 22mfor  Unix
              and Windows, and 1m: 22mfor Macintosh.

       1mfile link ?4m22m-linktype24m? 4mlinkName24m ?4mtarget24m?
              If  only  one  argument is given, that argument is assumed to be
              4mlinkName24m, and this command returns the value of the  link  given
              by  4mlinkName24m  (i.e.  the  name  of  the  file it points to).  If
              4mlinkName24m isn't a link or its value cannot be read (as, for exam-
              ple,  seems to be the case with hard links, which look just like
              ordinary files), then an error is returned.  If 2 arguments  are
              given,  then  these  are  assumed  to be 4mlinkName24m and 4mtarget24m. If
              4mlinkName24m already exists, or if 4mtarget24m doesn't  exist,  an  error
              will  be  returned.   Otherwise,  Tcl  creates a new link called
              4mlinkName24m which points to the existing filesystem object at  4mtar-0m
              4mget24m,  where the type of the link is platform-specific (on Unix a
              symbolic link will be the default).  This is useful for the case
              where  the user wishes to create a link in a cross-platform way,
              and doesn't care what type of link  is  created.   If  the  user
              wishes  to  make  a link of a specific type only, (and signal an
              error if for  some  reason  that  is  not  possible),  then  the
              optional  4m-linktype24m  argument  should be given.  Accepted values
              for 4m-linktype24m are "-symbolic" and "-hard".  When creating  links
              on  filesystems  that either do not support any links, or do not
              support the specific type requested, an error  message  will  be
              returned.   In  particular  Windows 95, 98 and ME do not support
              any links at present, but most Unix platforms support both  sym-
              bolic and hard links (the latter for files only), MacOS supports
              symbolic links and Windows NT/2000/XP (on NTFS  drives)  support
              symbolic directory links and hard file links.

       1mfile lstat 4m22mname24m 4mvarName0m
              Same  as  1mstat  22moption  (see below) except uses the 4mlstat24m kernel
              call instead of 4mstat24m.  This means that if 4mname24m refers to a  sym-
              bolic  link  the information returned in 4mvarName24m is for the link
              rather than the file it refers to.  On systems that  don't  sup-
              port  symbolic links this option behaves exactly the same as the
              1mstat 22moption.

       1mfile mkdir 4m22mdir24m ?4mdir24m ...?
              Creates each directory specified.  For each pathname 4mdir24m  speci-
              fied,  this command will create all non-existing parent directo-
              ries as well as 4mdir24m itself.  If an existing directory is  speci-
              fied,  then no action is taken and no error is returned.  Trying
              to overwrite an existing file with a directory will result in an
              error.   Arguments are processed in the order specified, halting
              at the first error, if any.

       1mfile mtime 4m22mname24m ?4mtime24m?
              Returns a decimal string giving the time at which file 4mname24m  was
              last  modified.  If 4mtime24m is specified, it is a modification time
              to set for the file (equivalent to Unix  1mtouch22m).   The  time  is
              measured  in  the standard POSIX fashion as seconds from a fixed
              starting time (often January 1,  1970).   If  the  file  doesn't
              exist  or  its  modified  time  cannot be queried or set then an
              error is generated.

       1mfile nativename 4m22mname0m
              Returns the platform-specific name of the file. This  is  useful
              if  the  filename is needed to pass to a platform-specific call,
              such as exec under Windows or AppleScript on the Macintosh.

       1mfile normalize 4m22mname0m
              Returns a unique normalized path representation  for  the  file-
              system  object  (file, directory, link, etc), whose string value
              can be used as a unique identifier for it.  A normalized path is
              an  absolute path which has all '../', './' removed.  Also it is
              one which is in the ``standard'' format for the native platform.
              On  MacOS,  Unix, this means the segments leading up to the path
              must be free of symbolic links/aliases (but the very  last  path
              component  may be a symbolic link), and on Windows it also means
              we want the long form with that  form's  case-dependence  (which
              gives us a unique, case-dependent path).  The one exception con-
              cerning the last link in the path is necessary, because  Tcl  or
              the  user may wish to operate on the actual symbolic link itself
              (for example 'file  delete',  'file  rename',  'file  copy'  are
              defined  to  operate  on  symbolic links, not on the things that
              they point to).

       1mfile owned 4m22mname0m
              Returns 1m1 22mif file 4mname24m is owned by the current  user,  1m0  22mother-
              wise.

       1mfile pathtype 4m22mname0m
              Returns  one  of  1mabsolute22m,  1mrelative22m,  1mvolumerelative22m.  If 4mname0m
              refers to a specific file on a specific volume,  the  path  type
              will be 1mabsolute22m.  If 4mname24m refers to a file relative to the cur-
              rent working directory, then the path type will be 1mrelative22m.  If
              4mname24m  refers to a file relative to the current working directory
              on a specified volume, or to a  specific  file  on  the  current
              working volume, then the file type is 1mvolumerelative22m.

       1mfile readable 4m22mname0m
              Returns 1m1 22mif file 4mname24m is readable by the current user, 1m0 22mother-
              wise.

       1mfile readlink 4m22mname0m
              Returns the value of the symbolic link given by 4mname24m  (i.e.  the
              name  of  the file it points to).  If 4mname24m isn't a symbolic link
              or its value cannot be read, then an error is returned.  On sys-
              tems that don't support symbolic links this option is undefined.

       1mfile rename 22m?1m-force22m? ?1m--22m? 4msource24m 4mtarget0m

       1mfile rename 22m?1m-force22m? ?1m--22m? 4msource24m ?4msource24m ...? 4mtargetDir0m
              The first form takes the file or directory specified by pathname
              4msource24m and renames it to 4mtarget24m, moving the file if the pathname
              4mtarget24m specifies a name in a different directory.  If 4mtarget24m  is
              an existing directory, then the second form is used.  The second
              form moves each 4msource24m file or directory into the directory 4mtar-0m
              4mgetDir24m. Existing files will not be overwritten unless the 1m-force0m
              option is specified.  When operating inside a single filesystem,
              Tcl  will rename symbolic links rather than the things that they
              point to.  Trying to overwrite a non-empty directory,  overwrite
              a  directory  with  a  file, or a file with a directory will all
              result in errors.  Arguments are processed in the  order  speci-
              fied, halting at the first error, if any.  A 1m-- 22mmarks the end of
              switches; the argument following the 1m-- 22mwill  be  treated  as  a
              4msource24m even if it starts with a 1m-22m.

       1mfile rootname 4m22mname0m
              Returns  all  of  the characters in 4mname24m up to but not including
              the last ``.'' character in the last component of name.  If  the
              last component of 4mname24m doesn't contain a dot, then returns 4mname24m.

       1mfile separator 22m?4mname24m?
              If no argument is given, returns the character which is used  to
              separate  path segments for native files on this platform.  If a
              path is given, the filesystem responsible for that path is asked
              to  return  its  separator character.  If no file system accepts
              4mname24m, an error is generated.

       1mfile size 4m22mname0m
              Returns a decimal string giving the size of file 4mname24m in  bytes.
              If  the file doesn't exist or its size cannot be queried then an
              error is generated.

       1mfile split 4m22mname0m
              Returns a list whose elements are the path components  in  4mname24m.
              The  first  element  of the list will have the same path type as
              4mname24m.  All other elements will  be  relative.   Path  separators
              will  be discarded unless they are needed ensure that an element
              is unambiguously relative.  For example, under Unix
                     file split /foo/~bar/baz
              returns 1m/  foo  ./~bar  baz 22mto ensure that later  commands  that
              use  the third component do not attempt to perform tilde substi-
              tution.

       1mfile stat  4m22mname24m 4mvarName0m
              Invokes the 1mstat 22mkernel call on  4mname24m,  and  uses  the  variable
              given  by  4mvarName24m  to hold information returned from the kernel
              call.  4mVarName24m is treated as an array variable, and the  follow-
              ing  elements  of that variable are set: 1matime22m, 1mctime22m, 1mdev22m, 1mgid22m,
              1mino22m, 1mmode22m, 1mmtime22m, 1mnlink22m, 1msize22m, 1mtype22m, 1muid22m.  Each  element  except
              1mtype  22mis  a  decimal  string with the value of the corresponding
              field from the 1mstat 22mreturn structure; see the manual  entry  for
              1mstat  22mfor  details on the meanings of the values.  The 1mtype 22mele-
              ment gives the type of the file in the same form returned by the
              command 1mfile type22m.  This command returns an empty string.

       1mfile system 4m22mname0m
              Returns  a  list of two elements, the first of which is the name
              of the filesystem to use for the file, and the second  an  arbi-
              trary string representing the filesystem-specific nature or type
              of the location within that filesystem.  If  a  filesystem  only
              supports  one type of file, the second element may be null.  For
              example the native files have a first element  'native',  and  a
              second  element  which  is a platform-specific type name for the
              file's system (e.g. 'NTFS', 'FAT', etc), or possibly  the  empty
              string  if no further information is available or if this is not
              implemented.  A generic virtual file  system  might  return  the
              list  'vfs ftp' to represent a file on a remote ftp site mounted
              as a virtual filesystem through an extension called  'vfs'.   If
              the  file  does not belong to any filesystem, an error is gener-
              ated.

       1mfile tail 4m22mname0m
              Returns all of the characters in 4mname24m after the  last  directory
              separator.  If 4mname24m contains no separators then returns 4mname24m.

       1mfile type 4m22mname0m
              Returns a string giving the type of file 4mname24m, which will be one
              of 1mfile22m, 1mdirectory22m, 1mcharacterSpecial22m, 1mblockSpecial22m, 1mfifo22m,  1mlink22m,
              or 1msocket22m.

       1mfile volumes0m
              Returns the absolute paths to the volumes mounted on the system,
              as a proper Tcl list.  On the Macintosh, this will be a list  of
              the  mounted drives, both local and network.  N.B. if two drives
              have the same name, they will both appear on  the  volume  list,
              but  there  is currently no way, from Tcl, to access any but the
              first of these drives.  On UNIX, the command will always  return
              "/",  since all filesystems are locally mounted.  On Windows, it
              will return a list of the  available  local  drives  (e.g.  {a:/
              c:/}).

       1mfile writable 4m22mname0m
              Returns 1m1 22mif file 4mname24m is writable by the current user, 1m0 22mother-
              wise.

1mPORTABILITY ISSUES0m
       1mUnix0m
              These commands always operate using  the  real  user  and  group
              identifiers, not the effective ones.

1mEXAMPLES0m
       This  procedure  shows  how  to search for C files in a given directory
       that have a correspondingly-named object file in the current directory:
              proc findMatchingCFiles {dir} {
                 set files {}
                 switch $::tcl_platform(platform) {
                    windows {
                       set ext .obj
                    }
                    unix {
                       set ext .o
                    }
                 }
                 foreach file [glob -nocomplain -directory $dir *.c] {
                    set objectFile [1mfile tail 22m[1mfile rootname 22m$file]]$ext
                    if {[1mfile exists 22m$objectFile]} {
                       lappend files $file
                    }
                 }
                 return $files
              }

       Rename  a file and leave a symbolic link pointing from the old location
       to the new place:
              set oldName foobar.txt
              set newName foo/bar.txt
              # Make sure that where we're going to move to exists...
              if {![1mfile isdirectory 22m[1mfile dirname 22m$newName]]} {
                 1mfile mkdir 22m[1mfile dirname 22m$newName]
              }
              1mfile rename 22m$oldName $newName
              1mfile link 22m-symbolic $oldName $newName


1mSEE ALSO0m
       filename(n), open(n),  close(n),  eof(n),  gets(n),  tell(n),  seek(n),
       fblocked(n), flush(n)


1mKEYWORDS0m
       attributes,  copy  files,  delete  files,  directory, file, move files,
