diff options
Diffstat (limited to 'tcl8.6/doc/FileSystem.3')
| -rw-r--r-- | tcl8.6/doc/FileSystem.3 | 1644 |
1 files changed, 0 insertions, 1644 deletions
diff --git a/tcl8.6/doc/FileSystem.3 b/tcl8.6/doc/FileSystem.3 deleted file mode 100644 index 28ee8f0..0000000 --- a/tcl8.6/doc/FileSystem.3 +++ /dev/null @@ -1,1644 +0,0 @@ -'\" -'\" Copyright (c) 2001 Vincent Darley -'\" Copyright (c) 2008-2010 Donal K. Fellows -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Filesystem 3 8.4 Tcl "Tcl Library Procedures" -.so man.macros -.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_FSEvalFileEx, Tcl_FSLoadFile, Tcl_FSUnloadFile, 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_GetAccessTimeFromStat, Tcl_GetBlockSizeFromStat, Tcl_GetBlocksFromStat, Tcl_GetChangeTimeFromStat, Tcl_GetDeviceTypeFromStat, Tcl_GetFSDeviceFromStat, Tcl_GetFSInodeFromStat, Tcl_GetGroupIdFromStat, Tcl_GetLinkCountFromStat, Tcl_GetModeFromStat, Tcl_GetModificationTimeFromStat, Tcl_GetSizeFromStat, Tcl_GetUserIdFromStat, 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 -const Tcl_Filesystem * -\fBTcl_FSGetFileSystemForPath\fR(\fIpathPtr\fR) -.sp -Tcl_PathType -\fBTcl_FSGetPathType\fR(\fIpathPtr\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_FSEvalFileEx\fR(\fIinterp, pathPtr, encodingName\fR) -.sp -int -\fBTcl_FSEvalFile\fR(\fIinterp, pathPtr\fR) -.sp -int -\fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr, - loadHandlePtr, unloadProcPtr\fR) -.sp -.VS 8.6 -int -\fBTcl_FSUnloadFile\fR(\fIinterp, loadHandle\fR) -.VE 8.6 -.sp -int -\fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, 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 *const * -\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 void * -\fBTcl_FSGetNativePath\fR(\fIpathPtr\fR) -.sp -Tcl_Obj * -\fBTcl_FSFileSystemInfo\fR(\fIpathPtr\fR) -.sp -Tcl_StatBuf * -\fBTcl_AllocStatBuf\fR() -.sp -.VS 8.6 -Tcl_WideInt -\fBTcl_GetAccessTimeFromStat\fR(\fIstatPtr\fR) -.sp -unsigned -\fBTcl_GetBlockSizeFromStat\fR(\fIstatPtr\fR) -.sp -Tcl_WideUInt -\fBTcl_GetBlocksFromStat\fR(\fIstatPtr\fR) -.sp -Tcl_WideInt -\fBTcl_GetChangeTimeFromStat\fR(\fIstatPtr\fR) -.sp -int -\fBTcl_GetDeviceTypeFromStat\fR(\fIstatPtr\fR) -.sp -unsigned -\fBTcl_GetFSDeviceFromStat\fR(\fIstatPtr\fR) -.sp -unsigned -\fBTcl_GetFSInodeFromStat\fR(\fIstatPtr\fR) -.sp -int -\fBTcl_GetGroupIdFromStat\fR(\fIstatPtr\fR) -.sp -int -\fBTcl_GetLinkCountFromStat\fR(\fIstatPtr\fR) -.sp -unsigned -\fBTcl_GetModeFromStat\fR(\fIstatPtr\fR) -.sp -Tcl_WideInt -\fBTcl_GetModificationTimeFromStat\fR(\fIstatPtr\fR) -.sp -Tcl_WideUInt -\fBTcl_GetSizeFromStat\fR(\fIstatPtr\fR) -.sp -int -\fBTcl_GetUserIdFromStat\fR(\fIstatPtr\fR) -.VE 8.6 -.SH ARGUMENTS -.AS Tcl_GlobTypeData **srcPathPtr out -.AP "const 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 value is used for the operation in -question. If the value does not already have an internal \fBpath\fR -representation, it will be converted to have one. -.AP Tcl_Obj *srcPathPtr in -As for \fIpathPtr\fR, but used for the source file for a copy or -rename operation. -.AP Tcl_Obj *destPathPtr in -As for \fIpathPtr\fR, but used for the destination filename for a copy or -rename operation. -.AP "const char" *encodingName in -The encoding of the data stored in the -file identified by \fIpathPtr\fR and to be evaluated. -.AP "const char" *pattern in -Only files or directories matching this pattern will be returned. -.AP Tcl_GlobTypeData *types in -Only files or directories matching the type descriptions contained in -this structure will be returned. 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 value to create. -.AP Tcl_Obj *firstPtr in -The first of two path values to compare. The value may be converted -to \fBpath\fR type. -.AP Tcl_Obj *secondPtr in -The second of two path values to compare. The value 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 \fIlistObj\fR 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 a value containing the name of -the file which caused an error in the various copy/rename operations. -.AP Tcl_Obj **objPtrRef out -Filled with a value containing the result of the operation. -.AP Tcl_Obj *resultPtr out -Pre-allocated value in which to store (using -\fBTcl_ListObjAppendElement\fR) the list of -files or directories which are successfully matched. -.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 Tcl_LoadHandle *loadHandlePtr out -Filled with an abstract token representing the loaded file. -.AP Tcl_FSUnloadFileProc **unloadProcPtr out -Filled with the function to use to unload this piece of code. -.AP Tcl_LoadHandle loadHandle in -Handle to the loaded library to be unloaded. -.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. -.AP Tcl_Obj *linkNamePtr in -The name of the link to be created or read. -.AP Tcl_Obj *toPtr in -What the link called \fIlinkNamePtr\fR should be linked to, or NULL if -the symbolic link specified by \fIlinkNamePtr\fR is to be read. -.AP int linkAction in -OR-ed combination of flags indicating what kind of link should be -created (will be ignored if \fItoPtr\fR is NULL). Valid bits to set -are \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR. -When both flags are set and the underlying filesystem can do either, -symbolic links are preferred. -.BE -.SH DESCRIPTION -.PP -There are several reasons for calling the \fBTcl_FS\fR API functions -(e.g.\ \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR) -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 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 -.QW "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 -.QW "virtual filesystem aware" . -Any virtual filesystem (VFS for short) 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 -.QW files -which are not -native files in the native filesystem. This also means that any Tcl -extension which accesses the filesystem (FS for short) through this API is -automatically -.QW "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 VFSes have been registered, the -.QW 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 -.QW "struct stat" -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 API is \fBTcl_Obj\fR-ified 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 values -with a reference count 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 value, and so one must not assume -that after any of these calls return, the value still has a reference count of -zero - it may have been incremented) or in a direct segmentation fault -(or other memory access error) -due to the value being freed part way through the complex value -manipulation required to ensure that the path is fully normalized and -absolute for filesystem determination. The practical lesson to learn -from this is that -.PP -.CS -Tcl_Obj *path = Tcl_NewStringObj(...); -Tcl_FS\fIWhatever\fR(path); -Tcl_DecrRefCount(path); -.CE -.PP -is wrong, and may cause memory errors. The \fIpath\fR must have its -reference count incremented before passing it in, or -decrementing it. For this reason, values with a reference count of zero are -considered not to be valid filesystem paths and calling any Tcl_FS API -function with such a value will result in no action being taken. -.SS "FS API FUNCTIONS" -\fBTcl_FSCopyFile\fR attempts to copy the file given by \fIsrcPathPtr\fR to the -path name given by \fIdestPathPtr\fR. If the two paths given lie in the same -filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that -filesystem's -.QW "copy file" -function is called (if it is non-NULL). -Otherwise the function returns -1 and sets the \fBerrno\fR global C -variable to the -.QW EXDEV -POSIX error code (which signifies a -.QW "cross-domain link" ). -.PP -\fBTcl_FSCopyDirectory\fR attempts to copy the directory given by \fIsrcPathPtr\fR to the -path name given by \fIdestPathPtr\fR. If the two paths given lie in the same -filesystem (according to \fBTcl_FSGetFileSystemForPath\fR) then that -filesystem's -.QW "copy file" -function is called (if it is non-NULL). -Otherwise the function returns -1 and sets the \fBerrno\fR global C -variable to the -.QW EXDEV -POSIX error code (which signifies a -.QW "cross-domain link" ). -.PP -\fBTcl_FSCreateDirectory\fR attempts to create the directory given by -\fIpathPtr\fR by calling the owning filesystem's -.QW "create directory" -function. -.PP -\fBTcl_FSDeleteFile\fR attempts to delete the file given by -\fIpathPtr\fR by calling the owning filesystem's -.QW "delete file" -function. -.PP -\fBTcl_FSRemoveDirectory\fR attempts to remove the directory given by -\fIpathPtr\fR by calling the owning filesystem's -.QW "remove directory" -function. -.PP -\fBTcl_FSRenameFile\fR attempts to rename the file or directory given by -\fIsrcPathPtr\fR to the path name given by \fIdestPathPtr\fR. If the two paths -given lie in the same filesystem (according to -\fBTcl_FSGetFileSystemForPath\fR) then that filesystem's -.QW "rename file" -function is called (if it is non-NULL). Otherwise the function returns -1 -and sets the \fBerrno\fR global C variable to the -.QW EXDEV -POSIX error code (which signifies a -.QW "cross-domain link" ). -.PP -\fBTcl_FSListVolumes\fR calls each filesystem which has a non-NULL -.QW "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 reference count of 0). -.PP -\fBTcl_FSEvalFileEx\fR reads the file given by \fIpathPtr\fR using -the encoding identified by \fIencodingName\fR and evaluates -its contents as a Tcl script. It returns the same information as -\fBTcl_EvalObjEx\fR. -If \fIencodingName\fR is NULL, the system encoding is used for -reading the file contents. -If the file could not be read then a Tcl error is returned to describe -why the file could not be read. -The eofchar for files is -.QW \e32 -(^Z) for all platforms. -If you require a -.QW ^Z -in code for string comparison, you can use -.QW \e032 -or -.QW \eu001a , -which will be safely substituted by the Tcl interpreter into -.QW ^Z . -\fBTcl_FSEvalFile\fR is a simpler version of -\fBTcl_FSEvalFileEx\fR that always uses the system encoding -when reading the file. -.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 \fIpathPtr\fR -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. -.VS 8.6 -\fBTcl_FSUnloadFile\fR reverses the operation, asking for the library -indicated by the \fIloadHandle\fR to be removed from the process. Note that, -unlike with the \fBunload\fR command, this does not give the library any -opportunity to clean up. -.VE 8.6 -.PP -Both the above functions return a standard Tcl completion code. If an error -occurs, an error message is left in the \fIinterp\fR's result. -.PP -.VS 8.6 -The token provided via the variable indicated by \fIloadHandlePtr\fR may be -used with \fBTcl_FindSymbol\fR. -.VE 8.6 -.PP -\fBTcl_FSMatchInDirectory\fR is used by the globbing code to search a -directory for all files which match a given pattern. The appropriate -function for the filesystem to which \fIpathPtr\fR 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 (unless -interp is NULL, which is allowed), but good results are placed in the -resultPtr given. -.PP -Note that the \fBglob\fR code implements recursive patterns internally, so -this function will only ever be passed simple patterns, which can be -matched using the logic of \fBstring match\fR. To handle recursion, Tcl -will call this function frequently asking only for directories to be -returned. A special case of being called with a NULL pattern indicates -that the path needs to be checked only for the correct type. -.PP -\fBTcl_FSLink\fR replaces the library version of \fBreadlink\fR, and -extends it to support the creation of links. The appropriate function -for the filesystem to which \fIlinkNamePtr\fR belongs will be called. -.PP -If the \fItoPtr\fR is NULL, a -.QW "read link" -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 \fBTcl_DecrRefCount\fR 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 ORed combination of \fBTCL_CREATE_SYMBOLIC_LINK\fR and \fBTCL_CREATE_HARD_LINK\fR. -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 is returned. -.PP -\fBTcl_FSLstat\fR fills the \fITcl_StatBuf\fR 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 \fITcl_StatBuf\fR -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 -last metadata change time. -See \fBPORTABLE STAT RESULT API\fR for a description of how to write -portable code to allocate and access the \fITcl_StatBuf\fR structure. -.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 -This returns 0 on success and -1 on error (as per the \fButime\fR -documentation). If successful, the function -will update the -.QW atime -and -.QW mtime -values of the file given. -.PP -\fBTcl_FSFileAttrsGet\fR implements read access for the hookable \fBfile -attributes\fR subcommand. The appropriate function for the filesystem to -which \fIpathPtr\fR belongs will be called. -.PP -If the result is \fBTCL_OK\fR, then a value was placed in -\fIobjPtrRef\fR, which -will only be temporarily valid (unless \fBTcl_IncrRefCount\fR is called). -.PP -\fBTcl_FSFileAttrsSet\fR implements write access for the hookable \fBfile -attributes\fR subcommand. The appropriate function for the filesystem to -which \fIpathPtr\fR belongs will be called. -.PP -\fBTcl_FSFileAttrStrings\fR implements part of the hookable \fBfile -attributes\fR subcommand. The appropriate function for the filesystem -to which \fIpathPtr\fR 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 \fIobjPtrRef\fR. Tcl -will take that list and first increment its reference count before using it. -On completion of that use, Tcl will decrement its reference count. Hence if -the list should be disposed of by Tcl when done, it should have a -reference count of zero, and if the list should not be disposed of, the -filesystem should ensure it retains a reference count to the value. -.PP -\fBTcl_FSAccess\fR checks whether the process would be allowed to read, -write or test for existence of the file (or other filesystem object) -whose name is \fIpathname\fR. If \fIpathname\fR 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 \fITcl_StatBuf\fR 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 \fITcl_StatBuf\fR -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 -last metadata change time. -See \fBPORTABLE STAT RESULT API\fR for a description of how to write -portable code to allocate and access the \fITcl_StatBuf\fR structure. -.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. -If one of the standard channels, \fBstdin\fR, \fBstdout\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 \fBgetcwd\fR. -.PP -It returns the Tcl library's current working directory. This may be -different to the native platform's working directory, which happens when -the current working directory 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 \fIinterp\fR's result. -.PP -The result already has its reference count incremented for the caller. When -it is no longer needed, that reference count 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 \fBchdir\fR. 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 \fBstat\fR and \fBaccess\fR to check whether the directory -exists and has appropriate permissions. -.PP -For results, see \fBchdir\fR documentation. If successful, we keep a -record of the successful path in \fIcwdPathPtr\fR for subsequent calls to -\fBTcl_FSGetCwd\fR. -.PP -\fBTcl_FSPathSeparator\fR returns the separator character to be used for -most specific element of the path specified by \fIpathPtr\fR (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 must be a valid -list (which is allowed to have a reference count of zero), and returns the path -value given by considering the first \fIelements\fR elements as valid path -segments (each path segment may be a complete path, a partial path or -just a single possible directory or file name). If any path segment is -actually an absolute path, then all prior path segments are discarded. -If \fIelements\fR is less than 0, we use the entire list. -.PP -It is possible that the returned value is actually an element -of the given list, so the caller should be careful to increment the -reference count of the result before freeing the list. -.PP -The returned value, typically with a reference count of zero (but it -could be shared -under some conditions), contains the joined path. The caller must -add a reference count to the value before using it. In particular, the -returned value could be an element of the given list, so freeing the -list might free the value prematurely if no reference count has been taken. -If the number of elements is zero, then the returned value will be -an empty-string Tcl_Obj. -.PP -\fBTcl_FSSplitPath\fR takes the given Tcl_Obj, which should be a valid path, -and returns a Tcl list value containing each segment of that path as -an element. -It returns a list value with a reference count of zero. If the -passed in \fIlenPtr\fR is non-NULL, the variable it points to will be -updated to contain the number of elements in the returned list. -.PP -\fBTcl_FSEqualPaths\fR tests whether the two paths given represent the same -filesystem object. -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 value, owned by Tcl, 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. The return value is owned by -Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR passed in -(unless that is a relative path, in which case the normalized path -value may be freed any time the cwd changes) - the caller can of -course increment the reference count if it wishes to maintain a copy for longer. -.PP -\fBTcl_FSJoinToPath\fR takes the given value, which should usually be a -valid path or NULL, and joins onto it the array of paths segments -given. -.PP -Returns a value, typically with reference count of zero (but it could be shared -under some conditions), containing the joined path. The caller must -add a reference count to the value before using it. If any of the values -passed into this function (\fIpathPtr\fR or \fIpath\fR elements) have -a reference count -of zero, they will be freed when this function returns. -.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 value is already supposedly of the correct type. -The filename may begin with -.QW ~ -(to indicate current user's home directory) or -.QW ~<user> -(to indicate any user's home directory). -.PP -If the conversion succeeds (i.e.\ the value is a valid path in one of -the current filesystems), then \fBTCL_OK\fR is returned. Otherwise -\fBTCL_ERROR\fR is returned, and an error message may -be left in the interpreter. -.PP -\fBTcl_FSGetInternalRep\fR extracts the internal representation of a given -path value, in the given filesystem. If the path value 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 value is a valid path), then it is -returned. Otherwise NULL will be returned, and an error message may be -left in the interpreter. A -.QW translated -path is one which contains no -.QW ~ -or -.QW ~user -sequences (these have been expanded to their current -representation in the filesystem). The value returned is owned by the -caller, which must store it or call \fBTcl_DecrRefCount\fR to ensure memory is -freed. This function is of little practical use, and -\fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually -better functions to use for most purposes. -.PP -\fBTcl_FSGetTranslatedStringPath\fR does the same as -\fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL. -The string returned is dynamically allocated and owned by the caller, -which must store it or call \fBckfree\fR to ensure it is freed. Again, -\fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually -better functions to use for most purposes. -.PP -\fBTcl_FSNewNativePath\fR performs something like the reverse of the -usual obj->path->nativerep conversions. If some code retrieves a path -in native form (from, e.g.\ \fBreadlink\fR 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 value type. -.PP -The resulting value is a pure -.QW path -value, 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 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. It may be desirable in the -future to have non-string-based native representations (for example, -on MacOSX, 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 which may contain either the relative path -or a complete, absolute normalized path in the native encoding (complex -conditions dictate which of these will be provided, so neither can be -relied upon, unless the path is known to be absolute). If you need a -native path which must be absolute, then you should ask for the native -version of a normalized path. If for some reason a non-absolute, -non-normalized version of the path is needed, that must be constructed -separately (e.g.\ using \fBTcl_FSGetTranslatedPath\fR). -.PP -The native representation is cached so that repeated calls to this -function will not require additional conversions. The return value is -owned by Tcl and has a lifetime equivalent to that of the \fIpathPtr\fR -passed in (unless that is a relative path, in which case the native -representation may be freed any time the cwd changes). -.PP -\fBTcl_FSFileSystemInfo\fR returns a list of two elements. The first -element is the name of the filesystem (e.g. -.QW native , -.QW vfs , -.QW zip , -or -.QW 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 value is returned, unless the path value is not -recognized, when NULL will be returned. -.PP -\fBTcl_FSGetFileSystemForPath\fR returns 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 \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or -\fBTCL_PATH_VOLUME_RELATIVE\fR -.SS "PORTABLE STAT RESULT API" -.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 -.VS 8.6 -The portable fields of a \fITcl_StatBuf\fR may be read using the following -functions, each of which returns the value of the corresponding field listed -in the table below. Note that on some platforms there may be other fields in -the \fITcl_StatBuf\fR as it is an alias for a suitable system structure, but -only the portable ones are made available here. See your system documentation -for a full description of these fields. -.DS -.ta \w'\fBTcl_GetModificationTimeFromStat\fR\0\0\0\0'u -\fIAccess Function\fR \fIField\fR - \fBTcl_GetFSDeviceFromStat\fR st_dev - \fBTcl_GetFSInodeFromStat\fR st_ino - \fBTcl_GetModeFromStat\fR st_mode - \fBTcl_GetLinkCountFromStat\fR st_nlink - \fBTcl_GetUserIdFromStat\fR st_uid - \fBTcl_GetGroupIdFromStat\fR st_gid - \fBTcl_GetDeviceTypeFromStat\fR st_rdev - \fBTcl_GetAccessTimeFromStat\fR st_atime - \fBTcl_GetModificationTimeFromStat\fR st_mtime - \fBTcl_GetChangeTimeFromStat\fR st_ctime - \fBTcl_GetSizeFromStat\fR st_size - \fBTcl_GetBlocksFromStat\fR st_blocks - \fBTcl_GetBlockSizeFromStat\fR st_blksize -.DE -.VE 8.6 -.SH "THE VIRTUAL FILESYSTEM API" -.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). \fBTCL_OK\fR will be returned. -.PP -\fBTcl_FSUnregister\fR removes the given filesystem structure from -the list of known filesystems, if it is known, and returns \fBTCL_OK\fR. If -the filesystem is not currently registered, \fBTCL_ERROR\fR 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. -.SS "THE TCL_FILESYSTEM STRUCTURE" -.PP -The \fBTcl_Filesystem\fR structure contains the following fields: -.PP -.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; -} \fBTcl_Filesystem\fR; -.CE -.PP -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 \fBfile rename\fR 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_FSRenameFileProc\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 (\fBlstat\fR, \fBload\fR, \fBgetcwd\fR and \fBchdir\fR) -for which fallbacks do in fact occur at the C level. -.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. -.SS "EXAMPLE FILESYSTEM DEFINITION" -.PP -Here is the filesystem lookup table used by the -.QW vfs -extension which allows filesystem actions to be implemented in Tcl. -.PP -.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; use the core fallback mechanism */ - NULL, - /* No rename file; use the core fallback mechanism */ - NULL, - /* No copy directory; use the core fallback mechanism */ - NULL, - /* Core will use stat for lstat */ - NULL, - /* No load; use the core fallback mechanism */ - NULL, - /* We don't need a getcwd or chdir; the core's own - * internal value is suitable */ - NULL, - NULL -}; -.CE -.SH "FILESYSTEM INFRASTRUCTURE" -.PP -These fields contain basic information about the filesystem structure -and 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. -.SS TYPENAME -.PP -The \fItypeName\fR field contains a null-terminated string that -identifies the type of the filesystem implemented, e.g. -.QW native , -.QW zip -or -.QW vfs . -.SS "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. -.SS VERSION -.PP -The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR. -.SS PATHINFILESYSTEMPROC -.PP -The \fIpathInFilesystemProc\fR field contains the address of a function -which is called to determine whether a given path value 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, -1 should be returned (the behavior of Tcl -for any other return value is not defined). If \fBTCL_OK\fR is returned, -then the optional \fIclientDataPtr\fR output parameter can be used to -return an internal (filesystem specific) representation of the path, -which will be cached inside the path value, 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 \fBTcl_FSPathInFilesystemProc\fR( - Tcl_Obj *\fIpathPtr\fR, - ClientData *\fIclientDataPtr\fR); -.CE -.SS DUPINTERNALREPPROC -.PP -This function makes a copy of a path's internal representation, and is -called when Tcl needs to duplicate a path value. If NULL, Tcl will -simply not copy the internal representation, which may then need to be -regenerated later. -.PP -.CS -typedef ClientData \fBTcl_FSDupInternalRepProc\fR( - ClientData \fIclientData\fR); -.CE -.SS 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 \fBTcl_FSFreeInternalRepProc\fR( - ClientData \fIclientData\fR); -.CE -.SS INTERNALTONORMALIZEDPROC -.PP -Function to convert internal representation to a normalized path. Only -required if the filesystem creates pure path values with no string/path -representation. The return value is a Tcl value whose string -representation is the normalized path. -.PP -.CS -typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR( - ClientData \fIclientData\fR); -.CE -.SS CREATEINTERNALREPPROC -.PP -Function to take a path value, and calculate an internal -representation for it, and store that native representation in the -value. 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 \fBTcl_FSCreateInternalRepProc\fR( - Tcl_Obj *\fIpathPtr\fR); -.CE -.SS NORMALIZEPATHPROC -.PP -Function to normalize a path. Should be implemented for all -filesystems which can have multiple string representations for the same -path value. In Tcl, every -.QW path -must have a single unique -.QW 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 -.QW ~ , -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 value 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 \fBfile -delete\fR, \fBfile rename\fR, \fBfile copy\fR operating on symbolic links. -This function may be called with \fInextCheckpoint\fR 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 \fBTcl_FSNormalizePathProc\fR( - 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). -.SS 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 -.QW 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 -.QW networked , -.QW zip -or -.QW ftp . -The Tcl_Obj result is owned by the filesystem and so Tcl will -increment the reference count of that value if it wishes to retain a reference -to it. -.PP -.CS -typedef Tcl_Obj *\fBTcl_FSFilesystemPathTypeProc\fR( - Tcl_Obj *\fIpathPtr\fR); -.CE -.SS FILESYSTEMSEPARATORPROC -.PP -Function to return the separator character(s) for this filesystem. -This need only be implemented if the filesystem wishes to use a -different separator than the standard string -.QW / . -Amongst other -uses, it is returned by the \fBfile separator\fR command. The -return value should be a value with reference count of zero. -.PP -.CS -typedef Tcl_Obj *\fBTcl_FSFilesystemSeparatorProc\fR( - Tcl_Obj *\fIpathPtr\fR); -.CE -.SS 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 \fBTcl_FSStatProc\fR( - 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 -last metadata change 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. -.SS 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 \fBTcl_FSAccessProc\fR( - 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 filesystem -object) whose name is in \fIpathPtr\fR. If the pathname refers to a -symbolic link, then the -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. -.SS 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 \fBTcl_FSOpenFileChannelProc\fR( - 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 must not be registered in the supplied interpreter -by a \fBTcl_FSOpenFileChannelProc\fR; that task is up to the caller of -\fBTcl_FSOpenFileChannel\fR (if necessary). If one of -the standard channels, \fBstdin\fR, \fBstdout\fR or \fBstderr\fR was -previously closed, the act of creating the new channel also assigns it -as a replacement for the standard channel. -.SS 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 \fBencoding names\fR -which use glob functionality internally). -.PP -.CS -typedef int \fBTcl_FSMatchInDirectoryProc\fR( - Tcl_Interp *\fIinterp\fR, - Tcl_Obj *\fIresultPtr\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 -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 -\fIinterp\fR, unless \fIinterp\fR in NULL in which case no error -message need be generated; on a \fBTCL_OK\fR result, results should be -added to the \fIresultPtr\fR value given (which can be assumed to be a -valid unshared Tcl list). The matches added -to \fIresultPtr\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. -.PP -The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR -parameter contains the following fields: -.PP -.CS -typedef struct Tcl_GlobTypeData { - /* Corresponds to bcdpfls as in 'find -t' */ - int \fItype\fR; - /* Corresponds to file permissions */ - int \fIperm\fR; - /* Acceptable mac type */ - Tcl_Obj *\fImacType\fR; - /* Acceptable mac creator */ - Tcl_Obj *\fImacCreator\fR; -} \fBTcl_GlobTypeData\fR; -.CE -.PP -There are two specific cases which it is important to handle correctly, -both when \fItypes\fR is non-NULL. The two cases are when \fItypes->types -& TCL_GLOB_TYPE_DIR\fR or \fItypes->types & TCL_GLOB_TYPE_MOUNT\fR are -true (and in particular when the other flags are false). In the first of -these cases, the function must list the contained directories. Tcl uses -this to implement recursive globbing, so it is critical that filesystems -implement directory matching correctly. In the second of these cases, -with \fBTCL_GLOB_TYPE_MOUNT\fR, the filesystem must list the mount points -which lie within the given \fIpathPtr\fR (and in this case, \fIpathPtr\fR -need not lie within the same filesystem - different to all other cases in -which this function is called). Support for this is critical if Tcl is -to have seamless transitions between from one filesystem to another. -.SS UTIMEPROC -.PP -Function to process a \fBTcl_FSUtime\fR call. Required to allow setting -(not reading) of times with \fBfile mtime\fR, \fBfile atime\fR and the -open-r/open-w/fcopy implementation of \fBfile copy\fR. -.PP -.CS -typedef int \fBTcl_FSUtimeProc\fR( - 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 should be 0 on success and -1 on an error, as -with the system \fButime\fR. -.SS 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 *\fBTcl_FSLinkProc\fR( - 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 (and should therefore -have its ref count incremented before being returned). Any callers -should call \fBTcl_DecrRefCount\fR on this result when it 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 -(i.e.\ no reference count manipulations on either end are needed). See -the documentation for \fBTcl_FSLink\fR for the correct interpretation -of the \fIlinkAction\fR flags. -.SS 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 \fBfile volumes\fR. -.PP -.CS -typedef Tcl_Obj *\fBTcl_FSListVolumesProc\fR(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 value -is considered to be owned by the filesystem (not by Tcl's core), but -should be given a reference count for Tcl. Tcl will use the contents of the -list and then decrement that reference count. This allows filesystems to -choose whether they actually want to retain a -.QW "master list" -of volumes -or not (if not, they generate the list on the fly and pass it to Tcl -with a reference count of 1 and then forget about the list, if yes, then -they simply increment the reference count 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. -.SS 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 *const *\fBTcl_FSFileAttrStringsProc\fR( - 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 \fIobjPtrRef\fR. Tcl -will take that list and first increment its reference count before using it. -On completion of that use, Tcl will decrement its reference count. Hence if -the list should be disposed of by Tcl when done, it should have a -reference count of zero, and if the list should not be disposed of, the -filesystem should ensure it returns a value with a reference count -of at least one. -.SS FILEATTRSGETPROC -.PP -Function to process a \fBTcl_FSFileAttrsGet\fR call, used by \fBfile -attributes\fR. -.PP -.CS -typedef int \fBTcl_FSFileAttrsGetProc\fR( - 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 \fBTcl_FSFileAttrStringsProc\fR, is a Tcl_Obj placed in \fIobjPtrRef\fR (if -\fBTCL_OK\fR was returned) and is likely to have a reference count of zero. Either -way we must either store it somewhere (e.g.\ the Tcl result), or -Incr/Decr its reference count to ensure it is properly freed. -.SS FILEATTRSSETPROC -.PP -Function to process a \fBTcl_FSFileAttrsSet\fR call, used by \fBfile -attributes\fR. If the filesystem is read-only, there is no need -to implement this. -.PP -.CS -typedef int \fBTcl_FSFileAttrsSetProc\fR( - 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. -.SS CREATEDIRECTORYPROC -.PP -Function to process a \fBTcl_FSCreateDirectory\fR call. Should be -implemented unless the FS is read-only. -.PP -.CS -typedef int \fBTcl_FSCreateDirectoryProc\fR( - 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. -.SS REMOVEDIRECTORYPROC -.PP -Function to process a \fBTcl_FSRemoveDirectory\fR call. Should be -implemented unless the FS is read-only. -.PP -.CS -typedef int \fBTcl_FSRemoveDirectoryProc\fR( - 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 this flag is not given, then and the -directory is non-empty a POSIX -.QW EEXIST -error should be signaled. If an -error does occur, the name of the file or directory which caused the -error should be placed in \fIerrorPtr\fR. -.SS DELETEFILEPROC -.PP -Function to process a \fBTcl_FSDeleteFile\fR call. Should be implemented -unless the FS is read-only. -.PP -.CS -typedef int \fBTcl_FSDeleteFileProc\fR( - 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 -These functions need not be implemented for a particular filesystem -because the core has a fallback implementation available. See each -individual description for the consequences of leaving the field NULL. -.SS 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 \fBTcl_FSLstatProc\fR( - Tcl_Obj *\fIpathPtr\fR, - Tcl_StatBuf *\fIstatPtr\fR); -.CE -.PP -The behavior of this function is very similar to that of the -\fBTcl_FSStatProc\fR defined above, except that if it is applied -to a symbolic link, it returns information about the link, not -about the target file. -.SS COPYFILEPROC -.PP -Function to process a \fBTcl_FSCopyFile\fR call. If not implemented Tcl -will fall back on \fBopen\fR-r, \fBopen\fR-w and \fBfcopy\fR as a -copying mechanism. -Therefore it need only be implemented if the filesystem can perform -that action more efficiently. -.PP -.CS -typedef int \fBTcl_FSCopyFileProc\fR( - 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 \fBfile -copy\fR subcommand). Note that, -if the filesystem supports symbolic links, Tcl will always call this -function and not \fIcopyDirectoryProc\fR when needed to copy them -(even if they are symbolic links to directories). Finally, if the -filesystem determines it cannot support the \fBfile copy\fR action, -calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR -result will tell Tcl to use its standard fallback mechanisms. -.SS 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 \fBTcl_FSRenameFileProc\fR( - 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. If the -filesystem determines it cannot support the \fBfile rename\fR action, -calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR -result will tell Tcl to use its standard fallback mechanisms. -.SS COPYDIRECTORYPROC -.PP -Function to process a \fBTcl_FSCopyDirectory\fR call. If not -implemented, Tcl will fall back on a recursive \fBfile mkdir\fR, \fBfile copy\fR -mechanism. Therefore it need only be implemented if the filesystem can -perform that action more efficiently. -.PP -.CS -typedef int \fBTcl_FSCopyDirectoryProc\fR( - 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 \fBfile copy\fR subcommand). Finally, if the -filesystem determines it cannot support the directory copy action, -calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR -result will tell Tcl to use its standard fallback mechanisms. -.SS 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 \fBTcl_FSLoadFile\fR 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 \fBTCL_ERROR\fR to disable load functionality in this filesystem -entirely. -.PP -.CS -typedef int \fBTcl_FSLoadFileProc\fR( - 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 \fIinterp\fR'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 unload procedure will be called with the given \fBTcl_LoadHandle\fR as its -only parameter when Tcl needs to unload the file. For example, for the -native filesystem, the \fBTcl_LoadHandle\fR returned is currently a token -which can be used in the private \fBTclpFindSymbol\fR to access functions -in the new code. Each filesystem is free to define the -\fBTcl_LoadHandle\fR as it requires. Finally, if the -filesystem determines it cannot support the file load action, -calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR -result will tell Tcl to use its standard fallback mechanisms. -.SS 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 \fBTcl_FSUnloadFileProc\fR( - Tcl_LoadHandle \fIloadHandle\fR); -.CE -.SS GETCWDPROC -.PP -Function to process a \fBTcl_FSGetCwd\fR call. Most filesystems need not -implement this. It will usually only be called once, if \fBgetcwd\fR is -called before \fBchdir\fR. May be NULL. -.PP -.CS -typedef Tcl_Obj *\fBTcl_FSGetCwdProc\fR( - 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 \fIinterp\fR's result. -.SS 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 \fIpathPtr\fR is a valid, -accessible directory in their filesystem. They need not remember the -result, since that will be automatically remembered for use by -\fBTcl_FSGetCwd\fR. -Real filesystems should carry out the correct action (i.e.\ call the -correct system \fBchdir\fR API). -.PP -.CS -typedef int \fBTcl_FSChdirProc\fR( - 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 "SEE ALSO" -cd(n), file(n), filename(n), load(n), open(n), pwd(n), source(n), unload(n) -.SH KEYWORDS -stat, access, filesystem, vfs, virtual filesystem |