file(n) manual page
Table of Contents
file - Manipulate file names and attributes
file option name ?arg arg ...?
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 doesn’t 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 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
Macintosh, -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. Note that directories
can only be locked if File Sharing is turned on. -type gives or sets the
Finder file type for the file.
- file channels ?pattern?
- If pattern isn’t
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 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
‘‘.’’ (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 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, and : for Macintosh.
- 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 isn’t 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 doesn’t exist, an error will be returned. Otherwise,
Tcl creates a new link called linkName which points to the existing filesystem
object at target, 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 doesn’t 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". 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), MacOS
supports symbolic links 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 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 ?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 doesn’t 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 exec under Windows or
AppleScript on the Macintosh.
- 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 ’../’, ’./’ removed. Also it is one which
is in the ‘‘standard’’ format for the native platform. On MacOS, 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 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 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 doesn’t 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 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 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 two elements,
the first of which is the name of the filesystem to use for the file, and
the second 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 be null. For example the native
files have a first element ’native’, and a second element which is a platform-specific
type name for the file’s system (e.g. ’NTFS’, ’FAT’, etc), or possibly the empty
string if no further information is available or if this is not implemented.
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 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 volumes
- Returns the absolute paths to the volumes
mounted on the system, as a proper Tcl list. On the Macintosh, this will
be a list of the mounted drives, both local and network. N.B. if two drives
have the same name, they will both appear on the volume list, but there
is currently no way, from Tcl, to access any but the first of these drives.
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:/}).
- file writable name
- Returns 1 if file name is writable
by the current user, 0 otherwise.
- Unix
- These commands
always operate using the real user and group identifiers, not the effective
ones.
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
filename(n)
, open(n)
, close(n)
, eof(n)
, gets(n)
, tell(n)
, seek(n)
,
fblocked(n)
, flush(n)
attributes, copy files, delete files, directory,
file, move files, name, rename files, stat
Table of Contents
![[Go to CFHT Home Page]](/images/cfht-icon.gif){kind=icon}
Man Pages 
Back to Software Index 
Manpage Top Level