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