filesystem.3

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

documented whether \fIpathPtr\fR will have a file separator at its end of
not, so code should be flexible to both possibilities.
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the matching process.  Error messages are placed in interp, 
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). 
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.
.SH UTIMEPROC       
.PP
Function to process a \fBTcl_FSUtime()\fR call.  Required to allow setting
(not reading) of times with 'file mtime', 'file atime' and the
open-r/open-w/fcopy implementation of 'file copy'.
.PP
.CS
typedef int Tcl_FSUtimeProc(
	Tcl_Obj *\fIpathPtr\fR, 
	struct utimbuf *\fItval\fR);
.CE
.PP
The access and modification times of the file specified by \fIpathPtr\fR
should be changed to the values given in the \fItval\fR structure.
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the process.
.SH LINKPROC 
.PP
Function to process a \fBTcl_FSLink()\fR call.  Should be implemented
only if the filesystem supports links, and may otherwise be NULL.
.PP
.CS
typedef Tcl_Obj* Tcl_FSLinkProc(
	Tcl_Obj *\fIlinkNamePtr\fR,
	Tcl_Obj *\fItoPtr\fR,
	int \fIlinkAction\fR);
.CE
.PP
If \fItoPtr\fR is NULL, the function is being asked to read the
contents of a link.  The result is a Tcl_Obj specifying the contents of
the 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 \fItoPtr\fR 
is not NULL, the function should attempt to create a link.  The result
in this case should be \fItoPtr\fR if the link was successful and NULL
otherwise.  In this case the result is not owned by the caller. See
the documentation for \fBTcl_FSLink\fR for the correct interpretation
of the \fIlinkAction\fR flags.
.SH LISTVOLUMESPROC	    
.PP
Function to list any filesystem volumes added by this filesystem.
Should be implemented only if the filesystem adds volumes at the head
of the filesystem, so that they can be returned by 'file volumes'.
.PP
.CS
typedef Tcl_Obj* Tcl_FSListVolumesProc(void);
.CE
.PP
The result should be a list of volumes added by this filesystem, or
NULL (or an empty list) if no volumes are provided.  The result object
is considered to be owned by the filesystem (not by Tcl's core), but
should be given a refCount for Tcl.  Tcl will use the contents of the
list and then decrement that refCount.  This allows filesystems to
choose whether they actually want to retain a 'master list' of volumes
or not (if not, they generate the list on the fly and pass it to Tcl
with a refCount of 1 and then forget about the list, if yes, then
they simply increment the refCount of their master list and pass it
to Tcl which will copy the contents and then decrement the count back
to where it was).
.PP
Therefore, Tcl considers return values from this proc to be read-only.
.PP
.SH FILEATTRSTRINGSPROC
.PP
Function to list all attribute strings which are valid for this
filesystem.  If not implemented the filesystem will not support
the \fBfile attributes\fR command.  This allows arbitrary additional
information to be attached to files in the filesystem.  If it is
not implemented, there is no need to implement the \fBget\fR and \fBset\fR
methods.
.PP
.CS
typedef CONST char** Tcl_FSFileAttrStringsProc(
	Tcl_Obj *\fIpathPtr\fR, 
	Tcl_Obj** \fIobjPtrRef\fR);
.CE
.PP
The called function 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.
.SH FILEATTRSGETPROC
.PP
Function to process a \fBTcl_FSFileAttrsGet()\fR call, used by 'file
attributes'.
.PP
.CS
typedef int Tcl_FSFileAttrsGetProc(
	Tcl_Interp *\fIinterp\fR,
	int \fIindex\fR, 
	Tcl_Obj *\fIpathPtr\fR,
	Tcl_Obj **\fIobjPtrRef\fR);
.CE
.PP
Returns a standard Tcl return code.  The attribute value retrieved,
which corresponds to the \fIindex\fR'th element in the list returned by
the Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if
TCL_OK was returned) and is likely to have a refCount of zero.  Either
way we must either store it somewhere (e.g. the Tcl result), or
Incr/Decr its refCount to ensure it is properly freed.
.SH FILEATTRSSETPROC
.PP
Function to process a \fBTcl_FSFileAttrsSet()\fR call, used by 'file
attributes'.  If the filesystem is read-only, there is no need
to implement this.
.PP
.CS
typedef int Tcl_FSFileAttrsSetProc(
	Tcl_Interp *\fIinterp\fR,
	int \fIindex\fR, 
	Tcl_Obj *\fIpathPtr\fR,
	Tcl_Obj *\fIobjPtr\fR);
