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
       executing 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
              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.

       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.
              -shortname  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
              interpreter.   If  pattern is specified, only those
              names matching pattern are returned.   Matching  is
              determined  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
              directory source under  the  pathname  target.   If
              target  is  an  existing directory, then the second
              form is used.  The second form makes a copy  inside
              targetDir   of  each  source  file  listed.   If  a
              directory  is  specified  as  a  source,  then  the
              contents  of  the  directory  will  be  recursively
              copied into targetDir.  Existing files will not  be
              overwritten  unless the -force option is specified.
              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.
              Trying  to  delete  a  non-existant  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.   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
              components in name excluding the last element.   If
              name  is a relative file name and only contains one
              path element, then returns ``.'' (or ``:''  on  the
              Macintosh).   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
              otherwise.

       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
              argument.  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
              pathname 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
              directory  will  result in an error.  Arguments are
              processed 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
              Windows 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
              working directory on a specified volume,  or  to  a
              specific  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
              undefined.

       file rename ?-force? ?--? source target
       file rename ?-force? ?--? source ?source ...? targetDir
              The  first  form  takes  the  file   or   directory
              specified  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  directory,  overwrite a directory with a
              file, or a file with a directory will all result in
              errors.   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 rootname name
              Returns all of the characters in name up to but not
              including the last  ``.''  character  in  the  last
              component  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
              components in name.  The first element of the  list
              will  have  the  same path type as name.  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  /  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
              structure;  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
              separators then returns name.

       file type name
              Returns  a  string  giving  the  type of file name,
              which   will   be   one   of    file,    directory,
              characterSpecial,   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
              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:/}).

       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,
