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