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 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.  Under UNIX  this  command  uses
              the real user and group identifiers, not the effec-
              tive ones.

       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 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 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.   Under UNIX this command uses
              the real user and group identifiers, not the effec-
              tive ones.

       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 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
              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 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 writable name
              Returns 1 if file name is writable by  the  current
              user,  0  otherwise.   Under UNIX this command uses
              the real user and group identifiers, not the effec-
              tive ones.


SEE ALSO
       filename


KEYWORDS
       attributes, directory, file, name, stat
