4 fs fixes

2 files changed, 138 insertions, 40 deletions

diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index cbfa25b..d504b64 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: FileSystem.3,v 1.19 2002/02/15 14:28:47 dkf Exp $
+'\" RCS: @(#) $Id: FileSystem.3,v 1.20 2002/03/24 11:41:48 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
@@ -495,7 +495,11 @@ string value can be used as a unique identifier for the file.
 .PP
 It returns the normalized path object, with refCount of zero, or NULL 
 if the path was invalid or could otherwise not be successfully
-converted.
+converted.  Extraction of absolute, normalized paths is very
+efficient (because the filesystem operates on these representations
+internally), although the result when the filesystem contains
+numerous symbolic links may not be the most user-friendly
+version of a path.
 .PP
 \fBTcl_FSJoinToPath\fR takes the given object, which should usually be a
 valid path or NULL, and joins onto it the array of paths segments
@@ -518,7 +522,7 @@ be left in the interpreter.
 path object, in the given filesystem.  If the path object belongs to a
 different filesystem, we return NULL. If the internal representation is
 currently NULL, we attempt to generate it, by calling the filesystem's
-\fBTclfsConvertToInternalProc_\fR.
+\fBTcl_FSCreateInternalRepProc\fR.
 .PP
 Returns NULL or a valid internal path representation.  This internal
 representation is cached, so that repeated calls to this function will
@@ -529,12 +533,14 @@ from the given Tcl_Obj.
 .PP
 If the translation succeeds (i.e. the object is a valid path), then it
 is returned.  Otherwise NULL will be returned, and an error message may
-be left in the interpreter.
+be left in the interpreter.  A "translated" path is one which
+contains no "~" or "~user" sequences (these have been expanded to
+their current representation in the filesystem).
 .PP
 \fBTcl_FSGetTranslatedStringPath\fR does the same as 
 \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
 .PP
-\fBTcl_FSNewNativePath\fR performs the something like that reverse of the
+\fBTcl_FSNewNativePath\fR performs something like that reverse of the
 usual obj->path->nativerep conversions.  If some code retrieves a path
 in native form (from, e.g. readlink or a native dialog), and that path
 is to be used at the Tcl level, then calling this function is an
@@ -545,7 +551,15 @@ a Utf-8 string representation if that is required by some Tcl code.
 .PP
 \fBTcl_FSGetNativePath\fR is for use by the Win/Unix/MacOS native
 filesystems, so that they can easily retrieve the native (char* or
-TCHAR*) representation of a path.
+TCHAR*) representation of a path.  This function is a convenience
+wrapper around \fBTcl_FSGetInternalRep\fR, and assumes the native
+representation is string-based.  It may be desirable in the future
+to have non-string-based native representations (for example, on
+MacOS, a representation using a fileSpec of FSRef structure would
+probably be more efficient).  On Windows a full Unicode
+representation would allow for paths of unlimited length.  Currently
+the representation is simply a character string containing the
+complete, absolute path in the native encoding.
 .PP
 The native representation is cached so that repeated calls to this
 function will not require additional conversions.
@@ -666,10 +680,62 @@ functions (it will use \fITcl_FSCopyFileProc\fR followed by
 \fITcl_FSDeleteFileProc\fR, and if \fITcl_FSCopyFileProc\fR is not
 implemented there is a further fallback).  However, if a
 \fITcl_FSRenameFile\fR command is issued at the C level, no such
-fallbacks occur.  This is true except for the last five entries in the
-filesystem table (lstat, load, unload, getcwd and chdir)
+fallbacks occur.  This is true except for the last four entries in the
+filesystem table (lstat, load, getcwd and chdir)
 for which fallbacks do in fact occur at the C level.
 .PP
+As an example, here is the filesystem lookup table used by the
+"vfs" extension which allows filesystem actions to be implemented
+in Tcl.
+.CS
+static Tcl_Filesystem vfsFilesystem = {
+    "tclvfs",
+    sizeof(Tcl_Filesystem),
+    TCL_FILESYSTEM_VERSION_1,
+    &VfsPathInFilesystem,
+    &VfsDupInternalRep,
+    &VfsFreeInternalRep,
+    /* No internal to normalized, since we don't create any
+     * pure 'internal' Tcl_Obj path representations */
+    NULL,
+    /* No create native rep function, since we don't use it
+     * and don't choose to support uses of 'Tcl_FSNewNativePath' */
+    NULL,
+    /* Normalize path isn't needed - we assume paths only have
+     * one representation */
+    NULL,
+    &VfsFilesystemPathType,
+    &VfsFilesystemSeparator,
+    &VfsStat,
+    &VfsAccess,
+    &VfsOpenFileChannel,
+    &VfsMatchInDirectory,
+    &VfsUtime,
+    /* We choose not to support symbolic links inside our vfs's */
+    NULL,
+    &VfsListVolumes,
+    &VfsFileAttrStrings,
+    &VfsFileAttrsGet,
+    &VfsFileAttrsSet,
+    &VfsCreateDirectory,
+    &VfsRemoveDirectory, 
+    &VfsDeleteFile,
+    /* No copy file - fallback will occur at Tcl level */
+    NULL,
+    /* No rename file - fallback will occur at Tcl level */
+    NULL,
+    /* No copy directory - fallback will occur at Tcl level */
+    NULL, 
+    /* Core will use stat for lstat */
+    NULL,
+    /* No load - fallback on core implementation */
+    NULL,
+    /* We don't need a getcwd or chdir - fallback on Tcl's versions */
+    NULL,
+    NULL
+};
+.CE
+.PP
 Any functions which take path names in Tcl_Obj form take
 those names in UTF\-8 form.  The filesystem infrastructure API is
 designed to support efficient, cached conversion of these UTF\-8 paths
