file(n) Tcl (7.6) 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 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 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 not support |
the symbolic attributes for chmod(1) at this time. |
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 |
Page 1 (printed 2/19/99)
file(n) Tcl (7.6) file(n)
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 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. 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
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. 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
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
Page 2 (printed 2/19/99)
file(n) Tcl (7.6) file(n)
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 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
Page 3 (printed 2/19/99)
file(n) Tcl (7.6) file(n)
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 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 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
Page 4 (printed 2/19/99)
file(n) Tcl (7.6) file(n)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.
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 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
Page 5 (printed 2/19/99)
file(n) Tcl (7.6) file(n)
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 volume
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.
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
Page 6 (printed 2/19/99)
