4 fs fixes

1 files changed, 94 insertions, 14 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