Filesystem(3) Tcl Library Procedures Filesystem(3)
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_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_FSGet-
TranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_AllocStatBuf - proce-
dures to interact with any filesystem
Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)
Tcl_FSRemoveDirectory(pathPtr, int recursive, errorPtr)
Tcl_FSEvalFileEx(interp, pathPtr, encodingName) |
Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
Tcl_FSMatchInDirectory(interp, resultPtr, pathPtr, pattern, types)
Tcl_FSLink(linkNamePtr, toPtr, linkAction)
Tcl_FSFileAttrsGet(interp, int index, pathPtr, objPtrRef)
Tcl_FSFileAttrsSet(interp, int index, pathPtr, Tcl_Obj *objPtr)
Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)
Tcl_FSJoinToPath(basePtr, objc, objv)
const char *
const char *
Tcl_Filesystem *fsPtr (in) Points to a structure containing the addresses of procedures that can be called to per-
form the various filesystem operations.
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 path representation, it will be converted to
Tcl_Obj *srcPathPtr (in) As for pathPtr, but used for the source file for a copy or rename operation.
Tcl_Obj *destPathPtr (in) As for pathPtr, but used for the destination filename for a copy or rename operation.
const char *encodingName (in) The encoding of the data stored in the file identified by pathPtr and to be evaluated.
const char *pattern (in) Only files or directories matching this pattern will be returned.
Tcl_GlobTypeData *types (in) Only files or directories matching the type descriptions contained in this structure
will be returned. This parameter may be NULL.
Tcl_Interp *interp (in) Interpreter to use either for results, evaluation, or reporting error messages.
ClientData clientData (in) The native description of the path object to create.
Tcl_Obj *firstPtr (in) The first of two path objects to compare. The object may be converted to path type.
Tcl_Obj *secondPtr (in) The second of two path objects to compare. The object may be converted to path type.
Tcl_Obj *listObj (in) The list of path elements to operate on with a join operation.
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.
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.
Tcl_Obj **objPtrRef (out) Filled with an object containing the result of the operation.
Tcl_Obj *resultPtr (out) Pre-allocated object in which to store (using Tcl_ListObjAppendElement) the list of
files or directories which are successfully matched.
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 permis-
sions, respectively. F_OK just requests checking for the existence of the file.
Tcl_StatBuf *statPtr (out) The structure that contains the result of a stat or lstat operation.
const char *sym1 (in) Name of a procedure to look up in the file's symbol table
const char *sym2 (in) Name of a procedure to look up in the file's symbol table
Tcl_PackageInitProc **proc1Ptr (out) Filled with the init function for this code.
Tcl_PackageInitProc **proc2Ptr (out) Filled with the safe-init function for this code.
ClientData *clientDataPtr (out) Filled with the clientData value to pass to this code's unload function when it is
Tcl_LoadHandle *handlePtr (out) Filled with an abstract token representing the loaded file.
Tcl_FSUnloadFileProc **unloadProcPtr (out) Filled with the function to use to unload this piece of code.
utimbuf *tval (in) The access and modification times in this structure are read and used to set those val-
ues for a given file.
const char *modeString (in) Specifies how the file is to be accessed. May have any of the values allowed for the
mode argument to the Tcl open command.
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.
int *lenPtr (out) If non-NULL, filled with the number of elements in the split path.
Tcl_Obj *basePtr (in) The base path on to which to join the given elements. May be NULL.
int objc (in) The number of elements in objv.
Tcl_Obj *const objv (in) The elements to join to the given base path.
Tcl_Obj *linkNamePtr (in) The name of the link to be created or read.
Tcl_Obj *toPtr (in) What the link called linkNamePtr should be linked to, or NULL if the symbolic link spec-
ified by linkNamePtr is to be read.
int linkAction (in) OR-ed combination of flags indicating what kind of link should be created (will be
ignored if toPtr is NULL). Valid bits to set are TCL_CREATE_SYMBOLIC_LINK and TCL_CRE-
ATE_HARD_LINK. When both flags are set and the underlying filesystem can do either,
symbolic links are preferred.
There are several reasons for calling the Tcl_FS API functions (e.g. Tcl_FSAccess and Tcl_FSStat) rather than calling system level func-
tions like access and stat 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 func-
tion 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 (VFS for short) which has been registered (through Tcl_FSRegister) may reroute file access to alternative media or
access methods. This means that all of these functions (and therefore the corresponding file, glob, pwd, cd, open, 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 (FS for short) 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.
If appropriate VFSes 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 Tcl_FSStat and Tcl_FSLstat calls abstract away from what the "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.
The Tcl_FS API is 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 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
object, and so one must not assume that after any of these calls return, the object 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 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
Tcl_Obj *path = Tcl_NewStringObj(...);
is wrong, and may cause memory errors. The path must have its reference count incremented before passing it in, or decrementing it. For
this reason, objects with a reference count of zero are considered not to be valid filesystem paths and calling any Tcl_FS API function
with such an object will result in no action being taken.
FS API FUNCTIONS
Tcl_FSCopyFile 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 Tcl_FSGetFileSystemForPath) then that filesystem's "copy file" function is called (if it is non-NULL). Otherwise
the function returns -1 and sets the errno global C variable to the "EXDEV" POSIX error code (which signifies a "cross-domain link").
Tcl_FSCopyDirectory 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 Tcl_FSGetFileSystemForPath) then that filesystem's "copy file" function is called (if it is non-NULL).
Otherwise the function returns -1 and sets the errno global C variable to the "EXDEV" POSIX error code (which signifies a "cross-domain
Tcl_FSCreateDirectory attempts to create the directory given by pathPtr by calling the owning filesystem's "create directory" function.
Tcl_FSDeleteFile attempts to delete the file given by pathPtr by calling the owning filesystem's "delete file" function.
Tcl_FSRemoveDirectory attempts to remove the directory given by pathPtr by calling the owning filesystem's "remove directory" function.
Tcl_FSRenameFile 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 Tcl_FSGetFileSystemForPath) then that filesystem's "rename file" function is called (if it
is non-NULL). Otherwise the function returns -1 and sets the errno global C variable to the "EXDEV" POSIX error code (which signifies a
Tcl_FSListVolumes 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 reference count of 0).
Tcl_FSEvalFileEx reads the file given by pathPtr using the encoding identified by encodingName and evaluates its contents as a Tcl script. |
It returns the same information as Tcl_EvalObjEx. If encodingName 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 "32" (^Z) |
for all platforms. If you require a "^Z" in code for string comparison, you can use "