filesystem.3

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

directory for all files which match a given pattern.  The appropriate
function for the filesystem to which pathPtr belongs will be called.
.PP
The return value is a standard Tcl result indicating whether an error
occurred in globbing.  Error messages are placed in interp, but good
results are placed in the resultPtr given.
 	
Note that the 'glob' code implements recursive patterns internally, so
this function will only ever be passed simple patterns, which can be
matched using the logic of 'string match'.  To handle recursion, Tcl
will call this function frequently asking only for directories to be
returned.
.PP
\fBTcl_FSLink\fR replaces the library version of readlink(), and
extends it to support the creation of links.  The appropriate function 
for the filesystem to which linkNamePtr belongs will be called.
.PP
If the \fItoPtr\fR is NULL, a readlink action is performed.  The result
is a Tcl_Obj specifying the contents of the symbolic link given by
\fIlinkNamePtr\fR, or NULL if the link could not be read.  The result is owned
by the caller, which should call Tcl_DecrRefCount when the result is no
longer needed.  If the \fItoPtr\fR is not NULL, Tcl should create a link
of one of the types passed in in the \fIlinkAction\fR flag.  This flag is
an or'd combination of TCL_CREATE_SYMBOLIC_LINK and TCL_CREATE_HARD_LINK.
Where a choice exists (i.e. more than one flag is passed in), the Tcl
convention is to prefer symbolic links.  When a link is successfully
created, the return value should be \fItoPtr\fR (which is therefore
already owned by the caller).  If unsuccessful, NULL should be
returned.
.PP
\fBTcl_FSLstat\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 \fIpath\fR exists, \fBTcl_FSLstat\fR returns 0 and the stat structure
is filled with data.  Otherwise, -1 is returned, and no stat info is
given.
.PP
\fBTcl_FSUtime\fR replaces the library version of utime.  
.PP
For results see 'utime' documentation.  If successful, the function
will update the 'atime' and 'mtime' values of the file given.
.PP
\fBTcl_FSFileAttrsGet\fR implements read access for the hookable 'file
attributes' subcommand.  The appropriate function for the filesystem to
which pathPtr belongs will be called.
.PP
If the result is TCL_OK, then an object was placed in objPtrRef, which
will only be temporarily valid (unless Tcl_IncrRefCount is called).
.PP
\fBTcl_FSFileAttrsSet\fR implements write access for the hookable 'file
attributes' subcommand.  The appropriate function for the filesystem to
which pathPtr belongs will be called.
.PP
\fBTcl_FSFileAttrStrings\fR implements part of the hookable 'file attributes'
subcommand.  The appropriate function for the filesystem to which
pathPtr belongs will be called.
.PP 
The called procedure may either return an array of strings, or may
instead return NULL and place a Tcl list into the given objPtrRef.  Tcl
will take that list and first increment its refCount before using it.
On completion of that use, Tcl will decrement its refCount.  Hence if
the list should be disposed of by Tcl when done, it should have a
refCount of zero, and if the list should not be disposed of, the
filesystem should ensure it retains a refCount on the object.
.PP
\fBTcl_FSAccess\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 on Unix,
then permissions of the file referred by this symbolic link are
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
\fBTcl_FSStat\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 \fIpath\fR exists, \fBTcl_FSStat\fR returns 0 and the stat structure
is filled with data.  Otherwise, -1 is returned, and no stat info is
given.
.PP
\fBTcl_FSOpenFileChannel\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.
If an error occurs while opening the channel, \fBTcl_FSOpenFileChannel\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, \fBTcl_FSOpenFileChannel\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, described below.
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.
.PP
\fBTcl_FSGetCwd\fR replaces the library version of getcwd().
.PP
It returns the Tcl library's current working directory.  This may be
different to the native platform's working directory, in the case for 
which the cwd is not in the native filesystem.
.PP
The result is a pointer to a Tcl_Obj specifying the current directory,
or NULL if the current directory could not be determined.  If NULL is
returned, an error message is left in the interp's result.
	