@@ -768,7 +834,13 @@ string representation.  Depending on the filesystem,
 there may be more than one unnormalized string representation which
 refers to that path (e.g. a relative path, a path with different
 character case if the filesystem is case insensitive, a path contain a
-reference to a home directory such as '~', etc).
+reference to a home directory such as '~', a path containing symbolic
+links, etc).  If the very last component in the path is a symbolic
+link, it should not be converted into the object it points to (but
+its case or other aspects should be made unique).  All other path
+components should be converted from symbolic links.  This one
+exception is required to agree with Tcl's semantics with 'file
+delete', 'file rename', 'file copy' operating on symbolic links.
 .PP
 .CS
 typedef int Tcl_FSNormalizePathProc(
@@ -909,9 +981,13 @@ typedef int Tcl_FSMatchInDirectoryProc(
 .PP
 The function should return all files or directories (or other
 filesystem objects) which match the given pattern and accord with the
-\fItypes\fR specification given.  The directory \fIpathPtr\fR, in which
-the function should search, can be assumed to be both non-NULL and
-non-empty.
+\fItypes\fR specification given.  There are two ways in which this 
+function may be called.  If \fIpattern\fR is NULL, then \fIpathPtr\fR
+is a full path specification of a single file or directory which
+should be checked for existence and correct type.  Otherwise, \fIpathPtr\fR
+is a directory, the contents of which the function should search for 
+files or directories which have the correct type.  In either case,
+\fIpathPtr\fR can be assumed to be both non-NULL and non-empty.  
 .PP
 The return value is a standard Tcl result indicating whether an error
 occurred in the matching process.  Error messages are placed in interp, 
@@ -919,7 +995,10 @@ but on a TCL_OK result, the interpreter should not be modified, but
 rather results should be added to the \fIresult\fR object given
 (which can be assumed to be a valid Tcl list).  The matches added
 to \fIresult\fR should include any path prefix given in \fIpathPtr\fR 
-(this usually means they will be absolute path specifications).
+(this usually means they will be absolute path specifications). 
+Note that if no matches are found, that simply leads to an empty 
+result --- errors are only signalled for actual file or filesystem
+problems which may occur during the matching process.
 .SH UTIMEPROC       
 .PP
 Function to process a \fBTcl_FSUtime()\fR call.  Required to allow setting
@@ -1164,7 +1243,8 @@ than the Tcl level 'file copy' subcommand).
 Function to process a \fBTcl_FSLoadFile()\fR call.  If not implemented, Tcl
 will fall back on a copy to native-temp followed by a Tcl_FSLoadFile on
 that temporary copy.  Therefore it need only be implemented if the
-filesystem can load code directly, or to disable load functionality
+filesystem can load code directly, or it can be implemented simply to
+return TCL_ERROR to disable load functionality in this filesystem
 entirely.
 .PP
 .CS
diff --git a/doc/file.n b/doc/file.n
index c572a32..b8c33a8 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -5,7 +5,7 @@
 '\" 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.13 2001/12/10 15:50:47 dgp Exp $
+'\" RCS: @(#) $Id: file.n,v 1.14 2002/03/24 11:41:48 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH file n 8.3 Tcl "Tcl Built-In Commands"
@@ -110,17 +110,20 @@ treated as a \fIsource\fR even if it starts with a \fB\-\fR.
 .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.  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 
+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.
+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
@@ -223,15 +226,27 @@ under Windows or AppleScript on the Macintosh.
 .TP
 \fBfile normalize \fIname\fR
 .
-Returns a unique normalised path representation for the file, whose
-string value can be used as a unique identifier for the it.  A
-normalized path is one which has all '../', './' removed.  Also it is
-one which is in the ``standard'' format for the native platform.  On
-MacOS, Unix, this means the path must be free of symbolic
-links/aliases, and on Windows it also means means we want the long form
-(when running Win NT/2000/XP) or the short form (when running Win
-95/98) with that form's case-dependence (which gives us a unique,
-case-dependent path).
+Returns a unique normalised 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 one which has all
+'../', './' removed.  Also it is one which is in the ``standard''
+format for the native platform.  On MacOS, 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 means we want the long form (when running Win
+NT/2000/XP) or the short form (when running Win 95/98) 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).
+.PP
+Note that this means normalized paths are different on old Windows
+operating systems (95/98) and new Windows operating systems
+(NT/2000/XP).  This is necessary because the APIs  
+to produce a long normalized path in older operating systems are 
+unfortunately very slow.
 .TP
 \fBfile owned \fIname\fR 
 .
@@ -267,12 +282,14 @@ support symbolic links this option is undefined.
 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.  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,
+\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.
@@ -331,7 +348,8 @@ empty string.
 \fBfile system \fIname\fR
 .
 Returns a list of two elements, the first of which is the name of the
-filesystem to use for the file, and the second the type of the file
+filesystem to use for the file, and the second 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 be null.  For example the native files
 have a first element 'native', and a second element which is a