* doc/FileSystem.3: added missing Tcl_GlobTypeData documentation

        [Bug 935853]

1 files changed, 34 insertions, 6 deletions

diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 1188778..54236c8 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.32.2.3 2005/04/29 14:09:35 dkf Exp $
+'\" RCS: @(#) $Id: FileSystem.3,v 1.32.2.4 2005/06/20 16:57:43 dgp Exp $
 '\" 
 .so man.macros
 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
@@ -1027,15 +1027,43 @@ documented whether \fIpathPtr\fR will have a file separator at its end of
 not, so code should be flexible to both possibilities.
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in the matching process.  Error messages are placed in interp, 
-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
+occurred in the matching process.  Error messages are placed in
+\fIinterp\fR; on a \fBTCL_OK\fR result, results should be added to the
+\fIresult\fR object given (which can be assumed to be a valid
+unshared 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). 
 Note that if no matches are found, that simply leads to an empty 
-result --- errors are only signaled for actual file or filesystem
+result; errors are only signaled for actual file or filesystem
 problems which may occur during the matching process.
+.PP
+The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR 
+parameter contains the following fields:
+.CS
+typedef struct Tcl_GlobTypeData {
+      /* Corresponds to bcdpfls as in 'find -t' */
+      int \fItype\fR;
+      /* Corresponds to file permissions */
+      int \fIperm\fR;
+      /* Acceptable mac type */
+      Tcl_Obj *\fImacType\fR;
+      /* Acceptable mac creator */
+      Tcl_Obj *\fImacCreator\fR;
+} Tcl_GlobTypeData;
+.CE
+.PP
+There are two specific cases which it is important to handle correctly,
+both when \fItypes\fR is non-NULL. The two cases are when \fItypes->types
+& TCL_GLOB_TYPE_DIR\fR or \fItypes->types & TCL_GLOB_TYPE_MOUNT\fR are
+true (and in particular when the other flags are false).  In the first of
+these cases, the function must list the contained directories.  Tcl uses
+this to implement recursive globbing, so it is critical that filesystems
+implement directory matching correctly.  In the second of these cases,
+with \fBTCL_GLOB_TYPE_MOUNT\fR, the filesystem must list the mount points
+which lie within the given \fIpathPtr\fR (and in this case, \fIpathPtr\fR
+need not lie within the same filesystem - different to all other cases in
+which this function is called).  Support for this is critical if Tcl is
+to have seamless transitions between from one filesystem to another.
 .SH UTIMEPROC       
 .PP
 Function to process a \fBTcl_FSUtime()\fR call.  Required to allow setting