diff options
| -rw-r--r-- | doc/FileSystem.3 | 1195 |
1 files changed, 1195 insertions, 0 deletions
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3 new file mode 100644 index 0000000..9380b42 --- /dev/null +++ b/doc/FileSystem.3 @@ -0,0 +1,1195 @@ +'\" +'\" 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.1 2001/07/31 19:15:24 vincentdarley Exp $ +'\" +.so man.macros +.TH Tcl_FSCopyFile 3 8.4 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSReadlink, 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_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo \- 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 +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 +int +\fBTcl_FSListVolumes\fR(\fIinterp\fR) +.sp +int +\fBTcl_FSEvalFile\fR(\fIinterp, fileName\fR) +.sp +int +\fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr, clientDataPtr, unloadProcPtr\fR) +.sp +int +\fBTcl_FSMatchInDirectory\fR(\fIinterp, result, pathPtr, pattern, types\fR) +.sp +Tcl_Obj* +\fBTcl_FSReadlink\fR(\fIpathPtr\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 +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(\fIfIpathPtr\fR\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 +char* +\fBTcl_FSGetTranslatedPath\fR(\fIinterp, pathPtr\fR) +.sp +Tcl_Obj* +\fBTcl_FSNewNativePath\fR(\fIfsPtr, clientData\fR) +.sp +char* +\fBTcl_FSGetNativePath\fR(\fIpathPtr\fR) +.sp +Tcl_Obj* +\fBTcl_FSFileSystemInfo\fR(\fIpathPtr\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 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 stat *statPtr out +The structure that contains the result of a stat or lstat operation. +.AP char *sym1 in +Name of a procedure to look up in the file's symbol table +.AP 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 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 +\fBTclRegisterFilesystem\fR) may reroute file access to alternative +media or access methods. This means that all of these functions (and +therefore the corresponding \fBfile\fR, \fBpwd\fR, \fBcd\fR, +\fBopen\fR, etc. Tcl commands) may be operate on 'files' which are not +native files in the native filesystem. 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. +.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 those to append their root volumes to +the list in the interpreters result. +.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 +directory for all files which match a given pattern. The appropriate +function for the filesystem to which pathPtr belongs will be called. +.PP +The return value is a standard Tcl result indicating whether an error +occurred in globbing. Error messages are placed in interp, but good +results are placed in the resultPtr given. + +Note that the 'glob' code implements recursive patterns internally, so +this function will only ever be passed simple patterns, which can be +matched using the logic of 'string match'. To handle recursion, Tcl +will call this function frequently asking only for directories to be +returned. +.PP +\fBTcl_FSReadlink\fR replaces the library version of readlink(). +The appropriate function for the filesystem to which pathPtr +belongs will be called. +.PP +The result is a Tcl_Obj specifying the contents of the symbolic link +given by 'path', or NULL if the symbolic link could not be read. The +result is owned by the caller, which should call Tcl_DecrRefCount when +the result is no longer needed. +.PP +\fBTcl_FSLstat\fR fills the stat structure \fIstatPtr\fR with information +about the specified file. You do not need any access rights to the +file to get this information but you need search rights to all +directories named in the path leading to the file. The stat structure +includes info regarding device, inode (always 0 on Windows), +privilege mode, nlink (always 1 on Windows), user id (always 0 on +Windows), group id (always 0 on Windows), rdev (same as device on +Windows), size, last access time, last modification time, and creation +time. +.PP +If \fIpath\fR exists, \fBTcl_FSLstat\fR returns 0 and the stat structure +is filled with data. Otherwise, -1 is returned, and no stat info is +given. +.PP +\fBTcl_FSUtime\fR replaces the library version of utime. +.PP +For results see 'utime' documentation. If successful, the function +will update the 'atime' and 'mtime' values of the file given. +.PP +\fBTcl_FSFileAttrsGet\fR implements read access for the hookable 'file +attributes' subcommand. The appropriate function for the filesystem to +which pathPtr belongs will be called. +.PP +If the result is TCL_OK, then an object was placed in objPtrRef, which +will only be temporarily valid (unless Tcl_IncrRefCount is called). +.PP +\fBTcl_FSFileAttrsSet\fR implements write access for the hookable 'file +attributes' subcommand. The appropriate function for the filesystem to +which pathPtr belongs will be called. +.PP +\fBTcl_FSFileAttrStrings\fR implements part of the hookable 'file attributes' +subcommand. The appropriate function for the filesystem to which +pathPtr belongs will be called. +.PP +The called procedure may either return an array of strings, or may +instead return NULL and place a Tcl list into the given objPtrRef. Tcl +will take that list and first increment its refCount before using it. +On completion of that use, Tcl will decrement its refCount. Hence if +the list should be disposed of by Tcl when done, it should have a +refCount of zero, and if the list should not be disposed of, the +filesystem should ensure it retains a refCount on the object. +.PP +\fBTcl_FSAccess\fR checks whether the process would be allowed to read, +write or test for existence of the file (or other file system object) +whose name is pathname. If pathname is a symbolic link on Unix, +then permissions of the file referred by this symbolic link are +tested. +.PP +On success (all requested permissions granted), zero is returned. On +error (at least one bit in mode asked for a permission that is denied, +or some other error occurred), -1 is returned. +.PP +\fBTcl_FSStat\fR fills the stat structure \fIstatPtr\fR with information +about the specified file. You do not need any access rights to the +file to get this information but you need search rights to all +directories named in the path leading to the file. The stat structure +includes info regarding device, inode (always 0 on Windows), +privilege mode, nlink (always 1 on Windows), user id (always 0 on +Windows), group id (always 0 on Windows), rdev (same as device on +Windows), size, last access time, last modification time, and creation +time. +.PP +If \fIpath\fR exists, \fBTcl_FSStat\fR returns 0 and the stat structure +is filled with data. Otherwise, -1 is returned, and no stat info is +given. +.PP +\fBTcl_FSOpenFileChannel\fR opens a file specified by \fIfileName\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_OpenFileChannel\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_OpenFileChannel\fR +leaves an error message in \fIinterp\fR's result after any error. +.PP +The newly created channel is not registered in the supplied interpreter; to +register it, use \fBTcl_RegisterChannel\fR, described below. +If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was +previously closed, the act of creating the new channel also assigns it as a +replacement for the standard channel. +.PP +\fBTcl_FSGetCwd\fR replaces the library version of getcwd(). +.PP +It returns the Tcl library's current working directory. This may be +different to the native platform's working directory, in the case for +which the cwd is not in the native filesystem. +.PP +The result is a pointer to a Tcl_Obj specifying the current directory, +or NULL if the current directory could not be determined. If NULL is +returned, an error message is left in the interp's result. + +The result already has its refCount incremented for the caller. When +it is no longer needed, that refCount should be decremented. This is +needed for thread-safety purposes, to allow multiple threads to access +this and related functions, while ensuring the results are always +valid. +.PP +\fBTcl_FSChdir\fR replaces the library version of chdir(). The path is +normalized and then passed to the filesystem which claims it. If that +filesystem does not implement this function, Tcl will fallback to a +combination of stat and access to check whether the directory exists +and has appropriate permissions. +.PP +For results, see chdir() documentation. If successful, we keep a +record of the successful path in cwdPathPtr for subsequent calls to +getcwd. +.PP +\fBTcl_FSPathSeparator\fR returns the separator character to be used for +most specific element of the path specified by pathPtr (i.e. the last +part of the path). +.PP +The separator is returned as a Tcl_Obj containing a string of length +1. If the path is invalid, NULL is returned. +.PP +\fBTcl_FSJoinPath\fR takes the given Tcl_Obj, which should be a valid list, +and returns the path object given by considering the first 'elements' +elements as valid path segments. If elements < 0, we use the entire +list. +.PP +Returns object with refCount of zero, containing the joined path. +.PP +\fBTcl_FSSplitPath\fR takes the given Tcl_Obj, which should be a valid path, +and returns a Tcl List object containing each segment of that path as +an element. +.PP +Returns list object with refCount of zero. If the passed in lenPtr is +non-NULL, we use it to return the number of elements in the returned +list. +.PP +\fBTcl_FSEqualPaths\fR tests whether the two paths given represent the same +filesystem object +.PP +It returns 1 if the paths are equal, and 0 if they are different. If +either path is NULL, 0 is always returned. +.PP +\fBTcl_FSGetNormalizedPath\fR this important function attempts to extract +from the given Tcl_Obj a unique normalized path representation, whose +string value can be used as a unique identifier for the file. +.PP +It returns the normalized path object, with refCount of zero, or NULL +if the path was invalid or could otherwise not be successfully +converted. +.PP +\fBTcl_FSJoinToPath\fR takes the given object, which should usually be a +valid path or NULL, and joins onto it the array of paths segments +given. +.PP +Returns object with refCount of zero, containing the joined path. +.PP +\fBTcl_FSConvertToPathType\fR tries to convert the given Tcl_Obj to a valid +Tcl path type, taking account of the fact that the cwd may have changed +even if this object is already supposedly of the correct type. +The filename may begin with "~" (to indicate current user's home +directory) or "~<user>" (to indicate any user's home directory). +.PP +If the conversion succeeds (i.e. the object is a valid path in one of +the current filesystems), then TCL_OK is returned. Otherwise +TCL_ERROR is returned, and an error message may +be left in the interpreter. +.PP +\fBTcl_FSGetInternalRep\fR extracts the internal representation of a given +path object, in the given filesystem. If the path object belongs to a +different filesystem, we return NULL. If the internal representation is +currently NULL, we attempt to generate it, by calling the filesystem's +'TclfsConvertToInternalProc_'. +.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 string +from the given Tcl_Obj. +.PP +If the translation succeeds (i.e. the object is a valid path), then it +is returned. Otherwise NULL will be returned, and an error message may +be left in the interpreter. +.PP +\fBTcl_FSNewNativePath\fR performs the something like that reverse of the +usual obj->path->nativerep conversions. If some code retrieves a path +in native form (from, e.g. readlink or a native dialog), and that path +is to be used at the Tcl level, then calling this function is an +efficient way of creating the appropriate path object type. +.PP +The resulting object is a pure 'path' object, which will only receive +a Utf-8 string representation if that is required by some Tcl code. +.PP +\fBTcl_FSGetNativePath\fR is for use by the Win/Unix/MacOS native +filesystems, so that they can easily retrieve the native (char* or +TCHAR*) representation of a path. +.PP +The native representation is cached so that repeated calls to this +function will not require additional conversions. +.PP +\fBTcl_FSFileSystemInfo\fR returns a list of two elements. The first +element is the name of the filesystem (e.g. "native" or "vfs" or "zip" +or "prowrap", perhaps), and the second is the particular type of the +given path within that filesystem (which is filesystem dependent). The +second element may be empty if the filesystem does not provide a +further categorization of files. +.PP +A valid list object is returned, unless the path object is not +recognized, when NULL will be returned. +.PP + +.SH TCL_FILESYSTEM +.PP +A filesystem provides a \fBTcl_Filesystem\fR structure that contains +pointers to functions that implement the various operations on a +filesystem; these operations are invoked as needed by the generic +layer, which generally occurs through the functions listed above. +.PP +The \fBTcl_Filesystem\fR structures are manipulated using the following +methods. +.PP +\fBTcl_FSRegister\fR takes a pointer to a filesystem structure and an +optional piece of data to associated with that filesystem. On calling +this function, Tcl will attach the filesystem to the list of known +filesystems, and it will become fully functional immediately. Tcl does +not check if the same filesystem is registered multiple times (and in +general that is not a good thing to do). TCL_OK will be returned. +.PP +\fBTcl_FSUnregister\fR removes the given filesystem structure from +the list of known filesystems, if it is known, and returns TCL_OK. If +the filesystem is not currently registered, TCL_ERROR is returned. +.PP +\fBTcl_FSData\fR will return the ClientData associated with the given +filesystem, if that filesystem is registered. Otherwise it will +return NULL. +.PP +The \fBTcl_Filesystem\fR structure contains the following fields: +.CS +typedef struct Tcl_Filesystem { + CONST char *\fItypeName\fR; + int \fIstructureLength\fR; + Tcl_FSVersion \fIversion\fR; + Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR; + Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR; + Tcl_FSFreeInternalRepProc *\fIfreeInternalRepProc\fR; + Tcl_FSInternalToNormalizedProc *\fIinternalToNormalizedProc\fR; + Tcl_FSCreateInternalRepProc *\fIcreateInternalRepProc\fR; + Tcl_FSNormalizePathProc *\fInormalizePathProc\fR; + Tcl_FSFilesystemPathTypeProc *\fIfilesystemPathTypeProc\fR; + Tcl_FSFilesystemSeparatorProc *\fIfilesystemSeparatorProc\fR; + Tcl_FSStatProc *\fIstatProc\fR; + Tcl_FSAccessProc *\fIaccessProc\fR; + Tcl_FSOpenFileChannelProc *\fIopenFileChannelProc\fR; + Tcl_FSMatchInDirectoryProc *\fImatchInDirectoryProc\fR; + Tcl_FSUtimeProc *\fIutimeProc\fR; + Tcl_FSReadlinkProc *\fIreadlinkProc\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_FSUnloadFileProc *\fIunloadFileProc\fR; + Tcl_FSGetCwdProc *\fIgetCwdProc\fR; + Tcl_FSChdirProc *\fIchdirProc\fR; +} Tcl_Filesystem; +.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 'file rename' 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_FSRenameFile\fR command is issued at the C level, no such +fallbacks occur. This is true except for the last five entries in the +filesystem table (lstat, load, unload, getcwd and chdir) 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. +.PP +.SH TYPENAME +.PP +The \fItypeName\fR field contains a null-terminated string that +identifies the type of the filesystem implemented, e.g. +\fBnative\fR or \fBzip\fR or \fBvfs\fR. +.PP +.SH "STRUCTURE LENGTH" +.PP +The \fIstructureLength\fR field is generally implemented as +\fIsizeof(Tcl_Filesystem)\R, and is there to allow easier +binary backwards compatibility if the size of the structure +changes in a future Tcl release. +.PP +.SH VERSION +.PP +The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR. +.PP +.SH FILESYSTEM INFRASTRUCTURE +.PP +These fields contain 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. +.PP +.SH PATHINFILESYSTEMPROC +.PP +The \fIpathInFilesystemProc\fR field contains the address of a function +which is called to determine whether a given path object 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, \fBTCL_ERROR\fR should be +returned. If \fBTCL_OK\fR is returned, then the optional +\fBclientDataPtr\fR output parameter can be used to return an internal +(filesystem specific) representation of the path, which will be cached +inside the path object, 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 Tcl_FSPathInFilesystemProc( + Tcl_Obj *\fIpathPtr\fR, + ClientData *\fIclientDataPtr\fR); +.CE +.PP +.SH DUPINTERNALREPPROC +.PP +This function makes a copy of a path's internal representation, and is +called when Tcl needs to duplicate a path object. If NULL, Tcl will +simply not copy the internal representation, which may then need to be +regenerated later. +.PP +.CS +typedef ClientData Tcl_FSDupInternalRepProc( + ClientData \fIclientData\fR); +.CE +.PP +.SH 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 Tcl_FSFreeInternalRepProc( + ClientData \fIclientData\fR); +.CE +.PP +.SH INTERNALTONORMALIZEDPROC +.PP +Function to convert internal representation to a normalized path. Only +required if the filesystem creates pure path objects with no string/path +representation. The return value is a Tcl object whose string +representation is the normalized path. +.PP +.CS +typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc( + ClientData \fIclientData\fR); +.CE +.PP +.SH CREATEINTERNALREPPROC +.PP +Function to take a path object, and calculate an internal +representation for it, and store that native representation in the +object. 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 Tcl_FSCreateInternalRepProc( + Tcl_Obj *\fIpathPtr\fR); +.CE +.PP +.SH NORMALIZEPATHPROC +.PP +Function to normalize a path. Should be implemented for all +filesystems which can have multiple string representations for the same +path object. In Tcl, every 'path' must have a single unique +'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 '~', etc). +.PP +.CS +typedef int Tcl_FSNormalizePathProc( + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIpathPtr\fR, + int \fInextCheckpoint\fR); +.CE +.PP +.SH FILESYSTEM OPERATIONS +.PP +This 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 'readlink' function, +etc. The Tcl core expects filesystems to behave in this way). +.PP +.SH 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 '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 "networked", "zip" +or "ftp". +.PP +.CS +typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc( + Tcl_Obj *\fIpathPtr\fR); +.CE +.PP +.SH FILESYSTEMSEPARATORPROC +.PP +Function to return the separator character(s) for this filesystem. +Must be implemented, otherwise the 'file separator' command will not +function correctly. The usual return value will be a Tcl_Obj +containing the string "/". +.PP +.CS +typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc( + Tcl_Obj *\fIpathPtr\fR); +.CE +.PP +.SH STATPROC +.PP +Function to process a 'Tcl_FSStat()' call. Must be implemented for any +reasonable filesystem, since many Tcl level commands depend crucially +upon it (e.g. 'file atime', 'file isdirectory', 'file size', 'glob'). +See the documentation of ' +.PP +.CS +typedef int Tcl_FSStatProc( + Tcl_Obj *\fIpathPtr\fR, + struct stat *\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 creation +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. +.PP +.SH ACCESSPROC +.PP +Function to process a 'Tcl_FSAccess()' call. Must be implemented for +any reasonable filesystem, since many Tcl level commands depend crucially +upon it (e.g. 'file exists', 'file readable'). +.PP +.CS +typedef int Tcl_FSAccessProc( + 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 file system +object) whose name is pathname. If pathname is a symbolic link, then +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. +.PP +.SH OPENFILECHANNELPROC +.PP +Function to process a 'Tcl_FSOpenFileChannel()' 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. 'open', 'encoding', and many Tk commands). +.PP +.CS +typedef Tcl_Channel Tcl_FSOpenFileChannelProc( + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIpathPtr\fR, + char *\fImodeString\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. 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 is not registered in the supplied +interpreter; to register it, use \fBTcl_RegisterChannel\fR. If one of +the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was +previously closed, the act of creating the new channel also assigns it +as a replacement for the standard channel. +.PP +.SH MATCHINDIRECTORYPROC +.PP +Function to process a 'Tcl_FSMatchInDirectory()' call. If not +implemented, then glob and recursive copy functionality will be lacking +in the filesystem (and this may impact commands like 'encoding names' +which use glob functionality internally). +.PP +.CS +typedef int Tcl_FSMatchInDirectoryProc( + Tcl_Interp* \fIinterp\fR, + Tcl_Obj *\fIresult\fR, + Tcl_Obj *\fIpathPtr\fR, + 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. The directory \fIpathPtr\fR, in which +the function should search, can be assumed to be both non-NULL and +non-empty. +.PP +The return value is a standard Tcl result indicating whether an error +occurred in the matching process. Error messages are placed in interp, +but on a TCL_OK result, the interpreter should not be modified, but +rather results should be added to the \fIresult\fR object given +(which can be assumed to be a valid Tcl list). The matches added +to \fIresult\fR should include any path prefix given in \fIpathPtr\fR +(this usually means they will be absolute path specifications). + .PP +.SH UTIMEPROC +.PP +Function to process a 'Tcl_FSUtime()' call. Required to allow setting +(not reading) of times with 'file mtime', 'file atime' and the +open-r/open-w/fcopy implementation of 'file copy'. +.PP +.CS +typedef int Tcl_FSUtimeProc( + Tcl_Obj *\fIpathPtr\fR, + struct utimbuf *\fItval\fR); +.CE +.PP +The access and modification times of the file specified by \fIpathPtr\fR +should be changed to the values given in the \fItval\fR structure. +.PP +The return value is a standard Tcl result indicating whether an error +occurred in the process. +.PP +.SH READLINKPROC +.PP +Function to process a 'Tcl_FSReadlink()' call. Should be implemented +only if the filesystem supports links, and may otherwise be NULL. +.PP +.CS +typedef Tcl_Obj* Tcl_FSReadlinkProc( + Tcl_Obj *\fIpathPtr\fR); +.CE +.PP +The result is a Tcl_Obj specifying the contents of the symbolic link +given by 'path', or NULL if the symbolic link could not be read. The +result is owned by the caller, which should call Tcl_DecrRefCount when +the result is no longer needed. +.PP +.SH LISTVOLUMESPROC +.PP +Function to list any filesystem volumes added by this filesystem. +Should be implemented only if the filesystem adds volumes at the head +of the filesystem, so that they can be returned by 'file volumes'. +.PP +.CS +typedef int Tcl_FSListVolumesProc( + Tcl_Interp *\fIinterp\fR); +.CE +.PP +The result should be TCL_OK, since there is no way this function can +fail. The function should add the known volumes to the list object +contained in the Tcl interpreter's result. +.PP +.SH FILEATTRSTRINGSPROC +.PP +Function to list all attributes strings which are valid for this +filesystem. If not implemented the filesystem will not support the +'file attributes' 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 'get' and 'set' +methods. +.PP +.CS +typedef char** Tcl_FSFileAttrStringsProc( + Tcl_Obj *\fIpathPtr\fR, + Tcl_Obj** \fIobjPtrRef\fR); +.CE +.PP +The called function may either return an array of strings, or may +instead return NULL and place a Tcl list into the given objPtrRef. Tcl +will take that list and first increment its refCount before using it. +On completion of that use, Tcl will decrement its refCount. Hence if +the list should be disposed of by Tcl when done, it should have a +refCount of zero, and if the list should not be disposed of, the +filesystem should ensure it retains a refCount on the object. +.PP +.SH FILEATTRSGETPROC +.PP +Function to process a 'Tcl_FSFileAttrsGet()' call, used by 'file +attributes'. +.PP +.CS +typedef int Tcl_FSFileAttrsGetProc( + Tcl_Interp *\fIinterp\fR, + int \fIindex\fR, + Tcl_Obj *\fIpathPtr\fR, + Tcl_Obj **\fIobjPtrRef\fR); +.CE +.PP +Returns a standard Tcl return code. The attribute value retrieved, +which corresponds to the \fIindex\fR'th element in the list returned by +the Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in objPtrRef (if +TCL_OK was returned) and is likely to have a refCount of zero. Either +way we must either store it somewhere (e.g. the Tcl result), or +Incr/Decr its refCount to ensure it is properly freed. +.PP +.SH FILEATTRSSETPROC +.PP +Function to process a 'Tcl_FSFileAttrsSet()' call, used by 'file +attributes'. If the filesystem is read-only, there is no need +to implement this. +.PP +.CS +typedef int Tcl_FSFileAttrsSetProc( + Tcl_Interp *\fIinterp\fR, + int \fIindex\fR, + Tcl_Obj *\fIpathPtr\fR, + Tcl_Obj *\fIobjPtr\fR); +.CE +.PP +The attribute value of the \fIindex\fR'th element in the list returned by +the Tcl_FSFileAttrStringsProc should be set to the \fIobjPtr\fR given. +.PP +.SH CREATEDIRECTORYPROC +.PP +Function to process a 'Tcl_FSCreateDirectory()' call. Should be +implemented unless the FS is read-only. +.PP +.CS +typedef int Tcl_FSCreateDirectoryProc( + Tcl_Obj *\fIpathPtr\fR); +.CE +.PP +The return value is a standard Tcl result indicating whether an error +occurred in the process. If successful, a new directory should have +been added to the filesystem in the location specified by +\fIpathPtr\fR. +.PP +.SH REMOVEDIRECTORYPROC +.PP +Function to process a 'Tcl_FSRemoveDirectory()' call. Should be +implemented unless the FS is read-only. +.PP +.CS +typedef int Tcl_FSRemoveDirectoryProc( + Tcl_Obj *\fIpathPtr\fR, + int \fIrecursive\fR, + Tcl_Obj **\fIerrorPtr\fR); +.CE +.PP +The return value is a standard Tcl result indicating whether an error +occurred in the process. If successful, the directory specified by +\fIpathPtr\fR should have been removed from the filesystem. If the +\fIrecursive\fR flag is given, then a non-empty directory should +be deleted without error. If an error does occur, the name of +the file or directory which caused the error should be placed in +\fIerrorPtr\fR. +.PP +.SH DELETEFILEPROC +.PP +Function to process a 'Tcl_FSDeleteFile()' call. Should be implemented +unless the FS is read-only. +.PP +.CS +typedef int Tcl_FSDeleteFileProc( + Tcl_Obj *\fIpathPtr\fR); +.CE +.PP +The return value is a standard Tcl result indicating whether an error +occurred in the process. If successful, the file specified by +\fIpathPtr\fR should have been removed from the filesystem. +.PP +.SH FILESYSTEM EFFICIENCY +.PP +.SH LSTATPROC +.PP +Function to process a 'Tcl_FSLstat()' call. If not implemented, Tcl +will attempt to use the 'statProc' defined above instead. Therefore +it need only be implemented if a filesystem can differentiate between +'stat' and 'lstat' calls. +.PP +.CS +typedef int Tcl_FSLstatProc( + Tcl_Obj *\fIpathPtr\fR, + struct stat *\fIstatPtr\fR); +.CE +.PP +The behavior of this function is very similar to that of the +Tcl_FSStatProc defined above, except that if it is applied +to a symbolic link, it returns information about the link, not +about the target file. +.PP +.SH COPYFILEPROC +.PP +Function to process a 'Tcl_FSCopyFile()' call. If not implemented Tcl +will fall back on open-r, open-w and fcopy as a copying mechanism. +Therefore it need only be implemented if the filesystem can perform +that action more efficiently. +.PP +.CS +typedef int Tcl_FSCopyFileProc( + Tcl_Obj *\fIsrcPathPtr\fR, + Tcl_Obj *\fIdestPathPtr\fR); +.CE +.PP +The return value is a standard Tcl result indicating whether an error +occurred in the copying process. Note that, \fIdestPathPtr\fR is the +name of the file which should become the copy of \fIsrcPathPtr\fR. It +is never the name of a directory into which \fIsrcPathPtr\fR could be +copied (i.e. the function is much simpler than the Tcl level 'file +copy' subcommand). +.PP +.SH RENAMEFILEPROC +.PP +Function to process a 'Tcl_FSRenameFile()' call. If not implemented, +Tcl will fall back on a copy and delete mechanism. Therefore it need +only be implemented if the filesystem can perform that action more +efficiently. +.PP +.CS +typedef int Tcl_FSRenameFileProc( + Tcl_Obj *\fIsrcPathPtr\fR, + Tcl_Obj *\fIdestPathPtr\fR); +.CE +.PP +The return value is a standard Tcl result indicating whether an error +occurred in the renaming process. +.PP +.SH COPYDIRECTORYPROC +.PP +Function to process a 'Tcl_FSCopyDirectory()' call. If not +implemented, Tcl will fall back on a recursive create-dir, file copy +mechanism. Therefore it need only be implemented if the filesystem can +perform that action more efficiently. +.PP +.CS +typedef int Tcl_FSCopyDirectoryProc( + Tcl_Obj *\fIsrcPathPtr\fR, + Tcl_Obj *\fIdestPathPtr\fR, + Tcl_Obj **\fIerrorPtr\fR); +.CE +.PP +The return value is a standard Tcl result indicating whether an error +occurred in the copying process. If an error does occur, the name of +the file or directory which caused the error should be placed in +\fIerrorPtr\fR. Note that, \fIdestPathPtr\fR is the name of the +directory-name which should become the mirror-image of +\fIsrcPathPtr\fR. It is not the name of a directory into which +\fIsrcPathPtr\fR should be copied (i.e. the function is much simpler +than the Tcl level 'file copy' subcommand). +.PP +.SH LOADFILEPROC +.PP +Function to process a 'Tcl_FSLoadFile()' call. If not implemented, Tcl +will fall back on a copy to native-temp followed by a Tcl_FSLoadFile on +that temporary copy. Therefore it need only be implemented if the +filesystem can load code directly, or to disable load functionality +entirely. +.PP +.CS +typedef int Tcl_FSLoadFileProc( + Tcl_Interp * \fIinterp\fR, + Tcl_Obj *\fIpathPtr\fR, + char * \fIsym1\fR, + char * \fIsym2\fR, + Tcl_PackageInitProc ** \fIproc1Ptr\fR, + Tcl_PackageInitProc ** \fIproc2Ptr\fR, + ClientData * \fIclientDataPtr\fR); +.CE +.PP +Returns a standard Tcl completion code. If an error occurs, an error +message is left in the interp's result. The function dynamically loads +a binary code file into memory and returns the addresses of two +procedures within that file, if they are defined. On a successful +load, the \fIclientDataPtr\fR should be filled with a token for +the dynamically loaded file which will be passed back to +the Tcl_FSUnloadFileProc to unload the file. +.PP +.SH UNLOADFILEPROC +.PP +Function to unload a previously successfully loaded file. If load was +implemented, then this should also be implemented, if there is any +cleanup action required. +.PP +.CS +typedef void Tcl_FSUnloadFileProc( + ClientData \fIclientData\fR); +.CE +.PP +.SH GETCWDPROC +.PP +Function to process a 'Tcl_FSGetCwd()' call. Most filesystems need not +implement this. It will usually only be called once, if 'getcwd' is +called before 'chdir'. May be NULL. +.PP +.CS +typedef Tcl_Obj* Tcl_FSGetCwdProc( + Tcl_Interp *\fIinterp\fR); +.CE +.PP +If the filesystem supports a native notion of a current working +directory (which might perhaps change independent of Tcl), this +function should return that cwd as the result, or NULL if the current +directory could not be determined (e.g. the user does not have +appropriate permissions on the cwd directory). If NULL is returned, an +error message is left in the interp's result. +.PP +.SH CHDIRPROC +.PP +Function to process a 'Tcl_FSChdir()' call. If filesystems do not +implement this, it will be emulated by a series of directory access +checks. Otherwise, virtual filesystems which do implement it need only +respond with a positive return result if the dirName is a valid +directory in their filesystem. They need not remember the result, +since that will be automatically remembered for use by GetCwd. Real +filesystems should carry out the correct action (i.e. call the correct +system 'chdir' api). If not implemented, then 'cd' and 'pwd' will fail +inside the filesystem. +.PP +.CS +typedef int Tcl_FSChdirProc( + Tcl_Obj *\fIpathPtr\fR); +.CE +.PP +The \fBTcl_FSChdirProc\fR changes the applications current working +directory to the value specified in \fIpathPtr\fR. The function returns +-1 on error or 0 on success. +.PP + +.SH KEYWORDS +stat access filesystem vfs + + |