.CE
.PP
The attribute value of the \fIindex\fR'th element in the list returned by
the Tcl_FSFileAttrStringsProc should be set to the \fIobjPtr\fR given.
.SH CREATEDIRECTORYPROC	    
.PP
Function to process a \fBTcl_FSCreateDirectory()\fR call.  Should be
implemented unless the FS is read-only.
.PP
.CS
typedef int Tcl_FSCreateDirectoryProc(
	Tcl_Obj *\fIpathPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the process.  If successful, a new directory should have
been added to the filesystem in the location specified by
\fIpathPtr\fR.
.SH REMOVEDIRECTORYPROC	    
.PP
Function to process a 'Tcl_FSRemoveDirectory()' call.  Should be
implemented unless the FS is read-only.
.PP
.CS
typedef int Tcl_FSRemoveDirectoryProc(
	Tcl_Obj *\fIpathPtr\fR,
	int \fIrecursive\fR, 
	Tcl_Obj **\fIerrorPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the process.  If successful, the directory specified by
\fIpathPtr\fR should have been removed from the filesystem.  If the
\fIrecursive\fR flag is given, then a non-empty directory should
be deleted without error.  If an error does occur, the name of
the file or directory which caused the error should be placed in
\fIerrorPtr\fR.
.SH DELETEFILEPROC	    
.PP
Function to process a \fBTcl_FSDeleteFile()\fR call.  Should be implemented
unless the FS is read-only.
.PP
.CS
typedef int Tcl_FSDeleteFileProc(
	Tcl_Obj *\fIpathPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the process.  If successful, the file specified by
\fIpathPtr\fR should have been removed from the filesystem.  Note that,
if the filesystem supports symbolic links, Tcl will always call this
function and not Tcl_FSRemoveDirectoryProc when needed to delete them
(even if they are symbolic links to directories).
.SH "FILESYSTEM EFFICIENCY"
.PP
.SH LSTATPROC	    
.PP
Function to process a \fBTcl_FSLstat()\fR call.  If not implemented, Tcl
will attempt to use the \fIstatProc\fR defined above instead.  Therefore
it need only be implemented if a filesystem can differentiate between
\fBstat\fR and \fBlstat\fR calls.
.PP
.CS
typedef int Tcl_FSLstatProc(
	Tcl_Obj *\fIpathPtr\fR, 
	Tcl_StatBuf *\fIstatPtr\fR);
.CE
.PP
The behavior of this function is very similar to that of the 
Tcl_FSStatProc defined above, except that if it is applied
to a symbolic link, it returns information about the link, not
about the target file.
.PP
.SH COPYFILEPROC 
.PP
Function to process a \fBTcl_FSCopyFile()\fR call.  If not implemented Tcl
will fall back on open-r, open-w and fcopy as a copying mechanism.
Therefore it need only be implemented if the filesystem can perform
that action more efficiently.
.PP
.CS
typedef int Tcl_FSCopyFileProc(
	Tcl_Obj *\fIsrcPathPtr\fR,
	Tcl_Obj *\fIdestPathPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the copying process.  Note that, \fIdestPathPtr\fR is the
name of the file which should become the copy of \fIsrcPathPtr\fR. It
is never the name of a directory into which \fIsrcPathPtr\fR could be
copied (i.e. the function is much simpler than the Tcl level 'file
copy' subcommand).  Note that,
if the filesystem supports symbolic links, Tcl will always call this
function and not Tcl_FSCopyDirectoryProc when needed to copy them
(even if they are symbolic links to directories).
.SH RENAMEFILEPROC	    
.PP
Function to process a \fBTcl_FSRenameFile()\fR call.  If not implemented,
Tcl will fall back on a copy and delete mechanism.  Therefore it need
only be implemented if the filesystem can perform that action more
efficiently.
.PP
.CS
typedef int Tcl_FSRenameFileProc(
	Tcl_Obj *\fIsrcPathPtr\fR,
	Tcl_Obj *\fIdestPathPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the renaming process.
.SH COPYDIRECTORYPROC	    
.PP
Function to process a \fBTcl_FSCopyDirectory()\fR call.  If not
implemented, Tcl will fall back on a recursive create-dir, file copy
mechanism.  Therefore it need only be implemented if the filesystem can
perform that action more efficiently.
.PP
.CS
typedef int Tcl_FSCopyDirectoryProc(
	Tcl_Obj *\fIsrcPathPtr\fR,
	Tcl_Obj *\fIdestPathPtr\fR, 
	Tcl_Obj **\fIerrorPtr\fR);
.CE
.PP
The return value is a standard Tcl result indicating whether an error
occurred in the copying process.  If an error does occur, the name of
the file or directory which caused the error should be placed in
\fIerrorPtr\fR. Note that, \fIdestPathPtr\fR is the name of the
directory-name which should become the mirror-image of
\fIsrcPathPtr\fR. It is not the name of a directory into which
\fIsrcPathPtr\fR should be copied (i.e. the function is much simpler
than the Tcl level 'file copy' subcommand).
.SH LOADFILEPROC 
.PP
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 it can be implemented simply to
return TCL_ERROR to disable load functionality in this filesystem
entirely.
.PP
.CS
typedef int Tcl_FSLoadFileProc(
	Tcl_Interp * \fIinterp\fR, 
	Tcl_Obj *\fIpathPtr\fR, 
	Tcl_LoadHandle * \fIhandlePtr\fR,
	Tcl_FSUnloadFileProc * \fIunloadProcPtr\fR);
.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.
.SH UNLOADFILEPROC	    
.PP
Function to unload a previously successfully loaded file.  If load was
implemented, then this should also be implemented, if there is any
cleanup action required.
.PP
.CS
typedef void Tcl_FSUnloadFileProc(
	Tcl_LoadHandle \fIloadHandle\fR);
.CE
.SH GETCWDPROC     
.PP
Function to process a \fBTcl_FSGetCwd()\fR call.  Most filesystems need not
implement this.  It will usually only be called once, if 'getcwd' is
called before 'chdir'.  May be NULL.
.PP
.CS
typedef Tcl_Obj* Tcl_FSGetCwdProc(
	Tcl_Interp *\fIinterp\fR);
.CE
.PP
If the filesystem supports a native notion of a current working
directory (which might perhaps change independent of Tcl), this
function should return that cwd as the result, or NULL if the current
directory could not be determined (e.g. the user does not have
appropriate permissions on the cwd directory).  If NULL is returned, an
error message is left in the interp's result.
.PP
.SH CHDIRPROC	    
.PP
Function to process a \fBTcl_FSChdir()\fR call.  If filesystems do not
implement this, it will be emulated by a series of directory access
checks.  Otherwise, virtual filesystems which do implement it need only
respond with a positive return result if the dirName is a valid,
accessible directory in their filesystem.  They need not remember the
result, since that will be automatically remembered for use by GetCwd.
Real filesystems should carry out the correct action (i.e. call the
correct system 'chdir' api).
.PP
.CS
typedef int Tcl_FSChdirProc(
	Tcl_Obj *\fIpathPtr\fR);
.CE
.PP
The \fBTcl_FSChdirProc\fR changes the applications current working
directory to the value specified in \fIpathPtr\fR. The function returns
-1 on error or 0 on success.
.SH KEYWORDS
stat access filesystem vfs