restore line endings

1 files changed, 475 insertions, 475 deletions

diff --git a/doc/file.n b/doc/file.n
index 8584468..d26d9f4 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -1,475 +1,475 @@
-'\"

-'\" Copyright (c) 1993 The Regents of the University of California.

-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.

-'\"

-'\" See the file "license.terms" for information on usage and redistribution

-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.

-'\" 

-'\" RCS: @(#) $Id: file.n,v 1.41 2006/12/02 16:14:30 dkf Exp $

-'\" 

-.so man.macros

-.TH file n 8.3 Tcl "Tcl Built-In Commands"

-.BS

-'\" Note:  do not modify the .SH NAME line immediately below!

-.SH NAME

-file \- Manipulate file names and attributes

-.SH SYNOPSIS

-\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?

-.BE

-

-.SH DESCRIPTION

-.PP

-This command provides several operations on a file's name or attributes.

-\fIName\fR 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

-\fBfilename\fR for details).  \fIOption\fR indicates what to do with the

-file name.  Any unique abbreviation for \fIoption\fR is acceptable.  The

-valid options are:

-.TP

-\fBfile atime \fIname\fR ?\fBtime\fR?

-.

-Returns a decimal string giving the time at which file \fIname\fR was last

-accessed.  If \fItime\fR 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.

-.TP

-\fBfile attributes \fIname\fR

-.TP

-\fBfile attributes \fIname\fR ?\fBoption\fR?

-.TP

-\fBfile attributes \fIname\fR ?\fBoption value option value...\fR?

-.RS

-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:

-.PP

-On Unix, \fB-group\fR gets or sets the group name for the file. A group id

-can be given to the command, but it returns a group name. \fB-owner\fR 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. \fB-permissions\fR 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:

-\fBu+s,go\-rw\fR add sticky bit for user, remove read and write

-permissions for group and other).  A simplified \fBls\fR style string,

-of the form rwxrwxrwx (must be 9 characters), is also supported

-(example: \fBrwxr\-xr\-t\fR is equivalent to 01755).

-On versions of Unix supporting file flags, \fB-readonly\fR gives the

-value or sets or clears the readonly attribute of the file,

-i.e. the user immutable flag \fBuchg\fR to chflags(1).

-.PP

-On Windows, \fB-archive\fR gives the value or sets or clears the

-archive attribute of the file. \fB-hidden\fR gives the value or sets

-or clears the hidden attribute of the file. \fB-longname\fR will

-expand each path element to its long version. This attribute cannot be

-set. \fB-readonly\fR gives the value or sets or clears the readonly

-attribute of the file. \fB-shortname\fR gives a string where every

-path element is replaced with its short (8.3) version of the

-name. This attribute cannot be set. \fB-system\fR gives or sets or

-clears the value of the system attribute of the file.

-.PP

-On Mac OS X and Darwin, \fB-creator\fR gives or sets the

-Finder creator type of the file. \fB-hidden\fR gives or sets or clears

-the hidden attribute of the file. \fB-readonly\fR gives or sets or

-clears the readonly attribute of the file. \fB-rsrclength\fR gives

-the length of the resource fork of the file, this attribute can only be

-set to the value 0, which results in the resource fork being stripped

-off the file.

-.RE

-.TP

-\fBfile channels ?\fIpattern\fR?

-.

-If \fIpattern\fR isn't specified, returns a list of names of all

-registered open channels in this interpreter.  If \fIpattern\fR is

-specified, only those names matching \fIpattern\fR are returned.  Matching

-is determined using the same rules as for \fBstring match\fR.

-.TP

-\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR

-.TP

-\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR

-.RS

-The first form makes a copy of the file or directory \fIsource\fR under

-the pathname \fItarget\fR. If \fItarget\fR is an existing directory,

-then the second form is used.  The second form makes a copy inside

-\fItargetDir\fR of each \fIsource\fR file listed.  If a directory is

-specified as a \fIsource\fR, then the contents of the directory will be

-recursively copied into \fItargetDir\fR. Existing files will not be

-overwritten unless the \fB\-force\fR option is specified (when Tcl will

-also attempt to adjust permissions on the destination file or directory

-if that is necessary to allow the copy to proceed).  When copying

