fs update

4 files changed, 63 insertions, 28 deletions

diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 1da96c5..7e49235 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -4,13 +4,13 @@
 '\" 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.2 2001/08/07 02:59:14 hobbs Exp $
+'\" RCS: @(#) $Id: FileSystem.3,v 1.3 2001/08/23 17:37:07 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH Tcl_FSCopyFile 3 8.4 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSReadlink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo \- procedures to interact with any filesystem
+Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSReadlink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo \- procedures to interact with any filesystem
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -42,8 +42,8 @@ int
 int
 \fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR)
 .sp
-int
-\fBTcl_FSListVolumes\fR(\fIinterp\fR)
+Tcl_Obj*
+\fBTcl_FSListVolumes\fR(\fIvoid\fR)
 .sp
 int
 \fBTcl_FSEvalFile\fR(\fIinterp, fileName\fR)
@@ -55,7 +55,7 @@ int
 \fBTcl_FSMatchInDirectory\fR(\fIinterp, result, pathPtr, pattern, types\fR)
 .sp
 Tcl_Obj*
-\fBTcl_FSReadlink\fR(\fIpathPtr\fR)
+\fBTcl_FSLink\fR(\fIpathPtr, toPtr\fR)
 .sp
 int
 \fBTcl_FSLstat\fR(\fIpathPtr, statPtr\fR)
@@ -111,9 +111,12 @@ int
 ClientData 
 \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR)
 .sp
-char* 
+Tcl_Obj* 
 \fBTcl_FSGetTranslatedPath\fR(\fIinterp, pathPtr\fR)
 .sp
+char* 
+\fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR)
+.sp
 Tcl_Obj*
 \fBTcl_FSNewNativePath\fR(\fIfsPtr, clientData\fR)
 .sp
@@ -230,7 +233,20 @@ native files in the native filesystem.  If appropriate vfs's have been
 registered, the 'files' may, to give two examples, be remote (e.g.
 situated on a remote ftp server) or archived (e.g. lying inside a .zip
 archive).  Such registered filesystems provide a lookup table of
-functions to implement all or some of the functionality listed here.  
+functions to implement all or some of the functionality listed here.
+.PP
+The \fBTcl_FS...\fR are objectified and may cache internal
+representations and other path-related strings (e.g. the current
+working directory).  One side-effect of this is that one must be
+careful when passing in temporary objects with a refCount of zero. 
+Under some circumstances, the filesystem code may wish to retain a
+reference to the passed in object, and so one must not assume that
+after any of these calls return, the object still has a refCount of
+zero - it may have been incremented.  The practical lesson to learn
+from this is that \fbTcl_Obj *path = Tcl_NewStringObj(...) ;
+Tcl_FS...(path) ; Tcl_DecrRefCount(path)\fR is wrong, and may
+segfault.  The 'path' must have its refCount incremented before
+passing it in, or decrementing it.
 .PP
 \fBTcl_FSCopyFile\fR attempts to copy the file given by srcPathPtr to the
 path name given by destPathPtr.  If the two paths given lie in the same
@@ -267,8 +283,9 @@ sets Tcl's errno to the 'EXDEV' posix error code (which signifies a
 'cross-domain link').
 .PP
 \fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL 'list
-volumes' function and asks those to append their root volumes to 
-the list in the interpreters result.
+volumes' function and asks them to return their list of root volumes.  It
+accumulates the return values in a list which is returned to the
+caller (with a refCount of 0).
 .PP
 \fBTcl_FSEvalFile\fR reads the file given by \fIpathPtr\fR and evaluates
 its contents as a Tcl script.  It returns the same information as
@@ -305,14 +322,18 @@ matched using the logic of 'string match'.  To handle recursion, Tcl
 will call this function frequently asking only for directories to be
 returned.
 .PP
-\fBTcl_FSReadlink\fR replaces the library version of readlink().
+\fBTcl_FSLink\fR replaces the library version of readlink(), and may
+also be used in the future to allow link creation.
 The appropriate function for the filesystem to which pathPtr
 belongs will be called.
 .PP
+If the \fItoPtr\fR is NULL, a readlink action is performed.
 The result is a Tcl_Obj specifying the contents of the symbolic link
-given by 'path', or NULL if the symbolic link could not be read.  The
+given by \fIpath\fR, or NULL if the symbolic link could not be read.  The
 result is owned by the caller, which should call Tcl_DecrRefCount when
-the result is no longer needed.
+the result is no longer needed.  If the \fItoPtr\fR is not NULL, Tcl
+should create a link, but this option is not currently supported (it
+is left available for future expansion).
 .PP
 \fBTcl_FSLstat\fR fills the stat structure \fIstatPtr\fR with information
 about the specified file.  You do not need any access rights to the
@@ -487,13 +508,16 @@ Returns NULL or a valid internal path representation.  This internal
 representation is cached, so that repeated calls to this function will
 not require additional conversions.
 .PP
-\fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path string
+\fBTcl_FSGetTranslatedPath\fR attempts to extract the translated path
 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.
 .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
 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
@@ -915,8 +939,7 @@ Should be implemented only if the filesystem adds volumes at the head
 of the filesystem, so that they can be returned by 'file volumes'.
 .PP
 .CS
