filesystem.3

来自「tcl是工具命令语言」· 3 代码 · 共 1,350 行 · 第 1/4 页

Except for the first three fields in this structure which contain
simple data elements, all entries contain addresses of functions called
by the generic filesystem layer to perform the complete range of
filesystem related actions.
.PP
The many functions in this structure are broken down into three
categories: infrastructure functions (almost all of which must be
implemented), operational functions (which must be implemented if a
complete filesystem is provided), and efficiency functions (which need
only be implemented if they can be done so efficiently, or if they have
side-effects which are required by the filesystem; Tcl has less
efficient emulations it can fall back on).  It is important to note
that, in the current version of Tcl, most of these fallbacks are only
used to handle commands initiated in Tcl, not in C. What this means is,
that if a 'file rename' command is issued in Tcl, and the relevant
filesystem(s) do not implement their \fITcl_FSRenameFileProc\fR, Tcl's
core will instead fallback on a combination of other filesystem
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 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
to other native representations.
.SH TYPENAME
.PP
The \fItypeName\fR field contains a null-terminated string that
identifies the type of the filesystem implemented, e.g.
\fBnative\fR or \fBzip\fR or \fBvfs\fR.
.PP
.SH "STRUCTURE LENGTH"
.PP
The \fIstructureLength\fR field is generally implemented as
\fIsizeof(Tcl_Filesystem)\fR, and is there to allow easier
binary backwards compatibility if the size of the structure
changes in a future Tcl release.
.SH VERSION
.PP
The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR.
.SH "FILESYSTEM INFRASTRUCTURE"
.PP
These fields contain addresses of functions which are used to associate
a particular filesystem with a file path, and deal with the internal
handling of path representations, for example copying and freeing such
representations.
.SH PATHINFILESYSTEMPROC
.PP
The \fIpathInFilesystemProc\fR field contains the address of a function
which is called to determine whether a given path object belongs to
this filesystem or not.  Tcl will only call the rest of the filesystem
functions with a path for which this function has returned
\fBTCL_OK\fR. If the path does not belong, \fBTCL_ERROR\fR should be
returned.  If \fBTCL_OK\fR is returned, then the optional
\fBclientDataPtr\fR output parameter can be used to return an internal
(filesystem specific) representation of the path, which will be cached
inside the path object, and may be retrieved efficiently by the other
filesystem functions.  Tcl will simultaneously cache the fact that this
path belongs to this filesystem.  Such caches are invalidated when
filesystem structures are added or removed from Tcl's internal list of
known filesystems.
.PP
.CS
typedef int Tcl_FSPathInFilesystemProc(
	Tcl_Obj *\fIpathPtr\fR, 
	ClientData *\fIclientDataPtr\fR);
.CE
.SH DUPINTERNALREPPROC
.PP
This function makes a copy of a path's internal representation, and is
called when Tcl needs to duplicate a path object.  If NULL, Tcl will
simply not copy the internal representation, which may then need to be
regenerated later.
.PP
.CS
typedef ClientData Tcl_FSDupInternalRepProc(
	ClientData \fIclientData\fR);
.CE
.SH FREEINTERNALREPPROC
Free the internal representation.  This must be implemented if internal
representations need freeing (i.e. if some memory is allocated when an
internal representation is generated), but may otherwise be NULL.
.PP
.CS
typedef void Tcl_FSFreeInternalRepProc(
	ClientData \fIclientData\fR);
.CE
.SH INTERNALTONORMALIZEDPROC
.PP
Function to convert internal representation to a normalized path.  Only
required if the filesystem creates pure path objects with no string/path
representation.  The return value is a Tcl object whose string
representation is the normalized path.
.PP
.CS
typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
	ClientData \fIclientData\fR);
.CE
.SH CREATEINTERNALREPPROC
.PP
Function to take a path object, and calculate an internal
representation for it, and store that native representation in the
object.  May be NULL if paths have no internal representation, or if
the \fITcl_FSPathInFilesystemProc\fR for this filesystem always
immediately creates an internal representation for paths it accepts.
.PP
.CS
typedef ClientData Tcl_FSCreateInternalRepProc(
	Tcl_Obj *\fIpathPtr\fR);
.CE
.SH NORMALIZEPATHPROC       
.PP
Function to normalize a path.  Should be implemented for all
filesystems which can have multiple string representations for the same
path object.  In Tcl, every 'path' must have a single unique 'normalized'
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 '~', 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.
This function may be called with 'nextCheckpoint' either
at the beginning of the path (i.e. zero), at the end of the path, or
at any intermediate file separator in the path.  It will never
point to any other arbitrary position in the path. In the last of
the three valid cases, the implementation can assume that the path 
up to and including the file separator is known and normalized.
.PP
.CS
typedef int Tcl_FSNormalizePathProc(
	Tcl_Interp *\fIinterp\fR, 
	Tcl_Obj *\fIpathPtr\fR, 
	int \fInextCheckpoint\fR);