-within a single filesystem, \fIfile copy\fR 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

-\fI\-force\fR was specified.  Arguments are processed in the order

-specified, halting at the first error, if any.  A \fB\-\|\-\fR marks

-the end of switches; the argument following the \fB\-\|\-\fR will be

-treated as a \fIsource\fR even if it starts with a \fB\-\fR.

-.RE

-.TP

-\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ?

-.

-Removes the file or directory specified by each \fIpathname\fR

-argument.  Non-empty directories will be removed only if the

-\fB\-force\fR 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 \fB\-force\fR flags is not specified.  If the \fB\-force\fR

-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 \fB\-\|\-\fR marks the end of switches; the argument following the

-\fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with

-a \fB\-\fR.

-.TP

-\fBfile dirname \fIname\fR

-Returns a name comprised of all of the path components in \fIname\fR

-excluding the last element.  If \fIname\fR is a relative file name and

-only contains one path element, then returns ``\fB.\fR''.  If \fIname\fR

-refers to a root directory, then the root directory is returned.  For

-example,

-.RS

-.CS

-\fBfile dirname c:/\fR

-.CE

-returns \fBc:/\fR. 

-.PP

-Note that tilde substitution will only be

-performed if it is necessary to complete the command. For example,

-.CS

-\fBfile dirname ~/src/foo.c\fR

-.CE

-returns \fB~/src\fR, whereas

-.CS

-\fBfile dirname ~\fR

-.CE

-returns \fB/home\fR (or something similar).

-.RE

-.TP

-\fBfile executable \fIname\fR

-.

-Returns \fB1\fR if file \fIname\fR is executable by the current user,

-\fB0\fR otherwise.  

-.TP

-\fBfile exists \fIname\fR

-.

-Returns \fB1\fR if file \fIname\fR exists and the current user has

-search privileges for the directories leading to it, \fB0\fR otherwise.

-.TP

-\fBfile extension \fIname\fR

-.

-Returns all of the characters in \fIname\fR after and including the last

-dot in the last element of \fIname\fR.  If there is no dot in the last

-element of \fIname\fR then returns the empty string.

-.TP

-\fBfile isdirectory \fIname\fR

-.

-Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise.

-.TP

-\fBfile isfile \fIname\fR

-.

-Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise.

-.TP

-\fBfile join \fIname\fR ?\fIname ...\fR?

-.

-Takes one or more file names and combines them, using the correct path

-separator for the current platform.  If a particular \fIname\fR 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,

-.RS

-.CS

-\fBfile join a b /foo bar\fR

-.CE

-returns \fB/foo/bar\fR.

-.PP

-Note that any of the names can contain separators, and that the result

-is always canonical for the current platform: \fB/\fR for Unix and

-Windows.

-.RE

-.TP

-\fBfile link ?\fI-linktype\fR? \fIlinkName\fR ?\fItarget\fR?

-.

-If only one argument is given, that argument is assumed to be

-\fIlinkName\fR, and this command returns the value of the link given by

-\fIlinkName\fR (i.e. the name of the file it points to).  If

-\fIlinkName\fR 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 \fIlinkName\fR

-and \fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR

-doesn't exist, an error will be returned.  Otherwise, Tcl creates a new

-link called \fIlinkName\fR which points to the existing filesystem

-object at \fItarget\fR (which is also the returned value), 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

-\fI-linktype\fR argument should be given.  Accepted values for

-\fI-linktype\fR are "-symbolic" and "-hard".

-.

-On Unix, symbolic links can be made to relative paths, and those paths

-must be relative to the actual \fIlinkName\fR's location (not to the

-cwd), but on all other platforms where relative links are not supported,

-target paths will always be converted to absolute, normalized form

-before the link is created (and therefore relative paths are interpreted

-as relative to the cwd).  Furthermore, "~user" paths are always expanded

-to absolute form.  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) and Windows

-NT/2000/XP (on NTFS drives) support symbolic

-directory links and hard file links.

-.TP

-\fBfile lstat \fIname varName\fR

-.

-Same as \fBstat\fR option (see below) except uses the \fIlstat\fR

-kernel call instead of \fIstat\fR.  This means that if \fIname\fR

-refers to a symbolic link the information returned in \fIvarName\fR

