Mac Developer Library Developer
Search

 

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.



file(n)                                     Tcl Built-In Commands                                    file(n)



____________________________________________________________________________________________________________

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 man-ual manual
       ual  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 com-mand, command,
              mand, 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.  Match-ing Matching
              ing 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 tar-get target
              get 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  speci-fied, specified,
              fied,  halting  at the first error, if any.  A -- marks the end of switches; the argument fol-lowing following
              lowing 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-exis-tent non-existent
              tent  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 com-mand. command.
              mand. 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  cur-rent current
              rent  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  cre-ates creates
              ates  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 cre-ate create
              ate 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 sup-port support
              port  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 speci-fied, specified,
              fied, 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  sym-bolic symbolic
              bolic  link),  and on Windows it also means we want the long form with that form's case-depen-dence case-dependence
              dence (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 sym-bolic symbolic
              bolic 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 spe-cific specific
              cific 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 npt 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 tar-get, target,
              get, 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 nonempty
              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  gen-erated. generated.
              erated.

       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 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  informa-tion information
              tion  returned from the kernel call.  VarName is treated as an array variable, and the follow-ing following
              ing 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  mean-ings meanings
              ings  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-spe-cific filesystem-specific
              cific 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  direc-tory directory
              tory  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,  charac-terSpecial, characterSpecial,
              terSpecial, blockSpecial, fifo, link, or socket.

       file volumes
              Returns  the absolute paths to the volumes mounted on the system, as a proper Tcl list.  With-out Without
              out 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(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n), fblocked(n), flush(n)

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



Tcl                                                  8.3                                             file(n)

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation to the Tcl project.
Bug reports
Report bugs in the functionality of the described tool or API to Apple through Bug Reporter and to the Tcl project through their bug reporting page.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback