diff options
| author | vincentdarley <vincentdarley> | 2001-09-29 11:09:34 (GMT) |
|---|---|---|
| committer | vincentdarley <vincentdarley> | 2001-09-29 11:09:34 (GMT) |
| commit | c1bf313ccab38b8a3a01c91baf5f02288f604a07 (patch) | |
| tree | 7dd42cb7c0e0c6bb2d80e9f322e5382a1f342915 | |
| parent | 02c86dcaaba99b53c26cfa3f1094a84781071c76 (diff) | |
| download | tcl-c1bf313ccab38b8a3a01c91baf5f02288f604a07.zip tcl-c1bf313ccab38b8a3a01c91baf5f02288f604a07.tar.gz tcl-c1bf313ccab38b8a3a01c91baf5f02288f604a07.tar.bz2 | |
fs doc improvement
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | doc/FileSystem.3 | 18 | ||||
| -rw-r--r-- | generic/tclIOUtil.c | 9 |
3 files changed, 28 insertions, 5 deletions
@@ -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. |