-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 \fBstat\fR option.

-.TP

-\fBfile mkdir \fIdir\fR ?\fIdir\fR ...?

-.

-Creates each directory specified.  For each pathname \fIdir\fR specified,

-this command will create all non-existing parent directories as

-well as \fIdir\fR 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.

-.TP

-\fBfile mtime \fIname\fR ?\fItime\fR?

-.

-Returns a decimal string giving the time at which file \fIname\fR was last

-modified.  If \fItime\fR is specified, it is a modification time to set for

-the file (equivalent to Unix \fBtouch\fR).  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.

-.TP

-\fBfile nativename \fIname\fR

-.

-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.

-.TP

-\fBfile normalize \fIname\fR

-.

-.RS

-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 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).

-.RE

-.TP

-\fBfile owned \fIname\fR 

-.

-Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR

-otherwise.

-.TP

-\fBfile pathtype \fIname\fR

-.

-Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If

-\fIname\fR refers to a specific file on a specific volume, the path type will

-be \fBabsolute\fR. If \fIname\fR refers to a file relative to the current

-working directory, then the path type will be \fBrelative\fR. If \fIname\fR

-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 path

-type is \fBvolumerelative\fR.

-.TP

-\fBfile readable \fIname\fR

-.

-Returns \fB1\fR if file \fIname\fR is readable by the current user,

-\fB0\fR otherwise. 

-.TP

-\fBfile readlink \fIname\fR

-.

-Returns the value of the symbolic link given by \fIname\fR (i.e. the name

-of the file it points to).  If \fIname\fR 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.

-.TP

-\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR

-.TP

-\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR

-.RS

-The first form takes the file or directory specified by pathname

-\fIsource\fR and renames it to \fItarget\fR, moving the file if the

-pathname \fItarget\fR specifies a name in a different directory.  If

-\fItarget\fR is an existing directory, then the second form is used.

-The second form moves each \fIsource\fR file or directory into the

-directory \fItargetDir\fR. Existing files will not be overwritten

-unless the \fB\-force\fR 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 \fB\-\|\-\fR marks the end of

-switches; the argument following the \fB\-\|\-\fR will be treated as a

-\fIsource\fR even if it starts with a \fB\-\fR.

-.RE

-.TP

-\fBfile rootname \fIname\fR

-.

-Returns all of the characters in \fIname\fR up to but not including the

-last ``.'' character in the last component of name.  If the last

-component of \fIname\fR doesn't contain a dot, then returns \fIname\fR.

-.TP

-\fBfile separator\fR ?\fIname\fR?

-.

-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 \fIname\fR, an error

-is generated.

-.TP

-\fBfile size \fIname\fR

-.

-Returns a decimal string giving the size of file \fIname\fR in bytes.  If

-the file doesn't exist or its size cannot be queried then an error is

-generated.

-.TP

-\fBfile split \fIname\fR

-.

-Returns a list whose elements are the path components in \fIname\fR.  The

-first element of the list will have the same path type as \fIname\fR.

-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

-.RS

-.CS

-file split /foo/~bar/baz

-.CE

-returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands

-that use the third component do not attempt to perform tilde

-substitution.

-.RE

-.TP

-\fBfile stat  \fIname varName\fR

-.

-Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable

-given by \fIvarName\fR to hold information returned from the kernel call.

-\fIVarName\fR is treated as an array variable, and the following elements

-of that variable are set: \fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR,

-\fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR,

-\fBuid\fR.  Each element except \fBtype\fR is a decimal string with the

-value of the corresponding field from the \fBstat\fR return structure;

-see the manual entry for \fBstat\fR for details on the meanings of the

-values.  The \fBtype\fR element gives the type of the file in the same

-form returned by the command \fBfile type\fR.  This command returns an

-empty string.

-.TP

-\fBfile system \fIname\fR

-.

-Returns a list of one or two elements, the first of which is the name of

-the filesystem to use for the file, and the second, if given, 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 not be supplied.  For example the

-native files have a first element 'native', and a second element which

-when given is a platform-specific type name for the file's system

-(e.g. 'NTFS', 'FAT', on Windows).  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.

-.TP

-\fBfile tail \fIname\fR

-.

-Returns all of the characters in the last filesystem component of

