Bug 1606454 fixed

2 files changed, 495 insertions, 492 deletions

diff --git a/ChangeLog b/ChangeLog
index c5d9229..bab903d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2006-12-02  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/file.n: Clarification of [file pathtype] docs. [Bug 1606454]
+
 2006-12-01  Kevin Kenny	 <kennykb@acm.org>
 
 	* libtommath/bn_mp_add.c:	Corrected the effects of a
@@ -10,13 +14,12 @@
 	* doc/mathfunc.n:	Added isqrt() function to docs
 	* generic/tclBasic.c:	Added isqrt() math function (ExprIsqrtFunc)
 	* tests/expr.test (expr-47.*): Added tests for isqrt()
-	* tests/info.test (info-20.2): Added isqrt() to expected math
-	funcs.
-	
+	* tests/info.test (info-20.2): Added isqrt() to expected math funcs.
+
 2006-12-01  Don Porter  <dgp@users.sourceforge.net>
 
-	* tests/chan.test:	Correct timing sensitivity in new test
-	[Bug 1606860]
+	* tests/chan.test:	Correct timing sensitivity in new test. [Bug
+	1606860]
 
 	TIP#287 IMPLEMENTATION
 
@@ -42,15 +45,15 @@
 2006-11-30  Kevin Kenny  <kennykb@acm.org>
 
 	* library/tzdata: Olson's tzdata2006p.
-	* libtommath/bn_mp_sqrt.c: Fixed a bug where the initial
-	approximation to the square root could be on the wrong side,
-	causing failure of convergence.
-	
+	* libtommath/bn_mp_sqrt.c: Fixed a bug where the initial approximation
+	to the square root could be on the wrong side, causing failure of
+	convergence.
+
 2006-11-29  Don Porter  <dgp@users.sourceforge.net>
 
 	* generic/tclBasic.c (Tcl_AppendObjToErrorInfo):  Added
-	Tcl_DecrRefCount() on the objPtr argument to plug memory leaks.
-	This makes the routine a consumer, which makes it easiest to use.
+	Tcl_DecrRefCount() on the objPtr argument to plug memory leaks. This
+	makes the routine a consumer, which makes it easiest to use.
 
 2006-11-28  Andreas Kupries  <andreask@activestate.com>
 
@@ -78,14 +81,14 @@
 
 	* unix/tclUnixChan.c (TclUnixWaitForFile):
 	* tests/event.test (event-14.*): Corrected a bug where
-	TclUnixWaitForFile would present select() with the wrong mask
-	on an LP64 machine if a fd number exceeds 32.  Thanks to
-	Jean-Luc Fontaine for reporting and diagnosing [Bug 1602208].
-	
+	TclUnixWaitForFile would present select() with the wrong mask on an
+	LP64 machine if a fd number exceeds 32. Thanks to Jean-Luc Fontaine
+	for reporting and diagnosing [Bug 1602208].
+
 2006-11-27  Don Porter  <dgp@users.sourceforge.net>
 
 	* generic/tclExecute.c (TclIncrObj):	Correct failure to detect
-	floating-point increment values.  Thanks to William Coleda [Bug 1602991]
+	floating-point increment values. Thanks to William Coleda [Bug 1602991]
 
 2006-11-26  Donal K. Fellows  <dkf@users.sf.net>
 
@@ -134,7 +137,7 @@
 
 2006-11-20  Donal K. Fellows  <dkf@users.sf.net>
 
-	* generic/tclBasic.c (Tcl_CreateInterp, TclHideUnsafeCommands): 
+	* generic/tclBasic.c (Tcl_CreateInterp, TclHideUnsafeCommands):
 	* library/init.tcl: Refactored the [chan] command's guts so that it
 	does not use aliases to global commands, making the code more robust.
 
diff --git a/doc/file.n b/doc/file.n
index c3c975a..8584468 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.40 2005/05/10 18:33:59 kennykb 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 file 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.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