308 lines
19 KiB
HTML
308 lines
19 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - file manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="file.htm#M2" NAME="L314">NAME</A>
|
|
<DL><DD>file - Manipulate file names and attributes</DL>
|
|
<DD><A HREF="file.htm#M3" NAME="L315">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="L316">DESCRIPTION</A>
|
|
<DL>
|
|
<DD><A HREF="file.htm#M5" NAME="L317"><B>file atime </B><I>name</I> ?<B>time</B>?</A>
|
|
<DD><A HREF="file.htm#M6" NAME="L318"><B>file attributes </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M7" NAME="L319"><B>file channels ?</B><I>pattern</I>?</A>
|
|
<DD><A HREF="file.htm#M8" NAME="L320"><B>file copy </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> <I>target</I></A>
|
|
<DD><A HREF="file.htm#M9" NAME="L321"><B>file delete </B>?<B>-force</B>? ?<B>- -</B>? <I>pathname</I> ?<I>pathname</I> ... ?</A>
|
|
<DD><A HREF="file.htm#M10" NAME="L322"><B>file dirname </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M11" NAME="L323"><B>file executable </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M12" NAME="L324"><B>file exists </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M13" NAME="L325"><B>file extension </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M14" NAME="L326"><B>file isdirectory </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M15" NAME="L327"><B>file isfile </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M16" NAME="L328"><B>file join </B><I>name</I> ?<I>name ...</I>?</A>
|
|
<DD><A HREF="file.htm#M17" NAME="L329"><B>file lstat </B><I>name varName</I></A>
|
|
<DD><A HREF="file.htm#M18" NAME="L330"><B>file mkdir </B><I>dir</I> ?<I>dir</I> ...?</A>
|
|
<DD><A HREF="file.htm#M19" NAME="L331"><B>file mtime </B><I>name</I> ?<I>time</I>?</A>
|
|
<DD><A HREF="file.htm#M20" NAME="L332"><B>file nativename </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M21" NAME="L333"><B>file owned </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M22" NAME="L334"><B>file pathtype </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M23" NAME="L335"><B>file readable </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M24" NAME="L336"><B>file readlink </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M25" NAME="L337"><B>file rename </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> <I>target</I></A>
|
|
<DD><A HREF="file.htm#M26" NAME="L338"><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="L339"><B>file rootname </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M28" NAME="L340"><B>file size </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M29" NAME="L341"><B>file split </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M30" NAME="L342"><B>file stat </B><I>name varName</I></A>
|
|
<DD><A HREF="file.htm#M31" NAME="L343"><B>file tail </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M32" NAME="L344"><B>file type </B><I>name</I></A>
|
|
<DD><A HREF="file.htm#M33" NAME="L345"><B>file volume</B></A>
|
|
<DD><A HREF="file.htm#M34" NAME="L346"><B>file writable </B><I>name</I></A>
|
|
</DL>
|
|
<DD><A HREF="file.htm#M35" NAME="L347">PORTABILITY ISSUES</A>
|
|
<DL>
|
|
<DD><A HREF="file.htm#M36" NAME="L348"><B>Unix</B></A>
|
|
</DL>
|
|
<DD><A HREF="file.htm#M37" NAME="L349">SEE ALSO</A>
|
|
<DD><A HREF="file.htm#M38" NAME="L350">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="../TkCmd/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> ?<B>time</B>?</A><DD>
|
|
Returns a decimal string giving the time at which file <I>name</I> was last
|
|
accessed. If <I>time</I> 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.
|
|
<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="../TclCmd/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 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:
|
|
<B>u+s,go-rw</B> add sticky bit for user, remove read and write
|
|
permissions for group and other). A simplified <B>ls</B> style string,
|
|
of the form rwxrwxrwx (must be 9 characters), is also supported
|
|
(example: <B>rwxr-xr-t</B> is equivalent to 01755).
|
|
<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 channels ?</B><I>pattern</I>?</A><DD>
|
|
If <I>pattern</I> isn't specified, returns a list of names of all
|
|
registered open channels in this interpreter. If <I>pattern</I> is
|
|
specified, only those names matching <I>pattern</I> are returned. Matching
|
|
is determined using the same rules as for <B><A HREF="../TkCmd/string.htm">string match</A></B>.
|
|
<P><DT><A NAME="M8"><B>file copy </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> <I>target</I></A><DD>
|
|
<BR>
|
|
<B>file copy </B>?<B>-force</B>? ?<B>- -</B>? <I>source</I> ?<I>source</I> ...? <I>targetDir</I>
|
|
<DL><P><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>.
|
|
</DL>
|
|
<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> ?<I>time</I>?</A><DD>
|
|
Returns a decimal string giving the time at which file <I>name</I> was last
|
|
modified. If <I>time</I> is specified, it is a modification time to set for
|
|
the file (equivalent to Unix <B>touch</B>). 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.
|
|
<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="../TkCmd/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="../TkCmd/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>
|