-\fIname\fR.  Any trailing directory separator in \fIname\fR is ignored.

-If \fIname\fR contains no separators then returns \fIname\fR.  So, 

-\fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all

-return \fBb\fR.

-.TP

-\fBfile type \fIname\fR

-.

-Returns a string giving the type of file \fIname\fR, which will be one of

-\fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR,

-\fBfifo\fR, \fBlink\fR, or \fBsocket\fR.

-.TP

-\fBfile volumes\fR

-. 

-Returns the absolute paths to the volumes mounted on the system, as a

-proper Tcl list.  Without any virtual filesystems mounted as root

-volumes, 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:/}).  If any virtual filesystem has mounted additional

-volumes, they will be in the returned list.

-.TP

-\fBfile writable \fIname\fR

-.

-Returns \fB1\fR if file \fIname\fR is writable by the current user,

-\fB0\fR otherwise.

-.SH "PORTABILITY ISSUES"

-.TP

-\fBUnix\fR\0\0\0\0\0\0\0

-.

-These commands always operate using the real user and group identifiers,

-not the effective ones. 

-.SH EXAMPLES

-This procedure shows how to search for C files in a given directory

-that have a correspondingly-named object file in the current

-directory:

-.CS

-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 [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext

-      if {[\fBfile exists\fR $objectFile]} {

-         lappend files $file

-      }

-   }

-   return $files

-}

-.CE

-.PP

-Rename a file and leave a symbolic link pointing from the old location

-to the new place:

-.CS

-set oldName foobar.txt

-set newName foo/bar.txt

-# Make sure that where we're going to move to exists...

-if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} {

-   \fBfile mkdir\fR [\fBfile dirname\fR $newName]

-}

-\fBfile rename\fR $oldName $newName

-\fBfile link\fR -symbolic $oldName $newName

-.CE

-

-.SH "SEE ALSO"

-filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),

-fblocked(n), flush(n)

-

-.SH KEYWORDS

-attributes, copy files, delete files, directory, file, move files, name, rename files, stat

