summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--ChangeLog6
-rw-r--r--doc/FileSystem.318
-rw-r--r--generic/tclIOUtil.c9
3 files changed, 28 insertions, 5 deletions
diff --git a/ChangeLog b/ChangeLog
index e4a429a..d10538c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2001-09-29 Vince Darley <vincentdarley@users.sourceforge.net>
+
+ * generic/tclIOUtil.c:
+ * doc/FileSystem.3: corrected and clarified documentation
+ for 'Tcl_FSListVolumes(Proc)'. No code changes.
+
2001-09-28 Miguel Sofer <msofer@users.sourceforge.net>
* doc/FindExec.3: added a comment not to change the working
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 6f9a4e8..e6f750d 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.7 2001/09/28 01:21:53 dgp Exp $
+'\" RCS: @(#) $Id: FileSystem.3,v 1.8 2001/09/29 11:09:35 vincentdarley Exp $
'\"
.so man.macros
.TH Tcl_FSCopyFile 3 8.4 Tcl "Tcl Library Procedures"
@@ -946,9 +946,19 @@ of the filesystem, so that they can be returned by 'file volumes'.
typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
.CE
.PP
-The result should be TCL_OK, since there is no way this function can
-fail. The function should add the known volumes to the list object
-contained in the Tcl interpreter's result.
+The result should be a list of volumes added by this filesystem, or
+NULL (or an empty list) if no volumes are provided. The result object
+is considered to be owned by the filesystem (not by Tcl's core), but
+should be given a refCount for Tcl. Tcl will use the contents of the
+list and then decrement that refCount. This allows filesystems to
+choose whether they actually want to retain a 'master list' of volumes
+or not (if not, they generate the list on the fly and pass it to Tcl
+with a refCount of 1 and then forget about the list, if yes, then
+they simply increment the refCount of their master list and pass it
+to Tcl which will copy the contents and then decrememnt the count back
+to where it was).
+.PP
+Therefore, Tcl considers return values from this proc to be read-only.
.PP
.SH FILEATTRSTRINGSPROC
.PP
diff --git a/generic/tclIOUtil.c b/generic/tclIOUtil.c
index f2f3497..57e99b3 100644
--- a/generic/tclIOUtil.c
+++ b/generic/tclIOUtil.c
@@ -17,7 +17,7 @@
* See the file "license.terms" for information on usage and redistribution
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclIOUtil.c,v 1.21 2001/09/28 01:21:53 dgp Exp $
+ * RCS: @(#) $Id: tclIOUtil.c,v 1.22 2001/09/29 11:09:35 vincentdarley Exp $
*/
#include "tclInt.h"
@@ -2449,6 +2449,13 @@ Tcl_FSLink(pathPtr, toPtr)
* that have been "inserted" into the filesystem will be called in
* succession; each may return a list of volumes, all of which are
* added to the result until all mounted file systems are listed.
+ *
+ * Notice that we assume the lists returned by each filesystem
+ * (if non NULL) have been given a refCount for us already.
+ * However, we are NOT allowed to hang on to the list itself
+ * (it belongs to the filesystem we called). Therefore we
+ * quite naturally add its contents to the result we are
+ * building, and then decrement the refCount.
*
* Results:
* The list of volumes, in an object which has refCount 0.