From 03736c0062a33d49dd420b759927e54f7533510c Mon Sep 17 00:00:00 2001 From: vincentdarley Date: Thu, 23 Oct 2003 10:10:11 +0000 Subject: filesystem documentation --- ChangeLog | 3 +++ doc/FileSystem.3 | 63 ++++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 44 insertions(+), 22 deletions(-) diff --git a/ChangeLog b/ChangeLog index dde01b8..c8ca431 100644 --- a/ChangeLog +++ b/ChangeLog @@ -3,6 +3,9 @@ * tests/resource.test: * mac/tclMacResource.c: fix to resource freeing problem in 'resource' command reported by Bernard Desgraupes. + + * doc/FileSystem.3: updated documentation for 'glob' fix on 2003-10-13 + below 2003-10-22 Donal K. Fellows diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index acfb093..4969721 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.35 2003/09/05 21:52:11 dgp Exp $ +'\" RCS: @(#) $Id: FileSystem.3,v 1.36 2003/10/23 10:10:31 vincentdarley Exp $ '\" .so man.macros .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures" @@ -163,10 +163,10 @@ file identified by \fBpathPtr\fR and to be evaluted. .AP "CONST char" *pattern in Only files or directories matching this pattern will be returned by \fBTcl_FSMatchInDirectory\fR. -.AP GlobTypeData *types in +.AP Tcl_GlobTypeData *types in Only files or directories matching the type descriptions contained in this structure will be returned by \fBTcl_FSMatchInDirectory\fR. It -is very important that the 'directory' flag is properly handled. +is very important that the 'directory' and 'mount' flags are properly handled. This parameter may be NULL. .AP Tcl_Interp *interp in Interpreter to use either for results, evaluation, or reporting error @@ -562,19 +562,22 @@ not require additional conversions. \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. A "translated" path is one which -contains no "~" or "~user" sequences (these have been expanded to -their current representation in the filesystem). This function is of -little practical use, and \fBTcl_FSGetNormalizedPath\fR or -\fBTcl_GetNativePath\fR are usually better functions to use for most -purposes. -.PP -\fBTcl_FSGetTranslatedStringPath\fR does the same as +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. A "translated" path is one which contains no +"~" or "~user" sequences (these have been expanded to their current +representation in the filesystem). The object returned is owned by the +caller, which must store it or call Tcl_DecrRefCount to ensure memory is +freed. This function is of little practical use, and +\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually +better functions to use for most purposes. +.PP +\fBTcl_FSGetTranslatedStringPath\fR does the same as \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL. -Again, \fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are -usually better functions to use for most purposes. +The string returned is dynamically allocated and owned by the caller, +which must store it or call ckfree to ensure it is freed. Again, +\fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are usually +better functions to use for most purposes. .PP \fBTcl_FSNewNativePath\fR performs something like that reverse of the usual obj->path->nativerep conversions. If some code retrieves a path @@ -1046,6 +1049,19 @@ to \fIresult\fR should include any path prefix given in \fIpathPtr\fR Note that if no matches are found, that simply leads to an empty result --- errors are only signaled for actual file or filesystem problems which may occur during the matching process. +.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 \fITCL_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 @@ -1312,13 +1328,16 @@ typedef int Tcl_FSLoadFileProc( .CE .PP Returns a standard Tcl completion code. If an error occurs, an error -message is left in the interp's result. The function dynamically loads -a binary code file into memory. On a successful -load, the \fIhandlePtr\fR should be filled with a token for -the dynamically loaded file, and the \fIunloadProcPtr\fR should be -filled in with the address of a procedure. The procedure will be -called with the given Tcl_LoadHandle as its only parameter when Tcl -needs to unload the file. +message is left in the interp's result. The function dynamically loads a +binary code file into memory. On a successful load, the \fIhandlePtr\fR +should be filled with a token for the dynamically loaded file, and the +\fIunloadProcPtr\fR should be filled in with the address of a procedure. +The unload procedure will be called with the given Tcl_LoadHandle as its +only parameter when Tcl needs to unload the file. For example, for the +native filesystem, the \fBTcl_LoadHandle\fR returned is currently a token +which can be used in the private \fBTclpFindSymbol\fR to access functions +in the new code. Each filesystem is free to define the +\fBTcl_LoadHandle\fR as it requires. .SH UNLOADFILEPROC .PP Function to unload a previously successfully loaded file. If load was -- cgit v0.12