+'\"
+'\" Copyright (c) 1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: file.n,v 1.42 2007/04/03 15:58:55 dgp Exp $
+'\" 
+.so man.macros
+.TH file n 8.3 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+file \- Manipulate file names and attributes
+.SH SYNOPSIS
+\fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+This command provides several operations on a file's name or attributes.
+\fIName\fR 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
+\fBfilename\fR for details).  \fIOption\fR indicates what to do with the
+file name.  Any unique abbreviation for \fIoption\fR is acceptable.  The
+valid options are:
+.TP
+\fBfile atime \fIname\fR ?\fBtime\fR?
+.
+Returns a decimal string giving the time at which file \fIname\fR was last
+accessed.  If \fItime\fR 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.
+.TP
+\fBfile attributes \fIname\fR
+.TP
+\fBfile attributes \fIname\fR ?\fBoption\fR?
+.TP
+\fBfile attributes \fIname\fR ?\fBoption value option value...\fR?
+.RS
+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:
+.PP
+On Unix, \fB-group\fR gets or sets the group name for the file. A group id
+can be given to the command, but it returns a group name. \fB-owner\fR 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. \fB-permissions\fR 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:
+\fBu+s,go\-rw\fR add sticky bit for user, remove read and write
+permissions for group and other).  A simplified \fBls\fR style string,
+of the form rwxrwxrwx (must be 9 characters), is also supported
+(example: \fBrwxr\-xr\-t\fR is equivalent to 01755).
+On versions of Unix supporting file flags, \fB-readonly\fR gives the
+value or sets or clears the readonly attribute of the file,
+i.e. the user immutable flag \fBuchg\fR to chflags(1).
+.PP
+On Windows, \fB-archive\fR gives the value or sets or clears the
+archive attribute of the file. \fB-hidden\fR gives the value or sets
+or clears the hidden attribute of the file. \fB-longname\fR will
+expand each path element to its long version. This attribute cannot be
+set. \fB-readonly\fR gives the value or sets or clears the readonly
+attribute of the file. \fB-shortname\fR gives a string where every
+path element is replaced with its short (8.3) version of the
+name. This attribute cannot be set. \fB-system\fR gives or sets or
+clears the value of the system attribute of the file.
+.PP
+On Mac OS X and Darwin, \fB-creator\fR gives or sets the
+Finder creator type of the file. \fB-hidden\fR gives or sets or clears
+the hidden attribute of the file. \fB-readonly\fR gives or sets or
+clears the readonly attribute of the file. \fB-rsrclength\fR gives
+the length of the resource fork of the file, this attribute can only be
+set to the value 0, which results in the resource fork being stripped
+off the file.
+.RE
+.TP
+\fBfile channels ?\fIpattern\fR?
+.
+If \fIpattern\fR isn't specified, returns a list of names of all
+registered open channels in this interpreter.  If \fIpattern\fR is
+specified, only those names matching \fIpattern\fR are returned.  Matching
+is determined using the same rules as for \fBstring match\fR.
+.TP
+\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
+.TP
+\fBfile copy \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
+.RS
+The first form makes a copy of the file or directory \fIsource\fR under
+the pathname \fItarget\fR. If \fItarget\fR is an existing directory,
+then the second form is used.  The second form makes a copy inside
+\fItargetDir\fR of each \fIsource\fR file listed.  If a directory is
+specified as a \fIsource\fR, then the contents of the directory will be
+recursively copied into \fItargetDir\fR. Existing files will not be
+overwritten unless the \fB\-force\fR option is specified (when Tcl will
+also attempt to adjust permissions on the destination file or directory
+if that is necessary to allow the copy to proceed).  When copying
+within a single filesystem, \fIfile copy\fR 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
+\fI\-force\fR was specified.  Arguments are processed in the order
+specified, halting at the first error, if any.  A \fB\-\|\-\fR marks
+the end of switches; the argument following the \fB\-\|\-\fR will be
+treated as a \fIsource\fR even if it starts with a \fB\-\fR.
+.RE
+.TP
+\fBfile delete \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIpathname\fR ?\fIpathname\fR ... ?
+.
+Removes the file or directory specified by each \fIpathname\fR
+argument.  Non-empty directories will be removed only if the
+\fB\-force\fR 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 \fB\-force\fR flags is not specified.  If the \fB\-force\fR
+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 \fB\-\|\-\fR marks the end of switches; the argument following the
+\fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with
+a \fB\-\fR.
+.TP
+\fBfile dirname \fIname\fR
+Returns a name comprised of all of the path components in \fIname\fR
+excluding the last element.  If \fIname\fR is a relative file name and
+only contains one path element, then returns ``\fB.\fR''.  If \fIname\fR
+refers to a root directory, then the root directory is returned.  For
+example,
+.RS
+.CS
+\fBfile dirname c:/\fR
+.CE
+returns \fBc:/\fR. 
+.PP
+Note that tilde substitution will only be
+performed if it is necessary to complete the command. For example,
+.CS
+\fBfile dirname ~/src/foo.c\fR
+.CE
+returns \fB~/src\fR, whereas
+.CS
+\fBfile dirname ~\fR
+.CE
+returns \fB/home\fR (or something similar).
+.RE
+.TP
+\fBfile executable \fIname\fR
+.
+Returns \fB1\fR if file \fIname\fR is executable by the current user,
+\fB0\fR otherwise.  
+.TP
+\fBfile exists \fIname\fR
+.
+Returns \fB1\fR if file \fIname\fR exists and the current user has
+search privileges for the directories leading to it, \fB0\fR otherwise.
+.TP
+\fBfile extension \fIname\fR
+.
+Returns all of the characters in \fIname\fR after and including the last
+dot in the last element of \fIname\fR.  If there is no dot in the last
+element of \fIname\fR then returns the empty string.
+.TP
+\fBfile isdirectory \fIname\fR
+.
+Returns \fB1\fR if file \fIname\fR is a directory, \fB0\fR otherwise.
+.TP
+\fBfile isfile \fIname\fR
+.
+Returns \fB1\fR if file \fIname\fR is a regular file, \fB0\fR otherwise.
+.TP
+\fBfile join \fIname\fR ?\fIname ...\fR?
+.
+Takes one or more file names and combines them, using the correct path
+separator for the current platform.  If a particular \fIname\fR 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,
+.RS
+.CS
+\fBfile join a b /foo bar\fR
+.CE
+returns \fB/foo/bar\fR.
+.PP
+Note that any of the names can contain separators, and that the result
+is always canonical for the current platform: \fB/\fR for Unix and
+Windows.
+.RE
+.TP
+\fBfile link ?\fI-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
+.
+If only one argument is given, that argument is assumed to be
+\fIlinkName\fR, and this command returns the value of the link given by
+\fIlinkName\fR (i.e. the name of the file it points to).  If
+\fIlinkName\fR 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 \fIlinkName\fR
+and \fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR
+doesn't exist, an error will be returned.  Otherwise, Tcl creates a new
+link called \fIlinkName\fR which points to the existing filesystem
+object at \fItarget\fR (which is also the returned value), 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
+\fI-linktype\fR argument should be given.  Accepted values for
+\fI-linktype\fR are "-symbolic" and "-hard".
+.
+On Unix, symbolic links can be made to relative paths, and those paths
+must be relative to the actual \fIlinkName\fR's location (not to the
+cwd), but on all other platforms where relative links are not supported,
+target paths will always be converted to absolute, normalized form
+before the link is created (and therefore relative paths are interpreted
+as relative to the cwd).  Furthermore, "~user" paths are always expanded
+to absolute form.  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) and Windows
+NT/2000/XP (on NTFS drives) support symbolic
+directory links and hard file links.
+.TP
+\fBfile lstat \fIname varName\fR
+.
+Same as \fBstat\fR option (see below) except uses the \fIlstat\fR
+kernel call instead of \fIstat\fR.  This means that if \fIname\fR
+refers to a symbolic link the information returned in \fIvarName\fR
+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 \fBstat\fR option.
+.TP
+\fBfile mkdir \fIdir\fR ?\fIdir\fR ...?
+.
+Creates each directory specified.  For each pathname \fIdir\fR specified,
+this command will create all non-existing parent directories as
+well as \fIdir\fR 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.
+.TP
+\fBfile mtime \fIname\fR ?\fItime\fR?
+.
+Returns a decimal string giving the time at which file \fIname\fR was last
+modified.  If \fItime\fR is specified, it is a modification time to set for
+the file (equivalent to Unix \fBtouch\fR).  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.
+.TP
+\fBfile nativename \fIname\fR
+.
+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.
+.TP
+\fBfile normalize \fIname\fR
+.
+.RS
+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 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).
+.RE
+.TP
+\fBfile owned \fIname\fR 
+.
+Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR
+otherwise.
+.TP
+\fBfile pathtype \fIname\fR
+.
+Returns one of \fBabsolute\fR, \fBrelative\fR, \fBvolumerelative\fR. If
+\fIname\fR refers to a specific file on a specific volume, the path type will
+be \fBabsolute\fR. If \fIname\fR refers to a file relative to the current
+working directory, then the path type will be \fBrelative\fR. If \fIname\fR
+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 path
+type is \fBvolumerelative\fR.
+.TP
+\fBfile readable \fIname\fR
+.
+Returns \fB1\fR if file \fIname\fR is readable by the current user,
+\fB0\fR otherwise. 
+.TP
+\fBfile readlink \fIname\fR
+.
+Returns the value of the symbolic link given by \fIname\fR (i.e. the name
+of the file it points to).  If \fIname\fR 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.
+.TP
+\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR \fItarget\fR
+.TP
+\fBfile rename \fR?\fB\-force\fR? ?\fB\-\|\-\fR? \fIsource\fR ?\fIsource\fR ...? \fItargetDir\fR
+.RS
+The first form takes the file or directory specified by pathname
+\fIsource\fR and renames it to \fItarget\fR, moving the file if the
+pathname \fItarget\fR specifies a name in a different directory.  If
+\fItarget\fR is an existing directory, then the second form is used.
+The second form moves each \fIsource\fR file or directory into the
+directory \fItargetDir\fR. Existing files will not be overwritten
+unless the \fB\-force\fR 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 \fB\-\|\-\fR marks the end of
+switches; the argument following the \fB\-\|\-\fR will be treated as a
+\fIsource\fR even if it starts with a \fB\-\fR.
+.RE
+.TP
+\fBfile rootname \fIname\fR
+.
+Returns all of the characters in \fIname\fR up to but not including the
+last ``.'' character in the last component of name.  If the last
+component of \fIname\fR doesn't contain a dot, then returns \fIname\fR.
+.TP
+\fBfile separator\fR ?\fIname\fR?
+.
+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 \fIname\fR, an error
+is generated.
+.TP
+\fBfile size \fIname\fR
+.
+Returns a decimal string giving the size of file \fIname\fR in bytes.  If
+the file doesn't exist or its size cannot be queried then an error is
+generated.
+.TP
+\fBfile split \fIname\fR
+.
+Returns a list whose elements are the path components in \fIname\fR.  The
+first element of the list will have the same path type as \fIname\fR.
+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
+.RS
+.CS
+file split /foo/~bar/baz
+.CE
+returns \fB/\0\0foo\0\0./~bar\0\0baz\fR to ensure that later commands
+that use the third component do not attempt to perform tilde
+substitution.
+.RE
+.TP
+\fBfile stat  \fIname varName\fR
+.
+Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the variable
+given by \fIvarName\fR to hold information returned from the kernel call.
+\fIVarName\fR is treated as an array variable, and the following elements
+of that variable are set: \fBatime\fR, \fBctime\fR, \fBdev\fR, \fBgid\fR,
+\fBino\fR, \fBmode\fR, \fBmtime\fR, \fBnlink\fR, \fBsize\fR, \fBtype\fR,
+\fBuid\fR.  Each element except \fBtype\fR is a decimal string with the
+value of the corresponding field from the \fBstat\fR return structure;
+see the manual entry for \fBstat\fR for details on the meanings of the
+values.  The \fBtype\fR element gives the type of the file in the same
+form returned by the command \fBfile type\fR.  This command returns an
+empty string.
+.TP
+\fBfile system \fIname\fR
+.
+Returns a list of one or two elements, the first of which is the name of
+the filesystem to use for the file, and the second, if given, 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 not be supplied.  For example the
+native files have a first element 'native', and a second element which
+when given is a platform-specific type name for the file's system
+(e.g. 'NTFS', 'FAT', on Windows).  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.
+.TP
+\fBfile tail \fIname\fR
+.
+Returns all of the characters in the last filesystem component of
+\fIname\fR.  Any trailing directory separator in \fIname\fR is ignored.
+If \fIname\fR contains no separators then returns \fIname\fR.  So, 
+\fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all
+return \fBb\fR.
+.TP
+\fBfile type \fIname\fR
+.
+Returns a string giving the type of file \fIname\fR, which will be one of
+\fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR,
+\fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
+.TP
+\fBfile volumes\fR
+. 
+Returns the absolute paths to the volumes mounted on the system, as a
+proper Tcl list.  Without any virtual filesystems mounted as root
+volumes, 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:/}).  If any virtual filesystem has mounted additional
+volumes, they will be in the returned list.
+.TP
+\fBfile writable \fIname\fR
+.
+Returns \fB1\fR if file \fIname\fR is writable by the current user,
+\fB0\fR otherwise.
+.SH "PORTABILITY ISSUES"
+.TP
+\fBUnix\fR\0\0\0\0\0\0\0
+.
+These commands always operate using the real user and group identifiers,
+not the effective ones. 
+.SH EXAMPLES
+This procedure shows how to search for C files in a given directory
+that have a correspondingly-named object file in the current
+directory:
+.CS
+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 [\fBfile tail\fR [\fBfile rootname\fR $file]]$ext
+      if {[\fBfile exists\fR $objectFile]} {
+         lappend files $file
+      }
+   }
+   return $files
+}
+.CE
+.PP
+Rename a file and leave a symbolic link pointing from the old location
+to the new place:
+.CS
+set oldName foobar.txt
+set newName foo/bar.txt
+# Make sure that where we're going to move to exists...
+if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} {
+   \fBfile mkdir\fR [\fBfile dirname\fR $newName]
+}
+\fBfile rename\fR $oldName $newName
+\fBfile link\fR -symbolic $oldName $newName
+.CE
+
+.SH "SEE ALSO"
+filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),
+fblocked(n), flush(n)
+
+.SH KEYWORDS
+attributes, copy files, delete files, directory, file, move files, name, rename files, stat