summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorvincentdarley <vincentdarley>2003-10-23 10:10:11 (GMT)
committervincentdarley <vincentdarley>2003-10-23 10:10:11 (GMT)
commit03736c0062a33d49dd420b759927e54f7533510c (patch)
tree92fb1cb43d69bf0ce87a4a5ed8ca7afd158399d7 /doc
parent06f7470662af25ea53cefea3f2e731cbf6ce2eaf (diff)
downloadtcl-03736c0062a33d49dd420b759927e54f7533510c.zip
tcl-03736c0062a33d49dd420b759927e54f7533510c.tar.gz
tcl-03736c0062a33d49dd420b759927e54f7533510c.tar.bz2
filesystem documentation
Diffstat (limited to 'doc')
-rw-r--r--doc/FileSystem.363
1 files changed, 41 insertions, 22 deletions
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