no zero refcount in Tcl_FS

1 files changed, 18 insertions, 12 deletions

diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 0161dba..d4f4c25 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.28 2002/07/08 10:14:24 vincentdarley Exp $
+'\" RCS: @(#) $Id: FileSystem.3,v 1.29 2002/07/08 12:08:34 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
@@ -257,17 +257,23 @@ declared to be, allowing the same code to be used both on systems with
 and systems without support for files larger than 2GB in size.
 .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.
+representations and other path-related strings (e.g. the current working
+directory).  One side-effect of this is that one must not pass in objects
+with a refCount of zero to any of these functions.  If such calls were 
+handled, they might result
+in memory leaks (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), or in a direct segfault
+due to the object being freed part way through the complex object
+manipulation required to ensure that the path is fully normalized and
+absolute for filesystem determination.  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.  For this reason, objects with a refCount of zero are
+considered not to be valid filesystem paths and calling any Tcl_FS API
+with such an object will result in no action being taken.
 .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