tcl7.6 User Commands - file






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
          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  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 speci-
          fied.   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 speci-
          fied, 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  path-
          name  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 speci-
          fied,  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 rela-
          tive 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 includ-
          ing 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
          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 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  dif-
          ferent  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 tar-
          getDir.  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 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  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  com-
          mands  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 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