filesystem.3

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

'\"
'\" Copyright (c) 2001 Vincent Darley
'\"
'\" 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.32 2003/02/10 12:50:31 vincentdarley Exp $
'\" 
.so man.macros
.TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_AllocStatBuf \- procedures to interact with any filesystem
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_FSRegister\fR(\fIclientData, fsPtr\fR)
.sp
int
\fBTcl_FSUnregister\fR(\fIfsPtr\fR)
.sp
ClientData
\fBTcl_FSData\fR(\fIfsPtr\fR)
.sp
void
\fBTcl_FSMountsChanged\fR(\fIfsPtr\fR)
.sp
Tcl_Filesystem*
\fBTcl_FSGetFileSystemForPath\fR(\fIpathObjPtr\fR)
.sp
Tcl_PathType
\fBTcl_FSGetPathType\fR(\fIpathObjPtr\fR)
.sp
int
\fBTcl_FSCopyFile\fR(\fIsrcPathPtr, destPathPtr\fR)
.sp
int
\fBTcl_FSCopyDirectory\fR(\fIsrcPathPtr, destPathPtr, errorPtr\fR)
.sp
int
\fBTcl_FSCreateDirectory\fR(\fIpathPtr\fR)
.sp
int
\fBTcl_FSDeleteFile\fR(\fIpathPtr\fR)
.sp
int
\fBTcl_FSRemoveDirectory\fR(\fIpathPtr, int recursive, errorPtr\fR)
.sp
int
\fBTcl_FSRenameFile\fR(\fIsrcPathPtr, destPathPtr\fR)
.sp
Tcl_Obj*
\fBTcl_FSListVolumes\fR(\fIvoid\fR)
.sp
int
\fBTcl_FSEvalFile\fR(\fIinterp, pathPtr\fR)
.sp
int
\fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr, handlePtr, unloadProcPtr\fR)
.sp
int
\fBTcl_FSMatchInDirectory\fR(\fIinterp, result, pathPtr, pattern, types\fR)
.sp
Tcl_Obj*
\fBTcl_FSLink\fR(\fIlinkNamePtr, toPtr, linkAction\fR)
.sp
int
\fBTcl_FSLstat\fR(\fIpathPtr, statPtr\fR)
.sp
int
\fBTcl_FSUtime\fR(\fIpathPtr, tval\fR)
.sp
int
\fBTcl_FSFileAttrsGet\fR(\fIinterp, int index, pathPtr, objPtrRef\fR)
.sp
int
\fBTcl_FSFileAttrsSet\fR(\fIinterp, int index, pathPtr, Tcl_Obj *objPtr\fR)
.sp
CONST char**      
\fBTcl_FSFileAttrStrings\fR(\fIpathPtr, objPtrRef\fR)
.sp
int
\fBTcl_FSStat\fR(\fIpathPtr, statPtr\fR)
.sp
int
\fBTcl_FSAccess\fR(\fIpathPtr, mode\fR)
.sp
Tcl_Channel 
\fBTcl_FSOpenFileChannel\fR(\fIinterp, pathPtr, modeString, permissions\fR)
.sp
Tcl_Obj*
\fBTcl_FSGetCwd\fR(\fIinterp\fR)
.sp
int
\fBTcl_FSChdir\fR(\fIpathPtr\fR)
.sp
Tcl_Obj*
\fBTcl_FSPathSeparator\fR(\fIpathPtr\fR)
.sp
Tcl_Obj*
\fBTcl_FSJoinPath\fR(\fIlistObj, elements\fR)
.sp
Tcl_Obj*
\fBTcl_FSSplitPath\fR(\fIpathPtr, lenPtr\fR)
.sp
int
\fBTcl_FSEqualPaths\fR(\fIfirstPtr, secondPtr\fR)
.sp
Tcl_Obj*
\fBTcl_FSGetNormalizedPath\fR(\fIinterp, pathPtr\fR)
.sp
Tcl_Obj*
\fBTcl_FSJoinToPath\fR(\fIbasePtr, objc, objv\fR)
.sp
int
\fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR)
.sp
ClientData 
\fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR)
.sp
Tcl_Obj* 
\fBTcl_FSGetTranslatedPath\fR(\fIinterp, pathPtr\fR)
.sp
CONST char* 
\fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR)
.sp
Tcl_Obj*
\fBTcl_FSNewNativePath\fR(\fIfsPtr, clientData\fR)
.sp
CONST char* 
\fBTcl_FSGetNativePath\fR(\fIpathPtr\fR)
.sp
Tcl_Obj*
\fBTcl_FSFileSystemInfo\fR(\fIpathPtr\fR)
.sp
Tcl_StatBuf*
\fBTcl_AllocStatBuf\fR()
.SH ARGUMENTS
.AS Tcl_Filesystem *fsPtr in
.AP Tcl_Filesystem *fsPtr in
Points to a structure containing the addresses of procedures that
can be called to perform the various filesystem operations.
.AP Tcl_Obj *pathPtr in
The path represented by this object is used for the operation in
question.  If the object does not already have an internal \fBpath\fR
representation, it will be converted to have one.
.AP Tcl_Obj *srcPathPtr in
As for \fBpathPtr\fR, but used for the source file for a copy or
rename operation.
.AP Tcl_Obj *destPathPtr in
As for \fBpathPtr\fR, but used for the destination filename for a copy or
rename operation.
.AP "CONST char" *pattern in
Only files or directories matching this pattern will be returned by
\fBTcl_FSMatchInDirectory\fR.
.AP 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.
This parameter may be NULL.
.AP Tcl_Interp *interp in
Interpreter to use either for results, evaluation, or reporting error 
messages.
.AP ClientData clientData in
The native description of the path object to create.
.AP Tcl_Obj *firstPtr in
The first of two path objects to compare.  The object may be converted
to \fBpath\fR type.
.AP Tcl_Obj *secondPtr in
The second of two path objects to compare.  The object may be converted
to \fBpath\fR type.
.AP Tcl_Obj *listObj in
The list of path elements to operate on with a \fBjoin\fR operation.
.AP int elements in
If non-negative, the number of elements in the listObj which should
be joined together.  If negative, then all elements are joined.
.AP Tcl_Obj **errorPtr out
In the case of an error, filled with an object containing the name of
the file which caused an error in the various copy/rename operations.
.AP Tcl_Obj **objPtrRef out
Filled with an object containing the result of the operation.
.AP Tcl_Obj *result out
Pre-allocated object in which to store (by lappending) the list of
files or directories which are successfully matched in
\fBTcl_FSMatchInDirectory\fR.
.AP int mode in
Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.  R_OK,
W_OK and X_OK request checking whether the file exists and  has  read,
write and  execute  permissions, respectively.  F_OK just requests
checking for the existence of the file.
.AP Tcl_StatBuf *statPtr out
The structure that contains the result of a stat or lstat operation.
.AP "CONST char" *sym1 in
Name of a procedure to look up in the file's symbol table
.AP "CONST char" *sym2 in
Name of a procedure to look up in the file's symbol table
.AP Tcl_PackageInitProc **proc1Ptr out
Filled with the init function for this code.
.AP Tcl_PackageInitProc **proc2Ptr out
Filled with the safe-init function for this code.
.AP ClientData *clientDataPtr out
Filled with the clientData value to pass to this code's unload
function when it is called.
.AP TclfsUnloadFileProc_ **unloadProcPtr out
Filled with the function to use to unload this piece of code.
.AP utimbuf *tval in
The access and modification times in this structure are read and 
used to set those values for a given file.
.AP "CONST char" *modeString in
Specifies how the file is to be accessed.  May have any of the values
allowed for the \fImode\fR argument to the Tcl \fBopen\fR command.
.AP int permissions in
POSIX-style permission flags such as 0644.  If a new file is created, these
permissions will be set on the created file.
.AP int *lenPtr out
If non-NULL, filled with the number of elements in the split path.
.AP Tcl_Obj *basePtr in
The base path on to which to join the given elements.  May be NULL.
.AP int objc in
The number of elements in \fIobjv\fR.
.AP "Tcl_Obj *CONST" objv[] in
The elements to join to the given base path.
.BE

