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 ...? target-
              Dir
              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.   Trying  to  over-
              write  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.
              Trying to delete a non-existant file is not consid-
              ered an error.  Trying to delete a  read-only  file
              will  cause  the  file  to  be deleted, even if the
              -force flags is not specified.  Arguments are  pro-
              cessed 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
              current 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 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 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.   Trying to overwrite a non-empty direc-
              tory, overwrite a directory with a file, or a  file
              with  a directory will all result in errors.  Argu-
              ments 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 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 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 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 volume
              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


KEYWORDS
       attributes,  copy  files,  delete  files, directory, file,
       move files, name, rename files, stat
