<HTML><HEAD><TITLE>Tcl Built-In Commands - file manual page</TITLE></HEAD><BODY>
<DL>
<DD><A HREF="file.htm#M2" NAME="L255">NAME</A>
<DL><DD>file - Manipulate file names and attributes</DL>
<DD><A HREF="file.htm#M3" NAME="L256">SYNOPSIS</A>
<DL>
<DD><B>file </B><I>option</I> <I>name</I> ?<I>arg arg ...</I>?
</DL>
<DD><A HREF="file.htm#M4" NAME="L257">DESCRIPTION</A>
<DL>
<DD><A HREF="file.htm#M5" NAME="L258"><B>file atime </B><I>name</I></A>
<DD><A HREF="file.htm#M6" NAME="L259"><B>file attributes </B><I>name</I></A>
<DD><A HREF="file.htm#M7" NAME="L260"><B>file copy </B>?<B>-force</B>? ?<B>--</B>? <I>source</I> <I>target</I></A>
<DD><A HREF="file.htm#M8" NAME="L261"><B>file copy </B>?<B>-force</B>? ?<B>--</B>? <I>source</I> ?<I>source</I> ...? <I>targetDir</I></A>
<DD><A HREF="file.htm#M9" NAME="L262"><B>file delete </B>?<B>-force</B>? ?<B>--</B>? <I>pathname</I> ?<I>pathname</I> ... ?</A>
<DD><A HREF="file.htm#M10" NAME="L263"><B>file dirname </B><I>name</I></A>
<DD><A HREF="file.htm#M11" NAME="L264"><B>file executable </B><I>name</I></A>
<DD><A HREF="file.htm#M12" NAME="L265"><B>file exists </B><I>name</I></A>
<DD><A HREF="file.htm#M13" NAME="L266"><B>file extension </B><I>name</I></A>
<DD><A HREF="file.htm#M14" NAME="L267"><B>file isdirectory </B><I>name</I></A>
<DD><A HREF="file.htm#M15" NAME="L268"><B>file isfile </B><I>name</I></A>
<DD><A HREF="file.htm#M16" NAME="L269"><B>file join </B><I>name</I> ?<I>name ...</I>?</A>
<DD><A HREF="file.htm#M17" NAME="L270"><B>file lstat </B><I>name varName</I></A>
<DD><A HREF="file.htm#M18" NAME="L271"><B>file mkdir </B><I>dir</I> ?<I>dir</I> ...?</A>
<DD><A HREF="file.htm#M19" NAME="L272"><B>file mtime </B><I>name</I></A>
<DD><A HREF="file.htm#M20" NAME="L273"><B>file nativename </B><I>name</I></A>
<DD><A HREF="file.htm#M21" NAME="L274"><B>file owned </B><I>name</I></A>
<DD><A HREF="file.htm#M22" NAME="L275"><B>file pathtype </B><I>name</I></A>
<DD><A HREF="file.htm#M23" NAME="L276"><B>file readable </B><I>name</I></A>
<DD><A HREF="file.htm#M24" NAME="L277"><B>file readlink </B><I>name</I></A>
<DD><A HREF="file.htm#M25" NAME="L278"><B>file rename </B>?<B>-force</B>? ?<B>--</B>? <I>source</I> <I>target</I></A>
<DD><A HREF="file.htm#M26" NAME="L279"><B>file rename </B>?<B>-force</B>? ?<B>--</B>? <I>source</I> ?<I>source</I> ...? <I>targetDir</I></A>
<DD><A HREF="file.htm#M27" NAME="L280"><B>file rootname </B><I>name</I></A>
<DD><A HREF="file.htm#M28" NAME="L281"><B>file size </B><I>name</I></A>
<DD><A HREF="file.htm#M29" NAME="L282"><B>file split </B><I>name</I></A>
<DD><A HREF="file.htm#M30" NAME="L283"><B>file stat </B><I>name varName</I></A>
<DD><A HREF="file.htm#M31" NAME="L284"><B>file tail </B><I>name</I></A>
<DD><A HREF="file.htm#M32" NAME="L285"><B>file type </B><I>name</I></A>
<DD><A HREF="file.htm#M33" NAME="L286"><B>file volume</B></A>
<DD><A HREF="file.htm#M34" NAME="L287"><B>file writable </B><I>name</I></A>
</DL>
<DD><A HREF="file.htm#M35" NAME="L288">PORTABILITY ISSUES</A>
<DL>
<DD><A HREF="file.htm#M36" NAME="L289"><B>Unix</B></A>
</DL>
<DD><A HREF="file.htm#M37" NAME="L290">SEE ALSO</A>
<DD><A HREF="file.htm#M38" NAME="L291">KEYWORDS</A>
</DL><HR>
<H3><A NAME="M2">NAME</A></H3>
file - Manipulate file names and attributes
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>file </B><I>option</I> <I>name</I> ?<I>arg arg ...</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
This command provides several operations on a file's name or attributes.
<I>Name</I> 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
<B><A HREF="../TclCmd/filename.htm">filename</A></B> for details). <I>Option</I> indicates what to do with the
file name. Any unique abbreviation for <I>option</I> is acceptable. The
valid options are:
<P>
<DL>
<P><DT><A NAME="M5"><B>file atime </B><I>name</I></A><DD>
Returns a decimal string giving the time at which file <I>name</I>
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.
<P><DT><A NAME="M6"><B>file attributes </B><I>name</I></A><DD>
<BR>
<B>file attributes </B><I>name</I> ?<B><A HREF="../TkCmd/option.htm">option</A></B>?
<BR>
<B>file attributes </B><I>name</I> ?<B>option value option value...</B>?
<DL><P><DD>
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:
<P>
On Unix, <B>-group</B> gets or sets the group name for the file. A group id can
be given to the command, but it returns a group name. <B>-owner</B>
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. <B>-permissions</B> sets or retrieves the octal code
that chmod(1) uses. This command does not support the symbolic
attributes for chmod(1) at this time.
<P>
On Windows, <B>-archive</B> gives the value or sets or clears the
archive attribute of the file. <B>-hidden</B> gives the value or sets
or clears the hidden attribute of the file. <B>-longname</B> will
expand each path element to its long version. This attribute cannot be
set. <B>-readonly</B> gives the value or sets or clears the readonly
attribute of the file. <B>-shortname</B> gives a string where every
path element is replaced with its short (8.3) version of the
name. This attribute cannot be set. <B>-system</B> gives or sets or
clears the value of the system attribute of the file.
<P>
On Macintosh, <B>-creator</B> gives or sets the Finder creator type of
the file. <B>-hidden</B> gives or sets or clears the hidden attribute
of the file. <B>-readonly</B> gives or sets or clears the readonly
attribute of the file. Note that directories can only be locked if
File Sharing is turned on. <B>-type</B> gives or sets the Finder file
type for the file.
</DL>
<P><DT><A NAME="M7"><B>file copy </B>?<B>-force</B>? ?<B>--</B>? <I>source</I> <I>target</I></A>
<DT><A NAME="M8"><B>file copy </B>?<B>-force</B>? ?<B>--</B>? <I>source</I> ?<I>source</I> ...? <I>targetDir</I></A><DD>
The first form makes a copy of the file or directory <I>source</I> under
the pathname <I>target</I>. If <I>target</I> is an existing directory,
then the second form is used. The second form makes a copy inside
<I>targetDir</I> of each <I>source</I> file listed. If a directory is
specified as a <I>source</I>, then the contents of the directory will be
recursively copied into <I>targetDir</I>. Existing files will not be
overwritten unless the <B>-force</B> 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 <I>-force</I> was
specified. Arguments are processed in the order specified, halting at the
first error, if any. A <B>--</B> marks the end of switches; the argument
following the <B>--</B> will be treated as a <I>source</I> even if it
starts with a <B>-</B>.
<P><DT><A NAME="M9"><B>file delete </B>?<B>-force</B>? ?<B>--</B>? <I>pathname</I> ?<I>pathname</I> ... ?</A><DD>
Removes the file or directory specified by each <I>pathname</I> argument.
Non-empty directories will be removed only if the <B>-force</B> 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 <B>-force</B> flags is not specified. Arguments are processed
in the order specified, halting at the first error, if any. A <B>--</B>
marks the end of switches; the argument following the <B>--</B> will be
treated as a <I>pathname</I> even if it starts with a <B>-</B>.
<P><DT><A NAME="M10"><B>file dirname </B><I>name</I></A><DD>
Returns a name comprised of all of the path components in <I>name</I>
excluding the last element. If <I>name</I> is a relative file name and
only contains one path element, then returns ``<B>.</B>'' (or ``<B>:</B>''
on the Macintosh). If <I>name</I> refers to a root directory, then the
root directory is returned. For example,
<PRE><B>file dirname c:/</B></PRE>
returns <B>c:/</B>.
<P>
Note that tilde substitution will only be
performed if it is necessary to complete the command. For example,
<PRE><B>file dirname ~/src/foo.c</B></PRE>
returns <B>~/src</B>, whereas
<PRE><B>file dirname ~</B></PRE>
returns <B>/home</B> (or something similar).
<P><DT><A NAME="M11"><B>file executable </B><I>name</I></A><DD>
Returns <B>1</B> if file <I>name</I> is executable by the current user,
<B>0</B> otherwise.
<P><DT><A NAME="M12"><B>file exists </B><I>name</I></A><DD>
Returns <B>1</B> if file <I>name</I> exists and the current user has
search privileges for the directories leading to it, <B>0</B> otherwise.
<P><DT><A NAME="M13"><B>file extension </B><I>name</I></A><DD>
Returns all of the characters in <I>name</I> after and including the last
dot in the last element of <I>name</I>. If there is no dot in the last
element of <I>name</I> then returns the empty string.
<P><DT><A NAME="M14"><B>file isdirectory </B><I>name</I></A><DD>
Returns <B>1</B> if file <I>name</I> is a directory, <B>0</B> otherwise.
<P><DT><A NAME="M15"><B>file isfile </B><I>name</I></A><DD>
Returns <B>1</B> if file <I>name</I> is a regular file, <B>0</B> otherwise.
<P><DT><A NAME="M16"><B>file join </B><I>name</I> ?<I>name ...</I>?</A><DD>
Takes one or more file names and combines them, using the correct path
separator for the current platform. If a particular <I>name</I> 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,
<PRE><B>file join a b /foo bar</B></PRE>
returns <B>/foo/bar</B>.
<P>Note that any of the names can contain separators, and that the result
is always canonical for the current platform: <B>/</B> for Unix and
Windows, and <B>:</B> for Macintosh.
<P><DT><A NAME="M17"><B>file lstat </B><I>name varName</I></A><DD>
Same as <B>stat</B> option (see below) except uses the <I>lstat</I>
kernel call instead of <I>stat</I>. This means that if <I>name</I>
refers to a symbolic link the information returned in <I>varName</I>
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 <B>stat</B> option.
<P><DT><A NAME="M18"><B>file mkdir </B><I>dir</I> ?<I>dir</I> ...?</A><DD>
Creates each directory specified. For each pathname <I>dir</I> specified,
this command will create all non-existing parent directories as
well as <I>dir</I> 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.
<P><DT><A NAME="M19"><B>file mtime </B><I>name</I></A><DD>
Returns a decimal string giving the time at which file <I>name</I> 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.
<P><DT><A NAME="M20"><B>file nativename </B><I>name</I></A><DD>
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.
<P><DT><A NAME="M21"><B>file owned </B><I>name</I></A><DD>
Returns <B>1</B> if file <I>name</I> is owned by the current user, <B>0</B>
otherwise.
<P><DT><A NAME="M22"><B>file pathtype </B><I>name</I></A><DD>
Returns one of <B>absolute</B>, <B>relative</B>, <B>volumerelative</B>. If
<I>name</I> refers to a specific file on a specific volume, the path type
will be <B>absolute</B>. If <I>name</I> refers to a file relative to the
current working directory, then the path type will be <B>relative</B>. If
<I>name</I> 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 <B>volumerelative</B>.
<P><DT><A NAME="M23"><B>file readable </B><I>name</I></A><DD>
Returns <B>1</B> if file <I>name</I> is readable by the current user,
<B>0</B> otherwise.
<P><DT><A NAME="M24"><B>file readlink </B><I>name</I></A><DD>
Returns the value of the symbolic link given by <I>name</I> (i.e. the name
of the file it points to). If <I>name</I> 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.
<P><DT><A NAME="M25"><B>file rename </B>?<B>-force</B>? ?<B>--</B>? <I>source</I> <I>target</I></A>
<DT><A NAME="M26"><B>file rename </B>?<B>-force</B>? ?<B>--</B>? <I>source</I> ?<I>source</I> ...? <I>targetDir</I></A><DD>
The first form takes the file or directory specified by pathname
<I>source</I> and renames it to <I>target</I>, moving the file if the
pathname <I>target</I> specifies a name in a different directory. If
<I>target</I> is an existing directory, then the second form is used. The
second form moves each <I>source</I> file or directory into the directory
<I>targetDir</I>. Existing files will not be overwritten unless the
<B>-force</B> 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 <B>--</B> marks the end of
switches; the argument following the <B>--</B> will be treated as a
<I>source</I> even if it starts with a <B>-</B>.
<P><DT><A NAME="M27"><B>file rootname </B><I>name</I></A><DD>
Returns all of the characters in <I>name</I> up to but not including the
last ``.'' character in the last component of name. If the last
component of <I>name</I> doesn't contain a dot, then returns <I>name</I>.
<P><DT><A NAME="M28"><B>file size </B><I>name</I></A><DD>
Returns a decimal string giving the size of file <I>name</I> in bytes. If
the file doesn't exist or its size cannot be queried then an error is
generated.
<P><DT><A NAME="M29"><B>file split </B><I>name</I></A><DD>
Returns a list whose elements are the path components in <I>name</I>. The
first element of the list will have the same path type as <I>name</I>.
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
<PRE><B>file split /foo/~bar/baz</B></PRE>
returns <B>/ foo ./~bar baz</B> to ensure that later commands
that use the third component do not attempt to perform tilde
substitution.
<P><DT><A NAME="M30"><B>file stat </B><I>name varName</I></A><DD>
Invokes the <B>stat</B> kernel call on <I>name</I>, and uses the variable
given by <I>varName</I> to hold information returned from the kernel call.
<I>VarName</I> is treated as an array variable, and the following elements
of that variable are set: <B>atime</B>, <B>ctime</B>, <B>dev</B>, <B>gid</B>,
<B>ino</B>, <B>mode</B>, <B>mtime</B>, <B>nlink</B>, <B>size</B>, <B>type</B>,
<B>uid</B>. Each element except <B>type</B> is a decimal string with the
value of the corresponding field from the <B>stat</B> return structure;
see the manual entry for <B>stat</B> for details on the meanings of the
values. The <B>type</B> element gives the type of the file in the same
form returned by the command <B>file type</B>. This command returns an
empty string.
<P><DT><A NAME="M31"><B>file tail </B><I>name</I></A><DD>
Returns all of the characters in <I>name</I> after the last directory
separator. If <I>name</I> contains no separators then returns
<I>name</I>.
<P><DT><A NAME="M32"><B>file type </B><I>name</I></A><DD>
Returns a string giving the type of file <I>name</I>, which will be one of
<B>file</B>, <B>directory</B>, <B>characterSpecial</B>, <B>blockSpecial</B>,
<B>fifo</B>, <B>link</B>, or <B><A HREF="../TclCmd/socket.htm">socket</A></B>.
<P><DT><A NAME="M33"><B>file volume</B></A><DD>
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:/}).
<P><DT><A NAME="M34"><B>file writable </B><I>name</I></A><DD>
Returns <B>1</B> if file <I>name</I> is writable by the current user,
<B>0</B> otherwise.
<P></DL>
<H3><A NAME="M35">PORTABILITY ISSUES</A></H3>
<DL>
<P><DT><A NAME="M36"><B>Unix</B></A><DD>
These commands always operate using the real user and group identifiers,
not the effective ones.
<P></DL>
<H3><A NAME="M37">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/filename.htm">filename</A></B>
<H3><A NAME="M38">KEYWORDS</A></H3>
<A href="../Keywords/A.htm#attributes">attributes</A>, <A href="../Keywords/C.htm#copy files">copy files</A>, <A href="../Keywords/D.htm#delete files">delete files</A>, <A href="../Keywords/D.htm#directory">directory</A>, <A href="../Keywords/F.htm#file">file</A>, <A href="../Keywords/M.htm#move files">move files</A>, <A href="../Keywords/N.htm#name">name</A>, <A href="../Keywords/R.htm#rename files">rename files</A>, <A href="../Keywords/S.htm#stat">stat</A>
<HR><PRE>
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
</BODY></HTML>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
bd5c3d824c3db63ffd9226c15941e6ad
>
files
>
1958