.CE
.SH "FILESYSTEM OPERATIONS"
.PP
The fields in this section of the structure contain addresses of
functions which are called to carry out the basic filesystem
operations.  A filesystem which expects to be used with the complete
standard Tcl command set must implement all of these.  If some of
them are not implemented, then certain Tcl commands may fail when
operating on paths within that filesystem.  However, in some instances
this may be desirable (for example, a read-only filesystem should not
implement the last four functions, and a filesystem which does not
support symbolic links need not implement the \fBreadlink\fR function,
etc.  The Tcl core expects filesystems to behave in this way).
.SH FILESYSTEMPATHTYPEPROC
.PP
Function to determine the type of a path in this filesystem.  May be
NULL, in which case no type information will be available to users of
the filesystem.  The 'type' is used only for informational purposes,
and should be returned as the string representation of the Tcl_Obj
which is returned.  A typical return value might be "networked", "zip"
or "ftp".  The Tcl_Obj result is owned by the filesystem and so Tcl will 
increment the refCount of that object if it wishes to retain a reference 
to it.
.PP
.CS
typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc(
	Tcl_Obj *\fIpathPtr\fR);
.CE
.SH FILESYSTEMSEPARATORPROC
.PP
Function to return the separator character(s) for this filesystem.
Must be implemented, otherwise the \fBfile separator\fR command will not
function correctly.  The usual return value will be a Tcl_Obj
containing the string "/".
.PP
.CS
typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
	Tcl_Obj *\fIpathPtr\fR);
.CE
.SH STATPROC 
.PP
Function to process a \fBTcl_FSStat()\fR call.  Must be implemented for any
reasonable filesystem, since many Tcl level commands depend crucially 
upon it (e.g. \fBfile atime\fR, \fBfile isdirectory\fR, \fBfile size\fR,
\fBglob\fR).
.PP
.CS
typedef int Tcl_FSStatProc(
	Tcl_Obj *\fIpathPtr\fR,
	Tcl_StatBuf *\fIstatPtr\fR);
.CE
.PP
The \fBTcl_FSStatProc\fR fills the stat structure \fIstatPtr\fR with
information about the specified file.  You do not need any access
rights to the file to get this information but you need search rights
to all directories named in the path leading to the file.  The stat
structure includes info regarding device, inode (always 0 on Windows),
privilege mode, nlink (always 1 on Windows), user id (always 0 on
Windows), group id (always 0 on Windows), rdev (same as device on
Windows), size, last access time, last modification time, and creation
time.
.PP
If the file represented by \fIpathPtr\fR exists, the
\fBTcl_FSStatProc\fR returns 0 and the stat structure is filled with
data.  Otherwise, -1 is returned, and no stat info is given.
.SH ACCESSPROC	    
.PP
Function to process a \fBTcl_FSAccess()\fR call.  Must be implemented for
any reasonable filesystem, since many Tcl level commands depend crucially 
upon it (e.g. \fBfile exists\fR, \fBfile readable\fR).
.PP
.CS
typedef int Tcl_FSAccessProc(
	Tcl_Obj *\fIpathPtr\fR,
	int \fImode\fR);
.CE
.PP
The \fBTcl_FSAccessProc\fR checks whether the process would be allowed
to read, write or test for existence of the file (or other file system
object) whose name is pathname.  If pathname is a symbolic link, then
permissions of the file referred by this symbolic link should be tested.
.PP
On success (all requested permissions granted), zero is returned.  On
error (at least one bit in mode asked for a permission that is denied,
or some other  error occurred), -1 is returned.
.PP
.SH OPENFILECHANNELPROC 
.PP
Function to process a \fBTcl_FSOpenFileChannel()\fR call.  Must be
implemented for any reasonable filesystem, since any operations
which require open or accessing a file's contents will use it 
(e.g. \fBopen\fR, \fBencoding\fR, and many Tk commands).
.PP
.CS
typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
	Tcl_Interp *\fIinterp\fR,
	Tcl_Obj *\fIpathPtr\fR,
	int \fImode\fR,
	int \fIpermissions\fR);
.CE
.PP
The \fBTcl_FSOpenFileChannelProc\fR opens a file specified by
\fIpathPtr\fR and returns a channel handle that can be used to perform
input and output on the file.  This API is modeled after the \fBfopen\fR
procedure of the Unix standard I/O library.  The syntax and meaning of
all arguments is similar to those given in the Tcl \fBopen\fR command
when opening a file, where the \fImode\fR argument is a combination of
the POSIX flags O_RDONLY, O_WRONLY, etc.  If an error occurs while
opening the channel, the \fBTcl_FSOpenFileChannelProc\fR returns NULL and
records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
In addition, if \fIinterp\fR is non-NULL, the
\fBTcl_FSOpenFileChannelProc\fR leaves an error message in \fIinterp\fR's
result after any error.
.PP
The newly created channel is not registered in the supplied
interpreter; to register it, use \fBTcl_RegisterChannel\fR. If one of
the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
previously closed, the act of creating the new channel also assigns it
as a replacement for the standard channel.
.SH MATCHINDIRECTORYPROC  
.PP
Function to process a \fBTcl_FSMatchInDirectory()\fR call.  If not
implemented, then glob and recursive copy functionality will be lacking
in the filesystem (and this may impact commands like 'encoding names' 
which use glob functionality internally).
.PP
.CS
typedef int Tcl_FSMatchInDirectoryProc(
	Tcl_Interp* \fIinterp\fR, 
	Tcl_Obj *\fIresult\fR,
	Tcl_Obj *\fIpathPtr\fR, 
	CONST char *\fIpattern\fR, 
	Tcl_GlobTypeData * \fItypes\fR);
.CE
.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.  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.  It is not currently