-typedef int Tcl_FSListVolumesProc(
-	Tcl_Interp *\fIinterp\fR);
+typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
 .CE
 .PP
 The result should be TCL_OK, since there is no way this function can
diff --git a/doc/SplitPath.3 b/doc/SplitPath.3
index b112b82..71ebe82 100644
--- a/doc/SplitPath.3
+++ b/doc/SplitPath.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: SplitPath.3,v 1.2 1998/09/14 18:39:50 stanton Exp $
+'\" RCS: @(#) $Id: SplitPath.3,v 1.3 2001/08/23 17:37:07 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures"
@@ -45,6 +45,9 @@ A pointer to an initialized \fBTcl_DString\fR to which the result of
 
 .SH DESCRIPTION
 .PP
+These procedures have been superceded by the objectified procedures in
+the \fBFileSystem\fR man page, which are more efficient.
+.PP
 These procedures may be used to disassemble and reassemble file
 paths in a platform independent manner: they provide C-level access to
 the same functionality as the \fBfile split\fR, \fBfile join\fR, and
diff --git a/doc/filename.n b/doc/filename.n
index 42a9dce..34939c0 100644
--- a/doc/filename.n
+++ b/doc/filename.n
@@ -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: filename.n,v 1.4 2000/09/07 14:27:47 poenitz Exp $
+'\" RCS: @(#) $Id: filename.n,v 1.5 2001/08/23 17:37:07 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH filename n 7.5 Tcl "Tcl Built-In Commands"
@@ -177,9 +177,13 @@ substitution.
 .PP
 The Macintosh and Windows platforms do not support tilde substitution
 when a user name follows the tilde.  On these platforms, attempts to
-use a tilde followed by a user name will generate an error.  File
-names that have a tilde without a user name will be substituted using
-the \fB$HOME\fR environment variable, just like for Unix.
+use a tilde followed by a user name will generate an error that the
+user does not exist when Tcl attempts to interpret that part of the
+path or otherwise access the file.  The behaviour of these paths
+when not trying to interpret them is the same as on Unix.  File
+names that have a tilde without a user name will be correctly
+substituted using the \fB$HOME\fR environment variable, just like 
+for Unix.
 
 .SH "PORTABILITY ISSUES"
 .PP
diff --git a/doc/glob.n b/doc/glob.n
index 38a96df..409001b 100644
--- a/doc/glob.n
+++ b/doc/glob.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: glob.n,v 1.9 2001/07/31 19:12:06 vincentdarley Exp $
+'\" RCS: @(#) $Id: glob.n,v 1.10 2001/08/23 17:37:07 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH glob n 8.3 Tcl "Tcl Built-In Commands"
@@ -33,7 +33,8 @@ Search for files which match the given patterns starting in the given
 \fIdirectory\fR.  This allows searching of directories whose name
 contains glob-sensitive characters without the need to quote such
 characters explicitly.  This option may not be used in conjunction with
-\fB\-path\fR.
+\fB\-path\fR, which is used to allow searching for complete file paths
+whose names may contain glob-sensitive characters.
 .TP
 \fB\-join\fR
 The remaining pattern arguments are treated as a single pattern
@@ -48,18 +49,22 @@ switch an error is returned if the result list would be empty.
 \fB\-path\fR \fIpathPrefix\fR
 Search for files with the given \fIpathPrefix\fR where the rest of the name
 matches the given patterns.  This allows searching for files with names
-similar to a given file even when the names contain glob-sensitive
+similar to a given file (as opposed to a directory) even when the names 
+contain glob-sensitive 
 characters.  This option may not be used in conjunction with
-\fB\-directory\fR.
+\fB\-directory\fR.  For example, to find all files with the same root name
+as $path, but differing extensions, you should use \fBglob 
+-path [file rootname $path] .*\fR which will work even if $path contains
+numerous glob-sensitive characters.
 .TP
 \fB\-tails\fR
 Only return the part of each file found which follows the last directory
 named in any \fB\-directory\fR or \fB\-path\fR path specification.  
-Thus \fBglob -tails -dir $dir *\fR is equivalent to 
+Thus \fBglob -tails -directory $dir *\fR is equivalent to 
 \fBset pwd [pwd] ; cd $dir ; glob *; cd $pwd\fR.  For 
 \fB\-path\fR specifications, the returned names will include the last
-path segment, so \fBglob -tails -path /usr/loc */*\fR will return paths
-like \fBlocal/bin local/lib\fR etc.
+path segment, so \fBglob -tails -path [file rootname ~/foo.tex] .*\fR 
+will return paths like \fBfoo.aux foo.bib foo.tex\fR etc.
 .TP
 \fB\-types\fR \fItypeList\fR
 Only list files or directories which match \fItypeList\fR, where the items
@@ -164,7 +169,7 @@ like ``.../'' and ``..../'' for successively higher up parent directories.
 .TP 
 \fBMacintosh\fR 
 . 
-When using the options, \fB\-dir\fR, \fB\-join\fR or \fB\-path\fR, glob
+When using the options, \fB\-directory\fR, \fB\-join\fR or \fB\-path\fR, glob
 assumes the directory separator for the entire pattern is the standard
 ``:''.  When not using these options, glob examines each pattern argument
 and uses ``/'' unless the pattern contains a ``:''.