diff options
Diffstat (limited to 'doc/FileSystem.3')
| -rw-r--r-- | doc/FileSystem.3 | 108 |
1 files changed, 94 insertions, 14 deletions
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 index cbfa25b..d504b64 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.19 2002/02/15 14:28:47 dkf Exp $ +'\" RCS: @(#) $Id: FileSystem.3,v 1.20 2002/03/24 11:41:48 vincentdarley Exp $ '\" .so man.macros .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures" @@ -495,7 +495,11 @@ string value can be used as a unique identifier for the file. .PP It returns the normalized path object, with refCount of zero, or NULL if the path was invalid or could otherwise not be successfully -converted. +converted. Extraction of absolute, normalized paths is very +efficient (because the filesystem operates on these representations +internally), although the result when the filesystem contains +numerous symbolic links may not be the most user-friendly +version of a path. .PP \fBTcl_FSJoinToPath\fR takes the given object, which should usually be a valid path or NULL, and joins onto it the array of paths segments @@ -518,7 +522,7 @@ be left in the interpreter. path object, in the given filesystem. If the path object belongs to a different filesystem, we return NULL. If the internal representation is currently NULL, we attempt to generate it, by calling the filesystem's -\fBTclfsConvertToInternalProc_\fR. +\fBTcl_FSCreateInternalRepProc\fR. .PP Returns NULL or a valid internal path representation. This internal representation is cached, so that repeated calls to this function will @@ -529,12 +533,14 @@ 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. +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). .PP \fBTcl_FSGetTranslatedStringPath\fR does the same as \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL. .PP -\fBTcl_FSNewNativePath\fR performs the something like that reverse of the +\fBTcl_FSNewNativePath\fR performs something like that reverse of the usual obj->path->nativerep conversions. If some code retrieves a path in native form (from, e.g. readlink or a native dialog), and that path is to be used at the Tcl level, then calling this function is an @@ -545,7 +551,15 @@ a Utf-8 string representation if that is required by some Tcl code. .PP \fBTcl_FSGetNativePath\fR is for use by the Win/Unix/MacOS native filesystems, so that they can easily retrieve the native (char* or -TCHAR*) representation of a path. +TCHAR*) representation of a path. This function is a convenience +wrapper around \fBTcl_FSGetInternalRep\fR, and assumes the native +representation is string-based. It may be desirable in the future +to have non-string-based native representations (for example, on +MacOS, a representation using a fileSpec of FSRef structure would +probably be more efficient). On Windows a full Unicode +representation would allow for paths of unlimited length. Currently +the representation is simply a character string containing the +complete, absolute path in the native encoding. .PP The native representation is cached so that repeated calls to this function will not require additional conversions. @@ -666,10 +680,62 @@ functions (it will use \fITcl_FSCopyFileProc\fR followed by \fITcl_FSDeleteFileProc\fR, and if \fITcl_FSCopyFileProc\fR is not implemented there is a further fallback). However, if a \fITcl_FSRenameFile\fR command is issued at the C level, no such -fallbacks occur. This is true except for the last five entries in the -filesystem table (lstat, load, unload, getcwd and chdir) +fallbacks occur. This is true except for the last four entries in the +filesystem table (lstat, load, getcwd and chdir) for which fallbacks do in fact occur at the C level. .PP +As an example, here is the filesystem lookup table used by the +"vfs" extension which allows filesystem actions to be implemented +in Tcl. +.CS +static Tcl_Filesystem vfsFilesystem = { + "tclvfs", + sizeof(Tcl_Filesystem), + TCL_FILESYSTEM_VERSION_1, + &VfsPathInFilesystem, + &VfsDupInternalRep, + &VfsFreeInternalRep, + /* No internal to normalized, since we don't create any + * pure 'internal' Tcl_Obj path representations */ + NULL, + /* No create native rep function, since we don't use it + * and don't choose to support uses of 'Tcl_FSNewNativePath' */ + NULL, + /* Normalize path isn't needed - we assume paths only have + * one representation */ + NULL, + &VfsFilesystemPathType, + &VfsFilesystemSeparator, + &VfsStat, + &VfsAccess, + &VfsOpenFileChannel, + &VfsMatchInDirectory, + &VfsUtime, + /* We choose not to support symbolic links inside our vfs's */ + NULL, + &VfsListVolumes, + &VfsFileAttrStrings, + &VfsFileAttrsGet, + &VfsFileAttrsSet, + &VfsCreateDirectory, + &VfsRemoveDirectory, + &VfsDeleteFile, + /* No copy file - fallback will occur at Tcl level */ + NULL, + /* No rename file - fallback will occur at Tcl level */ + NULL, + /* No copy directory - fallback will occur at Tcl level */ + NULL, + /* Core will use stat for lstat */ + NULL, + /* No load - fallback on core implementation */ + NULL, + /* We don't need a getcwd or chdir - fallback on Tcl's versions */ + NULL, + NULL +}; +.CE +.PP Any functions which take path names in Tcl_Obj form take those names in UTF\-8 form. The filesystem infrastructure API is designed to support efficient, cached conversion of these UTF\-8 paths @@ -768,7 +834,13 @@ string representation. Depending on the filesystem, there may be more than one unnormalized string representation which refers to that path (e.g. a relative path, a path with different character case if the filesystem is case insensitive, a path contain a -reference to a home directory such as '~', etc). +reference to a home directory such as '~', a path containing symbolic +links, etc). If the very last component in the path is a symbolic +link, it should not be converted into the object it points to (but +its case or other aspects should be made unique). All other path +components should be converted from symbolic links. This one +exception is required to agree with Tcl's semantics with 'file +delete', 'file rename', 'file copy' operating on symbolic links. .PP .CS typedef int Tcl_FSNormalizePathProc( @@ -909,9 +981,13 @@ typedef int Tcl_FSMatchInDirectoryProc( .PP The function should return all files or directories (or other filesystem objects) which match the given pattern and accord with the -\fItypes\fR specification given. The directory \fIpathPtr\fR, in which -the function should search, can be assumed to be both non-NULL and -non-empty. +\fItypes\fR specification given. There are two ways in which this +function may be called. If \fIpattern\fR is NULL, then \fIpathPtr\fR +is a full path specification of a single file or directory which +should be checked for existence and correct type. Otherwise, \fIpathPtr\fR +is a directory, the contents of which the function should search for +files or directories which have the correct type. In either case, +\fIpathPtr\fR can be assumed to be both non-NULL and non-empty. .PP The return value is a standard Tcl result indicating whether an error occurred in the matching process. Error messages are placed in interp, @@ -919,7 +995,10 @@ 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 to \fIresult\fR should include any path prefix given in \fIpathPtr\fR -(this usually means they will be absolute path specifications). +(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 signalled for actual file or filesystem +problems which may occur during the matching process. .SH UTIMEPROC .PP Function to process a \fBTcl_FSUtime()\fR call. Required to allow setting @@ -1164,7 +1243,8 @@ than the Tcl level 'file copy' subcommand). Function to process a \fBTcl_FSLoadFile()\fR call. If not implemented, Tcl will fall back on a copy to native-temp followed by a Tcl_FSLoadFile on that temporary copy. Therefore it need only be implemented if the -filesystem can load code directly, or to disable load functionality +filesystem can load code directly, or it can be implemented simply to +return TCL_ERROR to disable load functionality in this filesystem entirely. .PP .CS |