diff options
author | vincentdarley <vincentdarley@noemail.net> | 2003-10-23 10:10:11 (GMT) |
---|---|---|
committer | vincentdarley <vincentdarley@noemail.net> | 2003-10-23 10:10:11 (GMT) |
commit | b70ecdf38fef433c667ac5cdeadf3729855c1e2f (patch) | |
tree | 92fb1cb43d69bf0ce87a4a5ed8ca7afd158399d7 /doc | |
parent | 6022389b6e0ca7e8ac7db85c71cab6b19d63c1c6 (diff) | |
download | tcl-b70ecdf38fef433c667ac5cdeadf3729855c1e2f.zip tcl-b70ecdf38fef433c667ac5cdeadf3729855c1e2f.tar.gz tcl-b70ecdf38fef433c667ac5cdeadf3729855c1e2f.tar.bz2 |
filesystem documentation
FossilOrigin-Name: a4fc365a4e0d9f41503f35ba5fadb48072121b60
Diffstat (limited to 'doc')
-rw-r--r-- | doc/FileSystem.3 | 63 |
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 |