NAME
       file - Manipulate file names and attributes

SYNOPSIS
       file option name ?arg arg ...?


DESCRIPTION
       This  command provides several operations on a file's name
       or attributes.  Name is the name of a file; if  it  starts
       with  a tilde, then tilde substitution is done before exe-
       cuting the command (see the manual entry for filename  for
       details).  Option indicates what to do with the file name.
       Any unique abbreviation for  option  is  acceptable.   The
       valid options are:

       file atime name ?time?
              Returns  a  decimal string giving the time at which
              file name was last accessed.  If time is specified,
              it is an access time to set for the file.  The time
              is measured in the standard POSIX fashion  as  sec-
              onds  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 gen-
              erated.  On Windows, FAT file systems do  not  sup-
              port access time.

       file attributes name

       file attributes name ?option?

       file attributes name ?option value option value...?
              This  subcommand  returns or sets platform specific
              values associated  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, -group gets or sets the group name for the
              file.  A  group id can be given to the command, but
              it returns a group name. -owner gets  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. -permissions sets 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: u+s,go-rw add sticky bit for user, remove
              read and write permissions for group and other).  A
              simplified  ls  style string, of the form rwxrwxrwx
              (must be 9 characters), is also supported (example:
              rwxr-xr-t is equivalent to 01755).

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

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

       file channels ?pattern?
              If pattern isn't specified, returns a list of names
              of  all  registered  open  channels  in this inter-
              preter.  If pattern is specified, only those  names
              matching  pattern are returned.  Matching is deter-
              mined using the same rules as for string match.

       file copy ?-force? ?--? source target

       file copy ?-force? ?--? source ?source ...? targetDir
              The first form makes a copy of the file  or  direc-
              tory source under the pathname target. If target is
              an existing directory,  then  the  second  form  is
              used.   The second form makes a copy inside target-
              Dir of each source file listed.  If a directory  is
              specified  as  a  source,  then the contents of the
              directory will be recursively copied  into  target-
              Dir.  Existing files will not be overwritten unless
              the  -force  option  is  specified.   When  copying
              within  a  single  filesystem,  file copy 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 a file with a directory will all result in
              errors even if -force was specified.  Arguments are
              processed  in  the  order specified, halting at the
              first error,  if  any.   A  --  marks  the  end  of
              switches;  the  argument  following  the -- will be
              treated as a source even if it starts with a -.

       file delete ?-force? ?--? pathname ?pathname ... ?
              Removes the file or  directory  specified  by  each
              pathname  argument.   Non-empty directories will be
              removed only if the  -force  option  is  specified.
              When  operating  on symbolic links, the links them-
              selves 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
              -force flags  is  not  specified.   If  the  -force
              option  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,
              halting at the first error, if any.  A -- marks the
              end of switches; the argument following the -- will
              be treated as a pathname even if it starts  with  a
              -.

       file dirname name
              Returns  a name comprised of all of the path compo-
              nents in name excluding the last element.  If  name
              is  a relative file name and only contains one path
              element, then returns ``.'' (or ``:'' on the Macin-
              tosh).   If  name  refers to a root directory, then
              the root directory is returned.  For example,
                     file dirname c:/
              returns c:/.

              Note that tilde substitution will only be performed
              if  it  is  necessary  to complete the command. For
              example,
                     file dirname ~/src/foo.c
              returns ~/src, whereas
                     file dirname ~
              returns /home (or something similar).

       file executable name
              Returns 1 if file name is executable by the current
              user, 0 otherwise.

       file exists name
              Returns  1 if file name exists and the current user
              has search privileges for the  directories  leading
              to it, 0 otherwise.

       file extension name
              Returns  all  of  the  characters in name after and
              including the last dot in the last element of name.
              If there is no dot in the last element of name then
              returns the empty string.

       file isdirectory name
              Returns 1 if file name is a directory, 0 otherwise.

       file isfile name
              Returns  1 if file name is a regular file, 0 other-
              wise.

       file join name ?name ...?
              Takes one or more file  names  and  combines  them,
              using  the  correct  path separator for the current
              platform.  If a particular name is  relative,  then
              it  will  be joined to the previous file name argu-
              ment.  Otherwise, any  earlier  arguments  will  be
              discarded,  and  joining will proceed from the cur-
              rent argument.  For example,
                     file join a b /foo bar
              returns /foo/bar.

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

       file link ?-linktype? linkName ?target?
              If  only  one  argument  is given, that argument is
              assumed to be linkName, and  this  command  returns
              the  value  of the link given by linkName (i.e. the
              name of the file it points to).  If linkName  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  linkName  and  target. If linkName
              already exists, or  if  target  doesn't  exist,  an
              error  will  be returned.  Otherwise, Tcl creates a
              new link called linkName which points to the exist-
              ing  filesystem object at target, 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   -linktype   argument  should  be  given.
              Accepted values for -linktype 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 symbolic and hard links (the
              latter  for  files  only),  MacOS supports symbolic
              links and Windows NT/2000/XP (on NTFS drives)  sup-
              port  symbolic directory links and hard file links.

       file lstat name varName
              Same as stat option (see  below)  except  uses  the
              lstat kernel call instead of stat.  This means that
              if name refers to a symbolic link  the  information
              returned in varName is for the link rather than the
              file it refers to.  On systems that  don't  support
              symbolic links this option behaves exactly the same
              as the stat option.

       file mkdir dir ?dir ...?
              Creates each directory specified.  For  each  path-
              name  dir  specified,  this command will create all
              non-existing parent  directories  as  well  as  dir
              itself.   If  an  existing  directory is specified,
              then no action is taken and no error  is  returned.
              Trying  to overwrite an existing file with a direc-
              tory will result in an error.  Arguments  are  pro-
              cessed in the order specified, halting at the first
              error, if any.

       file mtime name ?time?
              Returns a decimal string giving the time  at  which
              file name was last modified.  If time is specified,
              it is a modification  time  to  set  for  the  file
              (equivalent  to  Unix touch).  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.

       file nativename name
              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 Win-
              dows or AppleScript on the Macintosh.

       file normalize name
              Returns a unique normalised 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 abso-
              lute 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 com-
              ponent  may  be a symbolic link), and on Windows it
              also means means we want the long  form  with  that
              form's  case-dependence  (which  gives us a unique,
              case-dependent path).  The one exception concerning
              the last link in the path is necessary, because Tcl
              or the user may wish to operate on the actual  sym-
              bolic link itself (for example 'file delete', 'file
              rename', 'file copy' are defined to operate on sym-
              bolic links, not on the things that they point to).

       file owned name
              Returns 1 if file name  is  owned  by  the  current
              user, 0 otherwise.

       file pathtype name
              Returns  one of absolute, relative, volumerelative.
              If name refers to a specific  file  on  a  specific
              volume,  the  path  type will be absolute.  If name
              refers to a file relative to  the  current  working
              directory, then the path type will be relative.  If
              name refers to a file relative to the current work-
              ing  directory  on a specified volume, or to a spe-
              cific file on the current working volume, then  the
              file type is volumerelative.

       file readable name
              Returns  1  if file name is readable by the current
              user, 0 otherwise.

       file readlink name
              Returns the value of the  symbolic  link  given  by
              name  (i.e. the name of the file it points to).  If
              name isn't a symbolic link or its value  cannot  be
              read,  then  an error is returned.  On systems that
              don't support symbolic links this option  is  unde-
              fined.

       file rename ?-force? ?--? source target

       file rename ?-force? ?--? source ?source ...? targetDir
              The  first  form takes the file or directory speci-
              fied by pathname source and renames it  to  target,
              moving  the file if the pathname target specifies a
              name in a different directory.   If  target  is  an
              existing  directory,  then the second form is used.
              The second form moves each source file or directory
              into  the  directory targetDir. Existing files will
              not be overwritten  unless  the  -force  option  is
              specified.  When operating inside a single filesys-
              tem, 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 spec-
              ified,  halting  at  the first error, if any.  A --
              marks the end of switches; the  argument  following
              the  --  will  be  treated  as  a source even if it
              starts with a -.

       file rootname name
              Returns all of the characters in name up to but not
              including the last ``.'' character in the last com-
              ponent of name.  If  the  last  component  of  name
              doesn't contain a dot, then returns name.

       file separator ?name?
              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 name, an error is generated.

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

       file split name
              Returns  a  list whose elements are the path compo-
              nents in name.  The first element of the list  will
              have  the  same  path type as name.  All other ele-
              ments 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  /  foo  ./~bar  baz  to  ensure that later
              commands  that  use  the  third  component  do  not
              attempt to perform tilde substitution.

       file stat  name varName
              Invokes  the stat kernel call on name, and uses the
              variable  given  by  varName  to  hold  information
              returned  from the kernel call.  VarName is treated
              as an array variable, and the following elements of
              that variable are set: atime, ctime, dev, gid, ino,
              mode, mtime, nlink, size, type, uid.  Each  element
              except  type  is a decimal string with the value of
              the corresponding field from the stat return struc-
              ture;  see the manual entry for stat for details on
              the meanings of the values.  The type element gives
              the  type  of the file in the same form returned by
              the command file type.   This  command  returns  an
              empty string.

       file system name
              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 arbitrary string representing the
              filesystem-specific nature or type of the  location
              within  that filesystem.  If a filesystem only sup-
              ports 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 generated.

       file tail name
              Returns  all  of  the  characters in name after the
              last directory separator.  If name contains no sep-
              arators then returns name.

       file type name
              Returns  a  string  giving  the  type of file name,
              which will be one of file, directory, characterSpe-
              cial, blockSpecial, fifo, link, or socket.

       file volumes
              Returns  the  absolute paths to the volumes mounted
              on the system, as a proper Tcl list.  On the Macin-
              tosh,  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:/}).

       file writable name
              Returns  1  if file name is writable by the current
              user, 0 otherwise.

PORTABILITY ISSUES
       Unix
              These commands always operate using the  real  user
              and group identifiers, not the effective ones.


SEE ALSO
       filename(n),  open(n), close(n), eof(n), gets(n), tell(n),
       seek(n), fblocked(n), flush(n)


KEYWORDS
       attributes, copy files,  delete  files,  directory,  file,
