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
              Returns  a  decimal string giving the time at which
              file name was last accessed.  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 then an error is generated.

       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  not  support the symbolic attributes
              for chmod(1) at this time.

              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 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.  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 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 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
              Returns  a  decimal string giving the time at which
              file name was last modified.  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 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