The result already has its refCount incremented for the caller.  When
it is no longer needed, that refCount should be decremented.  This is
needed for thread-safety purposes, to allow multiple threads to access
this and related functions, while ensuring the results are always
valid.
.PP
\fBTcl_FSChdir\fR replaces the library version of chdir().  The path is
normalized and then passed to the filesystem which claims it.  If that
filesystem does not implement this function, Tcl will fallback to a 
combination of stat and access to check whether the directory exists
and has appropriate permissions.
.PP 
For results, see chdir() documentation.  If successful, we keep a
record of the successful path in cwdPathPtr for subsequent calls to
getcwd.
.PP
\fBTcl_FSPathSeparator\fR returns the separator character to be used for 
most specific element of the path specified by pathPtr (i.e. the last 
part of the path).
.PP
The separator is returned as a Tcl_Obj containing a string of length
1.  If the path is invalid, NULL is returned.
.PP
\fBTcl_FSJoinPath\fR takes the given Tcl_Obj, which should be a valid list,
and returns the path object given by considering the first 'elements'
elements as valid path segments.  If elements < 0, we use the entire
list.
.PP
Returns object with refCount of zero, containing the joined path.
.PP
\fBTcl_FSSplitPath\fR takes the given Tcl_Obj, which should be a valid path,
and returns a Tcl List object containing each segment of that path as
an element.
.PP
Returns list object with refCount of zero.  If the passed in lenPtr is
non-NULL, we use it to return the number of elements in the returned
list.
.PP
\fBTcl_FSEqualPaths\fR tests whether the two paths given represent the same
filesystem object
.PP
It returns 1 if the paths are equal, and 0 if they are different.  If 
either path is NULL, 0 is always returned.
.PP
\fBTcl_FSGetNormalizedPath\fR this important function attempts to extract
from the given Tcl_Obj a unique normalized path representation, whose
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.  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
given.
.PP
Returns object with refCount of zero, containing the joined path.
.PP
\fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid
Tcl path type, taking account of the fact that the cwd may have changed
even if this object is already supposedly of the correct type.
The filename may begin with "~" (to indicate current user's home
directory) or "~<user>" (to indicate any user's home directory).
.PP
If the conversion succeeds (i.e. the object is a valid path in one of 
the current filesystems), then TCL_OK is returned.  Otherwise
TCL_ERROR is returned, and an error message may
be left in the interpreter.
.PP
\fBTcl_FSGetInternalRep\fR extracts the internal representation of a given
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
\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
not require additional conversions.
.PP
\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).
.PP
\fBTcl_FSGetTranslatedStringPath\fR does the same as 
\fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
.PP
\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
efficient way of creating the appropriate path object type.
.PP
The resulting object is a pure 'path' object, which will only receive 
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.  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.
.PP
\fBTcl_FSFileSystemInfo\fR returns a list of two elements.  The first
element is the name of the filesystem (e.g. "native" or "vfs" or "zip"
or "prowrap", perhaps), and the second is the particular type of the
given path within that filesystem (which is filesystem dependent).  The
second element may be empty if the filesystem does not provide a
further categorization of files.
.PP
A valid list object is returned, unless the path object is not
recognized, when NULL will be returned.
.PP
\fBTcl_FSGetFileSystemForPath\fR returns the a pointer to the
\fBTcl_Filesystem\fR which accepts this path as valid.
.PP
If no filesystem will accept the path, NULL is returned.
.PP
\fBTcl_FSGetPathType\fR determines whether the given path is relative 
to the current directory, relative to the current volume, or
absolute.
.PP
It returns one of TCL_PATH_ABSOLUTE, TCL_PATH_RELATIVE, or
TCL_PATH_VOLUME_RELATIVE
.PP
\fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system
heap (which may be deallocated by being passed to \fBckfree\fR.)  This
allows extensions to invoke \fBTcl_FSStat\fR and \fBTcl_FSLStat\fR
without being dependent on the size of the buffer.  That in turn
depends on the flags used to build Tcl.
.PP
.SH TCL_FILESYSTEM
.PP
A filesystem provides a \fBTcl_Filesystem\fR structure that contains
pointers to functions that implement the various operations on a
filesystem; these operations are invoked as needed by the generic
layer, which generally occurs through the functions listed above.  
.PP
The \fBTcl_Filesystem\fR structures are manipulated using the following
methods.
.PP
\fBTcl_FSRegister\fR takes a pointer to a filesystem structure and an
optional piece of data to associated with that filesystem.  On calling
this function, Tcl will attach the filesystem to the list of known
filesystems, and it will become fully functional immediately.  Tcl does
not check if the same filesystem is registered multiple times (and in
general that is not a good thing to do).  TCL_OK will be returned.
.PP
\fBTcl_FSUnregister\fR removes the given filesystem structure from
the list of known filesystems, if it is known, and returns TCL_OK.  If
the filesystem is not currently registered, TCL_ERROR is returned.
.PP
\fBTcl_FSData\fR will return the ClientData associated with the given 
filesystem, if that filesystem is registered.  Otherwise it will
return NULL.
.PP
\fBTcl_FSMountsChanged\fR is used to inform the Tcl's core that
the set of mount points for the given (already registered) filesystem
have changed, and that cached file representations may therefore no
longer be correct.
.PP
The \fBTcl_Filesystem\fR structure contains the following fields:
.CS
typedef struct Tcl_Filesystem {
    CONST char *\fItypeName\fR;  
    int \fIstructureLength\fR;   
    Tcl_FSVersion \fIversion\fR;  
    Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR;
    Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR;
    Tcl_FSFreeInternalRepProc *\fIfreeInternalRepProc\fR;
    Tcl_FSInternalToNormalizedProc *\fIinternalToNormalizedProc\fR;
    Tcl_FSCreateInternalRepProc *\fIcreateInternalRepProc\fR;
    Tcl_FSNormalizePathProc *\fInormalizePathProc\fR;       
    Tcl_FSFilesystemPathTypeProc *\fIfilesystemPathTypeProc\fR;
    Tcl_FSFilesystemSeparatorProc *\fIfilesystemSeparatorProc\fR;
    Tcl_FSStatProc *\fIstatProc\fR; 
    Tcl_FSAccessProc *\fIaccessProc\fR;	    
    Tcl_FSOpenFileChannelProc *\fIopenFileChannelProc\fR; 
    Tcl_FSMatchInDirectoryProc *\fImatchInDirectoryProc\fR;  
    Tcl_FSUtimeProc *\fIutimeProc\fR;       
    Tcl_FSLinkProc *\fIlinkProc\fR; 
    Tcl_FSListVolumesProc *\fIlistVolumesProc\fR;	    
    Tcl_FSFileAttrStringsProc *\fIfileAttrStringsProc\fR;
    Tcl_FSFileAttrsGetProc *\fIfileAttrsGetProc\fR;
    Tcl_FSFileAttrsSetProc *\fIfileAttrsSetProc\fR;
    Tcl_FSCreateDirectoryProc *\fIcreateDirectoryProc\fR;	    
    Tcl_FSRemoveDirectoryProc *\fIremoveDirectoryProc\fR;	    
    Tcl_FSDeleteFileProc *\fIdeleteFileProc\fR;	    
    Tcl_FSCopyFileProc *\fIcopyFileProc\fR; 
    Tcl_FSRenameFileProc *\fIrenameFileProc\fR;	    
    Tcl_FSCopyDirectoryProc *\fIcopyDirectoryProc\fR;	    
    Tcl_FSLstatProc *\fIlstatProc\fR;	    
    Tcl_FSLoadFileProc *\fIloadFileProc\fR; 
    Tcl_FSGetCwdProc *\fIgetCwdProc\fR;     
    Tcl_FSChdirProc *\fIchdirProc\fR;	    
} Tcl_Filesystem;
.CE
.PP