file(3tcl)


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 does not 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
          versions  of  Unix  supporting  file  flags, -readonly gives the
          value or sets or clears the readonly attribute of the file, i.e.
          the user immutable flag uchg to chflags(1).

          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  Mac  OS  X  and  Darwin,  -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. -rsrclength gives the length
          of the resource fork of the file, this attribute can only be set
          to the value  0,  which  results  in  the  resource  fork  being
          stripped off the file.

   file channels ?pattern?
          If  pattern  is  not  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 (when Tcl will
          also  attempt  to  adjust permissions on the destination file or
          directory if that is necessary to allow the  copy  to  proceed).
          When  copying  within  a  single filesystem, file copy will copy
          soft links (i.e.  the  links  themselves  are  copied,  not  the
          things   they  point  to).   Trying  to  overwrite  a  non-empty
          directory, overwrite a directory with a  file,  or  overwrite  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.  When operating on symbolic links,
          the links themselves will be deleted, not the objects they point
          to.   Trying  to delete a non-existent 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.  If the
          -force option is specified on a directory, Tcl will attempt both
          to  change  permissions and move the current directory "pwd" out
          of the given path if that is necessary to allow the deletion  to
          proceed.   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  ".".   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.

   file link ?-linktype? linkName ?target?
          If only one argument is given, that argument is  assumed  to  be
          linkName,  and  this command returns the value of the link given
          by linkName (i.e. the name  of  the  file  it  points  to).   If
          linkName  is  not  a  link  or its value cannot be read (as, for
          example, seems to be the case with hard links, which  look  just
          like ordinary files), then an error is returned.

          If  2 arguments are given, then these are assumed to be linkName
          and target. If linkName already exists, or if  target  does  not
          exist,  an error will be returned.  Otherwise, Tcl creates a new
          link called linkName which points  to  the  existing  filesystem
          object  at  target (which is also the returned value), where the
          type of the link is platform-specific (on Unix a  symbolic  link
          will  be  the  default).   This is useful for the case where the
          user wishes to create a link in a cross-platform way,  and  does
          not care what type of link is created.

          If  the user wishes to make a link of a specific type only, (and
          signal an error if for some reason that is not  possible),  then
          the  optional  -linktype  argument  should  be  given.  Accepted
          values for -linktype are "-symbolic" and "-hard".

          On Unix, symbolic links can be made to relative paths, and those
          paths must be relative to the actual linkName's location (not to
          the cwd), but on all other platforms where  relative  links  are
          not   supported,  target  paths  will  always  be  converted  to
          absolute, normalized  form  before  the  link  is  created  (and
          therefore  relative  paths  are  interpreted  as relative to the
          cwd).   Furthermore,  "~user"  paths  are  always  expanded   to
          absolute  form.   When creating links on filesystems that either
          do not support any links, or do not support  the  specific  type
          requested,  an  error  message  will be returned.  In particular
          Windows 95, 98 and ME do not support any links at  present,  but
          most  Unix  platforms  support both symbolic and hard links (the
          latter for files only) and Windows NT/2000/XP (on  NTFS  drives)
          support symbolic directory links and hard file links.

   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 do  not
          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  does  not
          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 to a subprocess via exec  under  Windows  (see  EXAMPLES
          below).

   file normalize name
          Returns  a  unique  normalized path representation for the file-
          system object (file, directory, link, etc), whose  string  value
          can be used as a unique identifier for it.  A normalized path is
          an absolute path which has all "../" and "./" removed.  Also  it
          is  one  which  is  in  the  "standard"  format  for  the native
          platform.  On Unix, this means the segments leading  up  to  the
          path  must  be free of symbolic links/aliases (but the very last
          path component may be a symbolic link), and on Windows  it  also
          means  we  want  the  long form with that form's case-dependence
          (which  gives  us  a  unique,  case-dependent  path).   The  one
          exception  concerning  the  last  link in the path is necessary,
          because Tcl or the user  may  wish  to  operate  on  the  actual
          symbolic link itself (for example file delete, file rename, file
          copy are defined to operate on symbolic links, not on the things
          that they point to).

   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 path 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 is not a symbolic  link
          or  its  value  cannot  be  read, then an error is returned.  On
          systems that do  not  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.   When  operating inside a single
          filesystem, Tcl will  rename  symbolic  links  rather  than  the
          things  that  they  point  to.   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 does not  contain  a  dot,  then  returns
          name.

   file separator ?name?
          If  no argument is given, returns the character which is used to
          separate path segments for native files on this platform.  If  a
          path is given, the filesystem responsible for that path is asked
          to return its separator character.  If no  file  system  accepts
          name, an error is generated.

   file size name
          Returns  a decimal string giving the size of file name in bytes.
          If the file does not 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  to  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 system name
          Returns a list of one or two elements, the first of which is the
          name of the filesystem to use for the file, and the  second,  if
          given,  an arbitrary string representing the filesystem-specific
          nature or type of the location within  that  filesystem.   If  a
          filesystem  only  supports  one type of file, the second element
          may not be supplied.  For example the native files have a  first
          element  "native",  and  a  second element which when given is a
          platform-specific type name for the file's system (e.g.  "NTFS",
          "FAT",  on Windows).  A generic virtual file system might return
          the list "vfs ftp" to represent a file  on  a  remote  ftp  site
          mounted  as  a  virtual  filesystem  through an extension called
          "vfs".  If the file does not belong to any filesystem, an  error
          is generated.

   file tail name
          Returns  all  of the characters in the last filesystem component
          of name.  Any trailing directory separator in name  is  ignored.
          If name contains no separators then returns name.  So, file tail
          a/b, file tail a/b/ and file tail b all return b.

   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 volumes
          Returns the absolute paths to the volumes mounted on the system,
          as  a  proper Tcl list.  Without any virtual filesystems mounted
          as root volumes, 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:/").
          If  any  virtual filesystem has mounted additional volumes, they
          will be in the returned list.

   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.

EXAMPLES

   This procedure shows how to search for C files  in  a  given  directory
   that have a correspondingly-named object file in the current directory:
          proc findMatchingCFiles {dir} {
             set files {}
             switch $::tcl_platform(platform) {
                windows {
                   set ext .obj
                }
                unix {
                   set ext .o
                }
             }
             foreach file [glob -nocomplain -directory $dir *.c] {
                set objectFile [file tail [file rootname $file]]$ext
                if {[file exists $objectFile]} {
                   lappend files $file
                }
             }
             return $files
          }

   Rename  a file and leave a symbolic link pointing from the old location
   to the new place:
          set oldName foobar.txt
          set newName foo/bar.txt
          # Make sure that where we're going to move to exists...
          if {![file isdirectory [file dirname $newName]]} {
             file mkdir [file dirname $newName]
          }
          file rename $oldName $newName
          file link -symbolic $oldName $newName

   On Windows, a file  can  be  "started"  easily  enough  (equivalent  to
   double-clicking on it in the Explorer interface) but the name passed to
   the operating system must be in native format:
          exec {*}[auto_execok start] {} [file nativename ~/example.txt]

SEE ALSO

   filename(3tcl),   open(3tcl),   close(3tcl),   eof(3tcl),   gets(3tcl),
   tell(3tcl), seek(3tcl), fblocked(3tcl), flush(3tcl)

KEYWORDS

   attributes,  copy  files,  delete  files,  directory, file, move files,
   name, rename files, stat





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.