.SH DESCRIPTION
.PP
There are several reasons for calling the \fBTcl_FS...\fR functions
rather than calling system level functions like \fBaccess\fR and
\fBstat\fR directly.  First, they will work cross-platform, so an
extension which calls them should work unmodified on Unix, MacOS and
Windows.  Second, the Windows implementation of some of these functions
fixes some bugs in the system level calls.  Third, these function calls
deal with any 'Utf to platform-native' path conversions which may be
required (and may cache the results of such conversions for greater
efficiency on subsequent calls).  Fourth, and perhaps most importantly,
all of these functions are 'virtual filesystem aware'.  Any virtual
filesystem which has been registered (through
\fBTcl_FSRegister\fR) may reroute file access to alternative
media or access methods.  This means that all of these functions (and
therefore the corresponding \fBfile\fR, \fBglob\fR, \fBpwd\fR, \fBcd\fR,
\fBopen\fR, etc.  Tcl commands) may be operate on 'files' which are not
native files in the native filesystem.  This also means that any Tcl
extension which accesses the filesystem through this API is
automatically 'virtual filesystem aware'.  Of course, if an extension
accesses the native filesystem directly (through platform-specific
APIs, for example), then Tcl cannot intercept such calls.  
.PP
If appropriate vfs's have been registered, the 'files' may, to give two
examples, be remote (e.g. situated on a remote ftp server) or archived
(e.g. lying inside a .zip archive).  Such registered filesystems provide
a lookup table of functions to implement all or some of the functionality
listed here.  Finally, the \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR calls
abstract away from what the 'struct stat' buffer buffer is actually
declared to be, allowing the same code to be used both on systems with
and systems without support for files larger than 2GB in size.
.PP
The \fBTcl_FS...\fR are objectified and may cache internal
representations and other path-related strings (e.g. the current working
directory).  One side-effect of this is that one must not pass in objects
with a refCount of zero to any of these functions.  If such calls were 
handled, they might result
in memory leaks (under some circumstances, the filesystem code may wish
to retain a reference to the passed in object, and so one must not assume
that after any of these calls return, the object still has a refCount of
zero - it may have been incremented), or in a direct segfault
due to the object being freed part way through the complex object
manipulation required to ensure that the path is fully normalized and
absolute for filesystem determination.  The practical lesson to learn
from this is that \fBTcl_Obj *path = Tcl_NewStringObj(...)  ;
Tcl_FS...(path) ; Tcl_DecrRefCount(path)\fR is wrong, and may segfault.
The 'path' must have its refCount incremented before passing it in, or
decrementing it.  For this reason, objects with a refCount of zero are
considered not to be valid filesystem paths and calling any Tcl_FS API
with such an object will result in no action being taken.
.PP
\fBTcl_FSCopyFile\fR attempts to copy the file given by srcPathPtr to the
path name given by destPathPtr.  If the two paths given lie in the same
filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
filesystem's 'copy file' function is called (if it is non-NULL).
Otherwise the function returns -1 and sets Tcl's errno to the 'EXDEV'
posix error code (which signifies a 'cross-domain link').
.PP
\fBTcl_FSCopyDirectory\fR attempts to copy the directory given by srcPathPtr to the
path name given by destPathPtr.  If the two paths given lie in the same
filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that
filesystem's 'copy file' function is called (if it is non-NULL).
Otherwise the function returns -1 and sets Tcl's errno to the 'EXDEV'
posix error code (which signifies a 'cross-domain link').
.PP
\fBTcl_FSCreateDirectory\fR attempts to create the directory given by
pathPtr by calling the owning filesystem's 'create directory'
function.
.PP
\fBTcl_FSDeleteFile\fR attempts to delete the file given by
pathPtr by calling the owning filesystem's 'delete file'
function.
.PP
\fBTcl_FSRemoveDirectory\fR attempts to remove the directory given by
pathPtr by calling the owning filesystem's 'remove directory'
function.
.PP
\fBTcl_FSRenameFile\fR attempts to rename the file or directory given by
srcPathPtr to the path name given by destPathPtr.  If the two paths
given lie in the same filesystem (according to
\fBTcl_FSGetFileSystemForPath\fR) then that filesystem's 'rename file'
function is called (if it is non-NULL).  Otherwise the function returns -1
and sets Tcl's errno to the 'EXDEV' posix error code (which signifies
a ``cross-domain link'').
.PP
\fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL 'list
volumes' function and asks them to return their list of root volumes.  It
accumulates the return values in a list which is returned to the
caller (with a refCount of 0).
.PP
\fBTcl_FSEvalFile\fR reads the file given by \fIpathPtr\fR and evaluates
its contents as a Tcl script.  It returns the same information as
\fBTcl_EvalObjEx\fR.
If the file couldn't be read then a Tcl error is returned to describe
why the file couldn't be read.
The eofchar for files is '\\32' (^Z) for all platforms.
If you require a ``^Z'' in code for string comparison, you can use
``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
interpreter into ``^Z''.
.PP
\fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
returns the addresses of two procedures within that file, if they are
defined.  The appropriate function for the filesystem to which pathPtr
belongs will be called.  If that filesystem does not implement this
function (most virtual filesystems will not, because of OS limitations
in dynamically loading binary code), Tcl will attempt to copy the file
to a temporary directory and load that temporary file.
.PP
Returns a standard Tcl completion code.  If an error occurs, an error
message is left in the interp's result.
.PP
\fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a