New documentation for TIP#17

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
+
+