Seth Woolley's Man Viewer

Tcl_FSOpenFileChannel(3) - Tcl_AllocStatBuf, Tcl_FSAccess, Tcl_FSChdir, Tcl_FSConvertToPathType, Tcl_FSCopyDirectory, Tcl_FSCopyFile, Tcl_FSCreateDirectory, Tcl_FSData, Tcl_FSDeleteFile, Tcl_FSEqualPaths, Tcl_FSEvalFile, Tcl_FSFileAttrStrings, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileSystemInfo, Tcl_FSGetCwd, Tcl_FSGetFileSystemForPath, Tcl_FSGetInternalRep, Tcl_FSGetNativePath, Tcl_FSGetNormalizedPath, Tcl_FSGetPathType, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSJoinPath, Tcl_FSJoinToPath, Tcl_FSLink, Tcl_FSListVolumes, Tcl_FSLoadFile, Tcl_FSLstat, Tcl_FSMatchInDirectory, Tcl_FSMountsChanged, Tcl_FSNewNativePath, Tcl_FSOpenFileChannel, Tcl_FSPathSeparator, Tcl_FSRegister, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSSplitPath, Tcl_FSStat, Tcl_FSUnregister, Tcl_FSUtime - procedures to interact with any filesystem - man 3 Tcl_FSOpenFileChannel

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

Filesystem(3)               Tcl Library Procedures               Filesystem(3)



______________________________________________________________________________

NAME
       Tcl_FSRegister,   Tcl_FSUnregister,   Tcl_FSData,  Tcl_FSMountsChanged,
       Tcl_FSGetFileSystemForPath,     Tcl_FSGetPathType,      Tcl_FSCopyFile,
       Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRe-
       moveDirectory,  Tcl_FSRenameFile,  Tcl_FSListVolumes,   Tcl_FSEvalFile,
       Tcl_FSLoadFile,    Tcl_FSMatchInDirectory,   Tcl_FSLink,   Tcl_FSLstat,
       Tcl_FSUtime,  Tcl_FSFileAttrsGet,   Tcl_FSFileAttrsSet,   Tcl_FSFileAt-
       trStrings,     Tcl_FSStat,     Tcl_FSAccess,     Tcl_FSOpenFileChannel,
       Tcl_FSGetCwd,   Tcl_FSChdir,    Tcl_FSPathSeparator,    Tcl_FSJoinPath,
       Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoin-
       ToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep,  Tcl_FSGetTrans-
       latedPath,      Tcl_FSGetTranslatedStringPath,     Tcl_FSNewNativePath,
       Tcl_FSGetNativePath, Tcl_FSFileSystemInfo,  Tcl_AllocStatBuf  -  proce-
       dures to interact with any filesystem

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_FSRegister(clientData, fsPtr)

       int
       Tcl_FSUnregister(fsPtr)

       ClientData
       Tcl_FSData(fsPtr)

       void
       Tcl_FSMountsChanged(fsPtr)

       Tcl_Filesystem*
       Tcl_FSGetFileSystemForPath(pathObjPtr)

       Tcl_PathType
       Tcl_FSGetPathType(pathObjPtr)

       int
       Tcl_FSCopyFile(srcPathPtr, destPathPtr)

       int
       Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)

       int
       Tcl_FSCreateDirectory(pathPtr)

       int
       Tcl_FSDeleteFile(pathPtr)

       int
       Tcl_FSRemoveDirectory(pathPtr, int recursive, errorPtr)

       int
       Tcl_FSRenameFile(srcPathPtr, destPathPtr)

       Tcl_Obj*
       Tcl_FSListVolumes(void)

       int
       Tcl_FSEvalFile(interp, pathPtr)

       int
       Tcl_FSLoadFile(interp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr, handlePtr, unloadProcPtr)

       int
       Tcl_FSMatchInDirectory(interp, result, pathPtr, pattern, types)

       Tcl_Obj*
       Tcl_FSLink(linkNamePtr, toPtr, linkAction)

       int
       Tcl_FSLstat(pathPtr, statPtr)

       int
       Tcl_FSUtime(pathPtr, tval)

       int
       Tcl_FSFileAttrsGet(interp, int index, pathPtr, objPtrRef)

       int
       Tcl_FSFileAttrsSet(interp, int index, pathPtr, Tcl_Obj *objPtr)

       CONST char**
       Tcl_FSFileAttrStrings(pathPtr, objPtrRef)

       int
       Tcl_FSStat(pathPtr, statPtr)

       int
       Tcl_FSAccess(pathPtr, mode)

       Tcl_Channel
       Tcl_FSOpenFileChannel(interp, pathPtr, modeString, permissions)

       Tcl_Obj*
       Tcl_FSGetCwd(interp)

       int
       Tcl_FSChdir(pathPtr)

       Tcl_Obj*
       Tcl_FSPathSeparator(pathPtr)

       Tcl_Obj*
       Tcl_FSJoinPath(listObj, elements)

       Tcl_Obj*
       Tcl_FSSplitPath(pathPtr, lenPtr)

       int
       Tcl_FSEqualPaths(firstPtr, secondPtr)

       Tcl_Obj*
       Tcl_FSGetNormalizedPath(interp, pathPtr)

       Tcl_Obj*
       Tcl_FSJoinToPath(basePtr, objc, objv)

       int
       Tcl_FSConvertToPathType(interp, pathPtr)

       ClientData
       Tcl_FSGetInternalRep(pathPtr, fsPtr)

       Tcl_Obj*
       Tcl_FSGetTranslatedPath(interp, pathPtr)

       CONST char*
       Tcl_FSGetTranslatedStringPath(interp, pathPtr)

       Tcl_Obj*
       Tcl_FSNewNativePath(fsPtr, clientData)

       CONST char*
       Tcl_FSGetNativePath(pathPtr)

       Tcl_Obj*
       Tcl_FSFileSystemInfo(pathPtr)

       Tcl_StatBuf*
       Tcl_AllocStatBuf()

ARGUMENTS
       Tcl_Filesystem   *fsPtr   (in(1,8))      Points  to  a  structure containing
                                           the addresses  of  procedures  that
                                           can  be called to perform the vari-
                                           ous filesystem operations.

       Tcl_Obj          *pathPtr (in(1,8))      The path represented by this object
                                           is  used for the operation in(1,8) ques-
                                           tion.   If  the  object  does   not
                                           already  have an internal path rep-
                                           resentation, it will  be  converted
                                           to have one.

       Tcl_Obj          *srcPathPtr(in(1,8))    As  for  pathPtr,  but used for the
                                           source file(1,n) for a  copy  or  rename(1,2,n)
                                           operation.

       Tcl_Obj          *destPathPtr(in(1,8))   As  for  pathPtr,  but used for the
                                           destination filename for a copy  or
                                           rename(1,2,n) operation.

       CONST char       *pattern (in(1,8))      Only  files or directories matching
                                           this pattern will  be  returned  by
                                           Tcl_FSMatchInDirectory.

       GlobTypeData     *types   (in(1,8))      Only  files or directories matching
                                           the type descriptions contained  in(1,8)
                                           this  structure will be returned by
                                           Tcl_FSMatchInDirectory.  It is very
                                           important that the 'directory' flag
                                           is properly handled.  This  parame-
                                           ter may be NULL.

       Tcl_Interp       *interp  (in(1,8))      Interpreter   to   use  either  for
                                           results, evaluation,  or  reporting
                                           error(8,n) messages.

       ClientData       clientData(in(1,8))     The  native description of the path
                                           object to create.

       Tcl_Obj          *firstPtr(in(1,8))      The first of two  path  objects  to
                                           compare.   The  object  may be con-
                                           verted to path type.

       Tcl_Obj          *secondPtr(in(1,8))     The second of two path  objects  to
                                           compare.   The  object  may be con-
                                           verted to path type.

       Tcl_Obj          *listObj (in(1,8))      The list of path elements to  oper-
                                           ate on with a join(1,n) operation.

       int              elements (in(1,8))      If non-negative, the number of ele-
                                           ments in(1,8) the listObj  which  should
                                           be  joined  together.  If negative,
                                           then all elements are joined.

       Tcl_Obj          **errorPtr(out)    In the case  of  an  error(8,n),  filled
                                           with  an object containing the name
                                           of the file(1,n) which caused  an  error(8,n)
                                           in(1,8)  the  various copy/rename(1,2,n) opera-
                                           tions.

       Tcl_Obj          **objPtrRef(out)   Filled with  an  object  containing
                                           the result of the operation.

       Tcl_Obj          *result  (out)     Pre-allocated  object  in(1,8)  which to
                                           store (by lappending) the  list  of
                                           files or directories which are suc-
                                           cessfully        matched         in(1,8)
                                           Tcl_FSMatchInDirectory.

       int              mode     (in(1,8))      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(1,n)  exists  and   has
                                           read(2,n,1 builtins),  write(1,2)  and  execute  permis-
                                           sions,  respectively.   F_OK   just
                                           requests checking for the existence
                                           of the file.

       Tcl_StatBuf      *statPtr (out)     The  structure  that  contains  the
                                           result  of  a  stat(1,2) or lstat opera-
                                           tion.

       CONST char       *sym1    (in(1,8))      Name of a procedure to look(1,8,3 Search::Dict)  up  in(1,8)
                                           the file(1,n)'s symbol table

       CONST char       *sym2    (in(1,8))      Name  of  a procedure to look(1,8,3 Search::Dict) up in(1,8)
                                           the file(1,n)'s symbol table

       Tcl_PackageInitProc       **proc1Ptr(out)
                                           Filled with the init  function  for
                                           this code.

       Tcl_PackageInitProc       **proc2Ptr(out)
                                           Filled  with the safe-init function
                                           for this code.

       ClientData       *clientDataPtr(out)
                                           Filled with the clientData value to
                                           pass to this code's unload function
                                           when it is called.

       TclfsUnloadFileProc_      **unloadProcPtr(out)
                                           Filled with the function to use  to
                                           unload this piece of code.

       utimbuf          *tval    (in(1,8))      The  access(2,5)  and modification times
                                           in(1,8) this structure are read(2,n,1 builtins) and used
                                           to  set(7,n,1 builtins)  those  values  for a given
                                           file.

       CONST char       *modeString(in(1,8))    Specifies how the  file(1,n)  is  to  be
                                           accessed.  May have any of the val-
                                           ues allowed for the  mode  argument
                                           to the Tcl open(2,3,n) command.

       int              permissions(in(1,8))    POSIX-style  permission  flags such
                                           as 0644.  If a new file(1,n) is created,
                                           these  permissions  will  be set(7,n,1 builtins) on
                                           the created file.

       int              *lenPtr  (out)     If non-NULL, filled with the number
                                           of elements in(1,8) the split(1,n) path.

       Tcl_Obj          *basePtr (in(1,8))      The  base  path on to which to join(1,n)
                                           the given elements.  May be NULL.

       int              objc     (in(1,8))      The number of elements in(1,8) objv.

       Tcl_Obj *CONST   objv[]   (in(1,8))      The elements to join(1,n) to  the  given
                                           base path.
_________________________________________________________________


DESCRIPTION
       There  are  several  reasons for calling the Tcl_FS... functions rather
       than calling system level functions  like  access(2,5)  and  stat(1,2)  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(1,8) the system
       level calls.  Third, these function calls deal with any 'Utf  to  plat-
       form-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(5,8) filesystem aware'.  Any virtual(5,8) filesystem which has  been
       registered (through Tcl_FSRegister) may reroute file(1,n) access(2,5) to alterna-
       tive media or access(2,5) methods.  This means that all of  these  functions
       (and  therefore  the corresponding file(1,n), glob(1,3,7,n), pwd(1,n,1 builtins), cd, open(2,3,n), etc.  Tcl
       commands) may be operate on 'files' which are not native files  in(1,8)  the
       native  filesystem.   This  also  means  that  any  Tcl extension which
       accesses the filesystem through  this  API  is  automatically  'virtual(5,8)
       filesystem  aware'.   Of  course,  if(3,n)  an extension accesses the native
       filesystem directly (through platform-specific APIs, for example), then
       Tcl cannot intercept such calls.

       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 pro-
       vide a lookup table of functions to implement all or some of the  func-
       tionality  listed  here.  Finally, the Tcl_FSStat and Tcl_FSLstat calls
       abstract away from what the 'struct stat(1,2)'  buffer  buffer  is  actually
       declared  to be, allowing the same code to be used both on systems with
       and systems without support for files larger than 2GB in(1,8) size.

       The Tcl_FS... are objectified and may  cache  internal  representations
       and  other  path-related  strings (e.g. the current working directory).
       One side-effect of this is that one must not pass  in(1,8)  objects  with  a
       refCount  of  zero  to any of these functions.  If such calls were han-
       dled, they might result in(1,8) memory leaks (under some circumstances,  the
       filesystem code may wish to retain a reference to the passed in(1,8) object,
       and so one must not assume that after any of these  calls  return,  the
       object still has a refCount of zero - it may have been incremented), or
       in(1,8) a direct segfault due to the object being freed part way through the
       complex  object  manipulation required to ensure that the path is fully
       normalized and absolute for filesystem  determination.   The  practical
       lesson to learn from this is that Tcl_Obj *path = Tcl_NewStringObj(...)
       ; Tcl_FS...(path) ; Tcl_DecrRefCount(path) is wrong, and may  segfault.
       The  'path' must have its refCount incremented before passing it in(1,8), or
       decrementing it.  For this reason, objects with a refCount of zero  are
       considered  not to be valid filesystem paths and calling any Tcl_FS API
       with such an object will result in(1,8) no action being taken.

       Tcl_FSCopyFile attempts to copy the file(1,n) given  by  srcPathPtr  to  the
       path name given by destPathPtr.  If the two paths given lie in(1,8) the same
       filesystem (according to Tcl_FSGetFileSystemForPath) then that filesys-
       tem's  'copy  file(1,n)'  function is called (if(3,n) it is non-NULL).  Otherwise
       the function returns -1 and sets Tcl's errno to the 'EXDEV' posix error(8,n)
       code (which signifies a 'cross-domain link(1,2)').

       Tcl_FSCopyDirectory  attempts to copy the directory given by srcPathPtr
       to the path name given by destPathPtr.  If the two paths given  lie  in(1,8)
       the same filesystem (according to Tcl_FSGetFileSystemForPath) then that
       filesystem's 'copy file(1,n)' function is called (if(3,n) it is non-NULL).   Oth-
       erwise  the  function  returns  -1  and sets Tcl's errno to the 'EXDEV'
       posix error(8,n) code (which signifies a 'cross-domain link(1,2)').

       Tcl_FSCreateDirectory attempts to create the directory given by pathPtr
       by calling the owning filesystem's 'create directory' function.

       Tcl_FSDeleteFile  attempts to delete the file(1,n) given by pathPtr by call-
       ing the owning filesystem's 'delete file(1,n)' function.

       Tcl_FSRemoveDirectory attempts to remove the directory given by pathPtr
       by calling the owning filesystem's 'remove directory' function.

       Tcl_FSRenameFile attempts to rename(1,2,n) the file(1,n) or directory given by src-
       PathPtr to the path name given by destPathPtr.  If the two paths  given
       lie  in(1,8)  the  same filesystem (according to Tcl_FSGetFileSystemForPath)
       then that filesystem's 'rename(1,2,n) file(1,n)' function is called (if(3,n) it is  non-
       NULL).   Otherwise  the function returns -1 and sets Tcl's errno to the
       'EXDEV' posix error(8,n) code (which signifies a ``cross-domain link(1,2)'').

       Tcl_FSListVolumes calls each filesystem which has a non-NULL 'list vol-
       umes'  function and asks them to return their list of root volumes.  It
       accumulates the return values in(1,8) a list which is returned to the caller
       (with a refCount of 0).

       Tcl_FSEvalFile  reads  the file(1,n) given by pathPtr and evaluates its con-
       tents as a Tcl script.  It returns the same information as  Tcl_EvalOb-
       jEx.   If  the  file(1,n)  couldn't  be read(2,n,1 builtins) then a Tcl error(8,n) is returned to
       describe why the file(1,n) couldn't be read.  The eofchar for files is '\32'
       (^Z)  for  all  platforms.   If you require a ``^Z'' in(1,8) code for string(3,n)
       comparison, you can use ``\032'' or ``\u001a'', which  will  be  safely
       substituted by the Tcl interpreter into ``^Z''.

       Tcl_FSLoadFile  dynamically  loads  a  binary code file(1,n) into memory and
       returns the addresses of two procedures within that file(1,n), if(3,n)  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(5,8) filesystems will not, because of OS limitations
       in(1,8) dynamically loading binary code), Tcl will attempt to copy the  file(1,n)
       to a temporary directory and load(7,n) that temporary file.

       Returns  a  standard Tcl completion code.  If an error(8,n) occurs, an error(8,n)
       message is left in(1,8) the interp's result.

       Tcl_FSMatchInDirectory is used by the globbing code to search a  direc-
       tory  for all files which match a given pattern.  The appropriate func-
       tion for the filesystem to which pathPtr belongs will be called.

       The return value is a standard Tcl result indicating whether  an  error(8,n)
       occurred  in(1,8)  globbing.   Error messages are placed in(1,8) interp, but good
       results are placed in(1,8) the resultPtr given.
                         Note that the 'glob(1,3,7,n)' code implements  recursive  pat-
       terns internally, so this function will only ever be passed simple pat-
       terns, which can be matched using the logic of 'string(3,n) match'.  To han-
       dle  recursion,  Tcl will call this function frequently asking only for
       directories to be returned.

       Tcl_FSLink replaces the library version(1,3,5) of readlink(1,2)(), and  extends  it
       to  support  the  creation  of links.  The appropriate function for the
       filesystem to which linkNamePtr belongs will be called.

       If the toPtr is NULL, a readlink(1,2) action is performed.  The result is  a
       Tcl_Obj   specifying  the  contents  of  the  symbolic  link(1,2)  given  by
       linkNamePtr, or NULL if(3,n) the link(1,2) could not  be  read.   The  result  is
       owned by the caller, which should call Tcl_DecrRefCount when the result
       is no longer needed.  If the toPtr is not NULL,  Tcl  should  create  a
       link(1,2)  of  one of the types passed in(1,8) in(1,8) the linkAction flag.  This flag
       is  an  or'd  combination  of  TCL_CREATE_SYMBOLIC_LINK  and   TCL_CRE-
       ATE_HARD_LINK.   Where  a  choice  exists  (i.e.  more than one flag is
       passed in(1,8)), the Tcl convention is to prefer  symbolic  links.   When  a
       link(1,2)  is  successfully created, the return value should be toPtr (which
       is therefore already owned  by  the  caller).   If  unsuccessful,  NULL
       should be returned.

       Tcl_FSLstat fills the stat(1,2) structure statPtr with information about the
       specified file.  You do not need any access(2,5) rights to the file(1,n)  to  get
       this information but you need search rights to all directories named(5,8) in(1,8)
       the path leading to the file.  The stat(1,2) structure includes info(1,5,n) regard-
       ing  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(2,5) time(1,2,n),
       last modification time(1,2,n), and creation time.

       If path exists, Tcl_FSLstat returns 0 and the stat(1,2) structure is  filled
       with data.  Otherwise, -1 is returned, and no stat(1,2) info(1,5,n) is given.

       Tcl_FSUtime replaces the library version(1,3,5) of utime.

       For  results  see  'utime'  documentation.  If successful, the function
       will update(7,n) the 'atime' and 'mtime' values of the file(1,n) given.

       Tcl_FSFileAttrsGet  implements  read(2,n,1 builtins)  access(2,5)  for  the  hookable  'file(1,n)
       attributes' subcommand.  The appropriate function for the filesystem to
       which pathPtr belongs will be called.

       If the result is TCL_OK, then an object was placed in(1,8) objPtrRef,  which
       will only be temporarily valid (unless Tcl_IncrRefCount is called).

       Tcl_FSFileAttrsSet  implements  write(1,2)  access(2,5)  for  the  hookable 'file(1,n)
       attributes' subcommand.  The appropriate function for the filesystem to
       which pathPtr belongs will be called.

       Tcl_FSFileAttrStrings implements part of the hookable 'file(1,n) attributes'
       subcommand.  The appropriate function for the filesystem to which path-
       Ptr belongs will be called.

       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(3,n)
       the  list should be disposed of by Tcl when done, it should have a ref-
       Count of zero, and if(3,n) the list should not be disposed of, the  filesys-
       tem should ensure it retains a refCount on the object.

       Tcl_FSAccess checks whether the process would be allowed to read(2,n,1 builtins), write(1,2)
       or test for existence of the file(1,n) (or other file(1,n) system  object)  whose
       name  is  pathname.   If pathname is a symbolic link(1,2) on Unix, then per-
       missions of the file(1,n) referred by this symbolic link(1,2) are tested.

       On success (all requested permissions granted), zero is  returned.   On
       error(8,n)  (at least one bit in(1,8) mode asked for a permission that is denied,
       or some other  error(8,n) occurred), -1 is returned.

       Tcl_FSStat fills the stat(1,2) structure statPtr with information about  the
       specified  file.   You do not need any access(2,5) rights to the file(1,n) to get
       this information but you need search rights to all directories named(5,8) in(1,8)
       the path leading to the file.  The stat(1,2) structure includes info(1,5,n) regard-
       ing 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(2,5)  time(1,2,n),
       last modification time(1,2,n), and creation time.

       If  path  exists, Tcl_FSStat returns 0 and the stat(1,2) structure is filled
       with data.  Otherwise, -1 is returned, and no stat(1,2) info(1,5,n) is given.

       Tcl_FSOpenFileChannel opens a file(1,n) specified by pathPtr and  returns  a
       channel  handle  that  can  be  used to perform input and output on the
       file. This API is modeled after the fopen procedure of the  Unix  stan-
       dard  I/O  library.  The syntax and meaning of all arguments is similar
       to those given in(1,8) the Tcl open(2,3,n) command when  opening  a  file.   If  an
       error(8,n)  occurs  while opening the channel, Tcl_FSOpenFileChannel returns
       NULL and records  a  POSIX  error(8,n)  code  that  can  be  retrieved  with
       Tcl_GetErrno.   In addition, if(3,n) interp is non-NULL, Tcl_FSOpenFileChan-
       nel leaves an error(8,n) message in(1,8) interp's result after any error.

       The newly created channel is not  registered  in(1,8)  the  supplied  inter-
       preter;  to  register it, use Tcl_RegisterChannel, described below.  If
       one of the standard channels, stdin, stdout or  stderr  was  previously
       closed,  the  act  of  creating  the  new  channel also assigns it as a
       replacement for the standard channel.

       Tcl_FSGetCwd replaces the library version(1,3,5) of getcwd().

       It returns the Tcl library's current working directory.   This  may  be
       different  to  the native platform's working directory, in(1,8) the case for
       which the cwd is not in(1,8) the native filesystem.

       The result is a pointer to a Tcl_Obj specifying the current  directory,
       or  NULL  if(3,n) the current directory could not be determined.  If NULL is
       returned,  an  error(8,n)  message  is  left   in(1,8)   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 mul-
       tiple threads to access(2,5) this and related functions, while ensuring  the
       results are always valid.

       Tcl_FSChdir  replaces the library version(1,3,5) of chdir().  The path is nor-
       malized 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(1,2) and access(2,5) to check whether  the  directory  exists
       and has appropriate permissions.

       For  results,  see  chdir()  documentation.   If  successful, we keep a
       record of the successful path in(1,8) cwdPathPtr  for  subsequent  calls  to
       getcwd.

       Tcl_FSPathSeparator 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).

       The separator is returned as a Tcl_Obj containing a string(3,n) of length 1.
       If the path is invalid, NULL is returned.

       Tcl_FSJoinPath 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.

       Returns object with refCount of zero, containing the joined path.

       Tcl_FSSplitPath  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.

       Returns  list object with refCount of zero.  If the passed in(1,8) lenPtr is
       non-NULL, we use it to return the number of elements  in(1,8)  the  returned
       list.

       Tcl_FSEqualPaths  tests  whether the two paths given represent the same
       filesystem object

       It returns 1 if(3,n) the paths are equal, and 0 if(3,n) they are  different.   If
       either path is NULL, 0 is always returned.

       Tcl_FSGetNormalizedPath  this  important  function  attempts to extract
       from the given Tcl_Obj a unique normalized path  representation,  whose
       string(3,n) value can be used as a unique identifier for the file.

       It  returns  the normalized path object, with refCount of zero, or NULL
       if(3,n) the path was invalid or could otherwise  not  be  successfully  con-
       verted.   Extraction  of  absolute,  normalized paths is very efficient
       (because the filesystem operates on these representations  internally),
       although  the  result  when  the  filesystem contains numerous symbolic
       links may not be the most user-friendly version(1,3,5) of a path.

       Tcl_FSJoinToPath takes the given object,  which  should  usually  be  a
       valid  path  or  NULL,  and  joins  onto it the array of paths segments
       given.

       Returns object with refCount of zero, containing the joined path.

       Tcl_FSConvertToPathType 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(3,n) 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).

       If the conversion succeeds (i.e. the object is a valid path in(1,8)  one  of
       the current filesystems), then TCL_OK is returned.  Otherwise TCL_ERROR
       is returned, and an error(8,n) message may be left in(1,8) the interpreter.

       Tcl_FSGetInternalRep extracts the internal representation  of  a  given
       path  object, in(1,8) 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
       Tcl_FSCreateInternalRepProc.

       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.

       Tcl_FSGetTranslatedPath attempts to extract the  translated  path  from
       the given Tcl_Obj.

       If  the translation succeeds (i.e. the object is a valid path), then it
       is returned.  Otherwise NULL will be returned, and an error(8,n) message may
       be  left in(1,8) the interpreter.  A "translated" path is one which contains
       no "~" or "~user" sequences (these have been expanded to their  current
       representation in(1,8) the filesystem).  The object returned is owned by the
       caller, which must store it or call Tcl_DecrRefCount to  ensure  memory
       is  freed.  This function is of little practical use, and Tcl_FSGetNor-
       malizedPath or Tcl_GetNativePath are usually better  functions  to  use
       for most purposes.

       Tcl_FSGetTranslatedStringPath does the same as Tcl_FSGetTranslatedPath,
       but returns a character string(3,n) or NULL.  The string(3,n) returned is dynami-
       cally  allocated  and  owned by the caller, which must store it or call
       ckfree to  ensure  it  is  freed.   Again,  Tcl_FSGetNormalizedPath  or
       Tcl_GetNativePath  are  usually  better  functions to use for most pur-
       poses.

       Tcl_FSNewNativePath performs something like that reverse of  the  usual
       obj->path->nativerep  conversions.   If  some  code retrieves a path in(1,8)
       native form (from, e.g. readlink(1,2) or a native dialog(1,3,n)), 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.

       The resulting object is a pure 'path' object, which will only receive a
       Utf-8 string(3,n) representation if(3,n) that is required by some Tcl code.

       Tcl_FSGetNativePath  is  for  use by the Win/Unix/MacOS native filesys-
       tems, so that they can easily retrieve the  native  (char*  or  TCHAR*)
       representation  of  a  path.   This  function  is a convenience wrapper
       around Tcl_FSGetInternalRep, and assumes the native  representation  is
       string-based.   It  may  be desirable in(1,8) the future to have non-string-
       based native representations (for example, on MacOS,  a  representation
       using  a fileSpec of FSRef structure would probably be more efficient).
       On Windows a full Unicode  representation  would  allow  for  paths  of
       unlimited  length.   Currently the representation is simply a character
       string(3,n) containing the complete, absolute path in(1,8) the native encoding.

       The native representation is cached so  that  repeated  calls  to  this
       function will not require additional conversions.

       Tcl_FSFileSystemInfo 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  sec-
       ond  element  may be empty if(3,n) the filesystem does not provide a further
       categorization of files.

       A valid list object is returned, unless the path object is  not  recog-
       nized, when NULL will be returned.

       Tcl_FSGetFileSystemForPath  returns the a pointer to the Tcl_Filesystem
       which accepts this path as valid.

       If no filesystem will accept(2,8) the path, NULL is returned.

       Tcl_FSGetPathType determines whether the given path is relative to  the
       current directory, relative to the current volume, or absolute.

       It    returns   one   of   TCL_PATH_ABSOLUTE,   TCL_PATH_RELATIVE,   or
       TCL_PATH_VOLUME_RELATIVE

       Tcl_AllocStatBuf allocates a Tcl_StatBuf on the system heap (which  may
       be  deallocated  by being passed to ckfree.)  This allows extensions to
       invoke Tcl_FSStat and Tcl_FSLStat without being dependent on  the  size
       of the buffer.  That in(1,8) turn depends on the flags used to build Tcl.


TCL_FILESYSTEM
       A filesystem provides a Tcl_Filesystem 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 gen-
       erally occurs through the functions listed above.

       The Tcl_Filesystem structures are manipulated using the following meth-
       ods.

       Tcl_FSRegister  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(3,n) the same filesystem is registered multiple times (and in(1,8)
       general that is not a good thing to do).  TCL_OK will be returned.

       Tcl_FSUnregister removes the given filesystem structure from  the  list
       of  known  filesystems,  if(3,n)  it  is  known, and returns TCL_OK.  If the
       filesystem is not currently registered, TCL_ERROR is returned.

       Tcl_FSData  will  return  the  ClientData  associated  with  the  given
       filesystem, if(3,n) that filesystem is registered.  Otherwise it will return
       NULL.

       Tcl_FSMountsChanged is used to inform the Tcl's core that  the  set(7,n,1 builtins)  of
       mount(2,8)  points  for  the  given  (already  registered)  filesystem  have
       changed, and that cached file(1,n) representations may therefore  no  longer
       be correct.

       The Tcl_Filesystem structure contains the following fields:
              typedef struct Tcl_Filesystem {
                  CONST char *typeName;
                  int structureLength;
                  Tcl_FSVersion version(1,3,5);
                  Tcl_FSPathInFilesystemProc *pathInFilesystemProc;
                  Tcl_FSDupInternalRepProc *dupInternalRepProc;
                  Tcl_FSFreeInternalRepProc *freeInternalRepProc;
                  Tcl_FSInternalToNormalizedProc *internalToNormalizedProc;
                  Tcl_FSCreateInternalRepProc *createInternalRepProc;
                  Tcl_FSNormalizePathProc *normalizePathProc;
                  Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc;
                  Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc;
                  Tcl_FSStatProc *statProc;
                  Tcl_FSAccessProc *accessProc;
                  Tcl_FSOpenFileChannelProc *openFileChannelProc;
                  Tcl_FSMatchInDirectoryProc *matchInDirectoryProc;
                  Tcl_FSUtimeProc *utimeProc;
                  Tcl_FSLinkProc *linkProc;
                  Tcl_FSListVolumesProc *listVolumesProc;
                  Tcl_FSFileAttrStringsProc *fileAttrStringsProc;
                  Tcl_FSFileAttrsGetProc *fileAttrsGetProc;
                  Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
                  Tcl_FSCreateDirectoryProc *createDirectoryProc;
                  Tcl_FSRemoveDirectoryProc *removeDirectoryProc;
                  Tcl_FSDeleteFileProc *deleteFileProc;
                  Tcl_FSCopyFileProc *copyFileProc;
                  Tcl_FSRenameFileProc *renameFileProc;
                  Tcl_FSCopyDirectoryProc *copyDirectoryProc;
                  Tcl_FSLstatProc *lstatProc;
                  Tcl_FSLoadFileProc *loadFileProc;
                  Tcl_FSGetCwdProc *getCwdProc;
                  Tcl_FSChdirProc *chdirProc;
              } Tcl_Filesystem;

       Except  for the first three fields in(1,8) this structure which contain sim-
       ple data elements, all entries contain addresses of functions called by
       the  generic filesystem layer to perform the complete range of filesys-
       tem related actions.

       The many functions in(1,8) this structure are broken down into  three  cate-
       gories:  infrastructure  functions  (almost all of which must be imple-
       mented), operational functions (which must be implemented if(3,n) a complete
       filesystem  is  provided), and efficiency functions (which need only be
       implemented if(3,n) they can be done so efficiently, or if(3,n) they  have  side-
       effects  which  are  required by the filesystem; Tcl has less(1,3) efficient
       emulations it can fall back on).  It is important to note that, in(1,8)  the
       current version(1,3,5) of Tcl, most of these fallbacks are only used to handle
       commands initiated in(1,8) Tcl, not in(1,8) C. What this  means  is,  that  if(3,n)  a
       'file(1,n)  rename(1,2,n)' command is issued in(1,8) Tcl, and the relevant filesystem(s)
       do not implement their Tcl_FSRenameFileProc, Tcl's  core  will  instead
       fallback  on  a  combination of other filesystem functions (it will use
       Tcl_FSCopyFileProc followed by Tcl_FSDeleteFileProc, and if(3,n) Tcl_FSCopy-
       FileProc  is not implemented there is a further fallback).  However, if(3,n)
       a Tcl_FSRenameFile command is issued at the C level, no such  fallbacks
       occur.  This is true except for the last four entries in(1,8) the filesystem
       table (lstat, load(7,n), getcwd and chdir) for which fallbacks  do  in(1,8)  fact
       occur at the C level.

       As  an  example,  here is the filesystem lookup table used by the "vfs"
       extension which allows filesystem actions to be implemented in(1,8) Tcl.
              static Tcl_Filesystem vfsFilesystem = {
                  "tclvfs",
                  sizeof(Tcl_Filesystem),
                  TCL_FILESYSTEM_VERSION_1,
                  &VfsPathInFilesystem,
                  &VfsDupInternalRep,
                  &VfsFreeInternalRep,
                  /* No internal to normalized, since we don't create any
                   * pure 'internal' Tcl_Obj path representations */
                  NULL,
                  /* No create native rep function, since we don't use it
                   * and don't choose to support uses of 'Tcl_FSNewNativePath' */
                  NULL,
                  /* Normalize path isn't needed - we assume paths only have
                   * one representation */
                  NULL,
                  &VfsFilesystemPathType,
                  &VfsFilesystemSeparator,
                  &VfsStat,
                  &VfsAccess,
                  &VfsOpenFileChannel,
                  &VfsMatchInDirectory,
                  &VfsUtime,
                  /* We choose not to support symbolic links inside our vfs's */
                  NULL,
                  &VfsListVolumes,
                  &VfsFileAttrStrings,
                  &VfsFileAttrsGet,
                  &VfsFileAttrsSet,
                  &VfsCreateDirectory,
                  &VfsRemoveDirectory,
                  &VfsDeleteFile,
                  /* No copy file(1,n) - fallback will occur at Tcl level */
                  NULL,
                  /* No rename(1,2,n) file(1,n) - fallback will occur at Tcl level */
                  NULL,
                  /* No copy directory - fallback will occur at Tcl level */
                  NULL,
                  /* Core will use stat(1,2) for lstat */
                  NULL,
                  /* No load(7,n) - fallback on core implementation */
                  NULL,
                  /* We don't need a getcwd or chdir - fallback on Tcl's versions */
                  NULL,
                  NULL
              };

       Any functions which take path names in(1,8) Tcl_Obj form take those names in(1,8)
       UTF-8  form.   The filesystem infrastructure API is designed to support
       efficient, cached conversion of these UTF-8 paths to other native  rep-
       resentations.

TYPENAME
       The  typeName  field  contains a null-terminated string(3,n) that identifies
       the type of the filesystem implemented, e.g.  native or zip or vfs.


STRUCTURE LENGTH
       The    structureLength    field    is    generally    implemented    as
       sizeof(Tcl_Filesystem),  and  is there to allow easier binary backwards
       compatibility if(3,n) the size of the structure  changes  in(1,8)  a  future  Tcl
       release.

VERSION
       The version(1,3,5) field should be set(7,n,1 builtins) to TCL_FILESYSTEM_VERSION_1.

FILESYSTEM INFRASTRUCTURE
       These fields contain addresses of functions which are used to associate
       a particular filesystem with a file(1,n) path, and deal  with  the  internal
       handling  of path representations, for example copying and freeing such
       representations.

PATHINFILESYSTEMPROC
       The pathInFilesystemProc 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 func-
       tions  with a path for which this function has returned TCL_OK.  If the
       path does not belong, -1 should be returned (the behaviour of  Tcl  for
       any  other  return  value is not defined).  If TCL_OK is returned, then
       the optional clientDataPtr 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.

              typedef int Tcl_FSPathInFilesystemProc(
                Tcl_Obj *pathPtr,
                ClientData *clientDataPtr);

DUPINTERNALREPPROC
       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.

              typedef ClientData Tcl_FSDupInternalRepProc(
                ClientData clientData);

FREEINTERNALREPPROC
       Free the internal representation.  This must be implemented if(3,n) internal
       representations need freeing (i.e. if(3,n) some memory is allocated when  an
       internal representation is generated), but may otherwise be NULL.

              typedef void Tcl_FSFreeInternalRepProc(
                ClientData clientData);

INTERNALTONORMALIZEDPROC
       Function to convert internal representation to a normalized path.  Only
       required  if(3,n)  the  filesystem  creates  pure  path  objects   with   no
       string(3,n)/path  representation.   The  return  value is a Tcl object whose
       string(3,n) representation is the normalized path.

              typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
                ClientData clientData);

CREATEINTERNALREPPROC
       Function to take a path object, and calculate an  internal  representa-
       tion  for  it, and store that native representation in(1,8) the object.  May
       be  NULL  if(3,n)  paths  have  no  internal  representation,  or   if(3,n)   the
       Tcl_FSPathInFilesystemProc  for this filesystem always immediately cre-
       ates an internal representation for paths it accepts.

              typedef ClientData Tcl_FSCreateInternalRepProc(
                Tcl_Obj *pathPtr);

NORMALIZEPATHPROC
       Function to normalize a path.  Should be implemented for  all  filesys-
       tems  which  can have multiple string(3,n) representations for the same path
       object.  In Tcl, every 'path' must have a  single  unique  'normalized'
       string(3,n)  representation.  Depending on the filesystem, there may be more
       than one unnormalized string(3,n) representation which refers to  that  path
       (e.g.  a  relative  path,  a  path with different character case if(3,n) the
       filesystem is case insensitive, a path contain a reference  to  a  home
       directory  such as '~', a path containing symbolic links, etc).  If the
       very last component in(1,8) the path is a symbolic link(1,2), it  should  not  be
       converted  into  the object it points to (but its case or other aspects
       should be made unique).  All other path components should be  converted
       from  symbolic  links.   This  one  exception is required to agree with
       Tcl's semantics with 'file(1,n) delete', 'file(1,n) rename(1,2,n)', 'file(1,n) copy'  operat-
       ing  on  symbolic  links.  This function may be called with 'nextCheck-
       point' either at the beginning of the path (i.e. zero), at the  end  of
       the  path,  or at any intermediate file(1,n) separator in(1,8) the path.  It will
       never point to any other arbitrary position in(1,8) the path. In the last of
       the  three  valid cases, the implementation can assume that the path up
       to and including the file(1,n) separator is known and normalized.

              typedef int Tcl_FSNormalizePathProc(
                Tcl_Interp *interp,
                Tcl_Obj *pathPtr,
                int nextCheckpoint);

FILESYSTEM OPERATIONS
       The fields in(1,8) this section of the structure contain addresses of  func-
       tions which are called to carry out the basic filesystem operations.  A
       filesystem which expects to be used with the complete standard Tcl com-
       mand  set(7,n,1 builtins)  must implement all of these.  If some of them are not imple-
       mented, then certain Tcl commands may  fail  when  operating  on  paths
       within  that filesystem.  However, in(1,8) some instances this may be desir-
       able (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(1,2) function, etc.  The  Tcl  core  expects
       filesystems to behave in(1,8) this way).

FILESYSTEMPATHTYPEPROC
       Function  to  determine  the type of a path in(1,8) this filesystem.  May be
       NULL, in(1,8) which case no type information will be available to  users(1,5)  of
       the  filesystem.   The  'type' is used only for informational purposes,
       and should be returned as the  string(3,n)  representation  of  the  Tcl_Obj
       which  is returned.  A typical return value might be "networked", "zip"
       or "ftp".  The Tcl_Obj result is owned by the  filesystem  and  so  Tcl
       will  increment  the  refCount  of that object if(3,n) it wishes to retain a
       reference to it.

              typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc(
                Tcl_Obj *pathPtr);

FILESYSTEMSEPARATORPROC
       Function to return the  separator  character(s)  for  this  filesystem.
       Must  be  implemented,  otherwise  the  file(1,n) separator command will not
       function correctly.  The usual return value will be a Tcl_Obj  contain-
       ing the string(3,n) "/".

              typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
                Tcl_Obj *pathPtr);

STATPROC
       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(1,n) atime, file(1,n) isdirectory, file(1,n) size, glob(1,3,7,n)).

              typedef int Tcl_FSStatProc(
                Tcl_Obj *pathPtr,
                Tcl_StatBuf *statPtr);

       The  Tcl_FSStatProc  fills  the stat(1,2) structure statPtr with information
       about the specified file.  You do not need any  access(2,5)  rights  to  the
       file(1,n) to get this information but you need search rights to all directo-
       ries named(5,8) in(1,8) the  path  leading  to  the  file.   The  stat(1,2)  structure
       includes  info(1,5,n) 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(2,5) time(1,2,n), last modification time(1,2,n), and creation time.

       If the file(1,n) represented by pathPtr exists, the Tcl_FSStatProc returns 0
       and the stat(1,2) structure is filled with data.  Otherwise, -1 is returned,
       and no stat(1,2) info(1,5,n) is given.

ACCESSPROC
       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(1,n) exists, file(1,n) readable).

              typedef int Tcl_FSAccessProc(
                Tcl_Obj *pathPtr,
                int mode);

       The Tcl_FSAccessProc checks whether the process  would  be  allowed  to
       read(2,n,1 builtins),  write(1,2)  or  test  for existence of the file(1,n) (or other file(1,n) system
       object) whose name is pathname.  If pathname is a symbolic  link(1,2),  then
       permissions  of  the  file(1,n)  referred  by  this  symbolic link(1,2) should be
       tested.

       On success (all requested permissions granted), zero is  returned.   On
       error(8,n)  (at least one bit in(1,8) mode asked for a permission that is denied,
       or some other  error(8,n) occurred), -1 is returned.


OPENFILECHANNELPROC
       Function to process a Tcl_FSOpenFileChannel()  call.   Must  be  imple-
       mented  for  any  reasonable  filesystem,  since  any  operations which
       require open(2,3,n) or accessing a file(1,n)'s contents will  use  it  (e.g.  open(2,3,n),
       encoding(3,n), and many Tk commands).

              typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
                Tcl_Interp *interp,
                Tcl_Obj *pathPtr,
                int mode,
                int permissions);

       The  Tcl_FSOpenFileChannelProc  opens  a  file(1,n) specified by pathPtr and
       returns a channel handle that can be used to perform input  and  output
       on the file.  This API is modeled after the fopen procedure of the Unix
       standard I/O library.  The syntax and meaning of all arguments is simi-
       lar  to  those given in(1,8) the Tcl open(2,3,n) command when opening a file(1,n), where
       the mode argument  is  a  combination  of  the  POSIX  flags  O_RDONLY,
       O_WRONLY,  etc.   If  an  error(8,n)  occurs  while opening the channel, the
       Tcl_FSOpenFileChannelProc returns NULL and records a POSIX  error(8,n)  code
       that  can  be  retrieved  with Tcl_GetErrno.  In addition, if(3,n) interp is
       non-NULL, the Tcl_FSOpenFileChannelProc  leaves  an  error(8,n)  message  in(1,8)
       interp's result after any error.

       The  newly  created  channel  is  not registered in(1,8) the supplied inter-
       preter; to register it, use Tcl_RegisterChannel. If one of the standard
       channels,  stdin,  stdout  or  stderr was previously closed, the act of
       creating the new channel also assigns it as a replacement for the stan-
       dard channel.

MATCHINDIRECTORYPROC
       Function  to  process  a  Tcl_FSMatchInDirectory() call.  If not imple-
       mented, then glob(1,3,7,n) and recursive copy functionality will be  lacking  in(1,8)
       the  filesystem  (and  this  may  impact commands like 'encoding(3,n) names'
       which use glob(1,3,7,n) functionality internally).

              typedef int Tcl_FSMatchInDirectoryProc(
                Tcl_Interp* interp,
                Tcl_Obj *result,
                Tcl_Obj *pathPtr,
                CONST char *pattern,
                Tcl_GlobTypeData * types);

       The function should return all files or directories (or other  filesys-
       tem  objects)  which  match the given pattern and accord with the types
       specification given.  There are two ways in(1,8) which this function may  be
       called.   If pattern is NULL, then pathPtr is a full path specification
       of a single file(1,n) or directory which should be checked for existence and
       correct type.  Otherwise, pathPtr is a directory, the contents of which
       the function should search for files or directories which have the cor-
       rect  type.  In either case, pathPtr can be assumed to be both non-NULL
       and non-empty.  It is not currently  documented  whether  pathPtr  will
       have  a file(1,n) separator at its end of not, so code should be flexible to
       both possibilities.

       The return value is a standard Tcl result indicating whether  an  error(8,n)
       occurred in(1,8) the matching process.  Error messages are placed in(1,8) interp,
       but on a TCL_OK result, the interpreter should  not  be  modified,  but
       rather results should be added to the result object given (which can be
       assumed to be a valid Tcl list).  The matches added  to  result  should
       include  any path prefix given in(1,8) pathPtr (this usually means they will
       be absolute path specifications).  Note that if(3,n) no matches  are  found,
       that  simply  leads to an empty result --- errors are only signaled for
       actual file(1,n) or filesystem problems which may occur during the  matching
       process.

UTIMEPROC
       Function  to  process  a Tcl_FSUtime() call.  Required to allow setting
       (not reading) of times with 'file(1,n) mtime', 'file(1,n) atime'  and  the  open-
       r/open-w/fcopy implementation of 'file(1,n) copy'.

              typedef int Tcl_FSUtimeProc(
                Tcl_Obj *pathPtr,
                struct utimbuf *tval);

       The  access(2,5)  and  modification  times  of the file(1,n) specified by pathPtr
       should be changed to the values given in(1,8) the tval structure.

       The return value is a standard Tcl result indicating whether  an  error(8,n)
       occurred in(1,8) the process.

LINKPROC
       Function to process a Tcl_FSLink() call.  Should be implemented only if(3,n)
       the filesystem supports links, and may otherwise be NULL.

              typedef Tcl_Obj* Tcl_FSLinkProc(
                Tcl_Obj *linkNamePtr,
                Tcl_Obj *toPtr,
                int linkAction);

       If toPtr is NULL, the function is being asked to read(2,n,1 builtins) the contents of a
       link.   The  result  is  a  Tcl_Obj specifying the contents of the link(1,2)
       given by linkNamePtr, or NULL if(3,n) the  link(1,2)  could  not  be  read.   The
       result  is owned by the caller, which should call Tcl_DecrRefCount when
       the result is no longer needed.  If toPtr is  not  NULL,  the  function
       should  attempt  to  create  a link.  The result in(1,8) this case should be
       toPtr if(3,n) the link(1,2) was successful and NULL otherwise.  In this case  the
       result is not owned by the caller. See the documentation for Tcl_FSLink
       for the correct interpretation of the linkAction flags.

LISTVOLUMESPROC
       Function to list any  filesystem  volumes  added  by  this  filesystem.
       Should  be  implemented only if(3,n) the filesystem adds volumes at the head
       of the filesystem, so that they can be returned by 'file(1,n) volumes'.

              typedef Tcl_Obj* Tcl_FSListVolumesProc(void);

       The result should be a list of volumes added  by  this  filesystem,  or
       NULL  (or an empty list) if(3,n) no volumes are provided.  The result object
       is considered to be owned by the filesystem (not by  Tcl's  core),  but
       should  be  given a refCount for Tcl.  Tcl will use the contents of the
       list and then decrement that  refCount.   This  allows  filesystems  to
       choose  whether they actually want to retain a 'master(5,8) list' of volumes
       or not (if(3,n) not, they generate the list on the fly and pass  it  to  Tcl
       with  a refCount of 1 and then forget about the list, if(3,n) yes, then they
       simply increment the refCount of their master(5,8) list and pass it  to  Tcl
       which will copy the contents and then decrement the count back to where
       it was).

       Therefore, Tcl considers return values from this proc(5,n) to be  read-only.


FILEATTRSTRINGSPROC
       Function  to  list  all  attribute  strings  which  are  valid for this
       filesystem.  If not implemented the filesystem  will  not  support  the
       file(1,n)  attributes command.  This allows arbitrary additional information
       to be attached to files in(1,8) the filesystem.  If it is  not  implemented,
       there is no need to implement the get and set(7,n,1 builtins) methods.

              typedef CONST char** Tcl_FSFileAttrStringsProc(
                Tcl_Obj *pathPtr,
                Tcl_Obj** objPtrRef);

       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(3,n)
       the  list should be disposed of by Tcl when done, it should have a ref-
       Count of zero, and if(3,n) the list should not be disposed of, the  filesys-
       tem should ensure it retains a refCount on the object.

FILEATTRSGETPROC
       Function   to  process  a  Tcl_FSFileAttrsGet()  call,  used  by  'file(1,n)
       attributes'.

              typedef int Tcl_FSFileAttrsGetProc(
                Tcl_Interp *interp,
                int index,
                Tcl_Obj *pathPtr,
                Tcl_Obj **objPtrRef);

       Returns a standard Tcl return code.   The  attribute  value  retrieved,
       which  corresponds  to the index'th element in(1,8) the list returned by the
       Tcl_FSFileAttrStringsProc, is a Tcl_Obj placed in(1,8) objPtrRef (if(3,n)  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.

FILEATTRSSETPROC
       Function   to  process  a  Tcl_FSFileAttrsSet()  call,  used  by  'file(1,n)
       attributes'.  If the filesystem is  read-only,  there  is  no  need  to
       implement this.

              typedef int Tcl_FSFileAttrsSetProc(
                Tcl_Interp *interp,
                int index,
                Tcl_Obj *pathPtr,
                Tcl_Obj *objPtr);

       The attribute value of the index'th element in(1,8) the list returned by the
       Tcl_FSFileAttrStringsProc should be set(7,n,1 builtins) to the objPtr given.

CREATEDIRECTORYPROC
       Function to process a Tcl_FSCreateDirectory() call.  Should  be  imple-
       mented unless the FS is read-only.

              typedef int Tcl_FSCreateDirectoryProc(
                Tcl_Obj *pathPtr);

       The  return  value is a standard Tcl result indicating whether an error(8,n)
       occurred in(1,8) the process.  If successful, a new  directory  should  have
       been added to the filesystem in(1,8) the location specified by pathPtr.

REMOVEDIRECTORYPROC
       Function to process a 'Tcl_FSRemoveDirectory()' call.  Should be imple-
       mented unless the FS is read-only.

              typedef int Tcl_FSRemoveDirectoryProc(
                Tcl_Obj *pathPtr,
                int recursive,
                Tcl_Obj **errorPtr);

       The return value is a standard Tcl result indicating whether  an  error(8,n)
       occurred  in(1,8)  the  process.   If successful, the directory specified by
       pathPtr should have been removed from the filesystem.  If the recursive
       flag  is  given,  then  a non-empty directory should be deleted without
       error.  If an error(8,n) does occur, the name of the file(1,n) or directory which
       caused the error(8,n) should be placed in(1,8) errorPtr.

DELETEFILEPROC
       Function  to  process a Tcl_FSDeleteFile() call.  Should be implemented
       unless the FS is read-only.

              typedef int Tcl_FSDeleteFileProc(
                Tcl_Obj *pathPtr);

       The return value is a standard Tcl result indicating whether  an  error(8,n)
       occurred  in(1,8) the process.  If successful, the file(1,n) specified by pathPtr
       should have been removed  from  the  filesystem.   Note  that,  if(3,n)  the
       filesystem  supports symbolic links, Tcl will always call this function
       and not Tcl_FSRemoveDirectoryProc when needed to delete them  (even  if(3,n)
       they are symbolic links to directories).

FILESYSTEM EFFICIENCY
LSTATPROC
       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(3,n) a filesystem can differentiate between stat(1,2) and
       lstat calls.

              typedef int Tcl_FSLstatProc(
                Tcl_Obj *pathPtr,
                Tcl_StatBuf *statPtr);

       The  behavior  of  this  function  is  very  similar  to  that  of  the
       Tcl_FSStatProc  defined  above,  except that if(3,n) it is applied to a sym-
       bolic link(1,2), it returns information about the link(1,2), not about the target
       file.


COPYFILEPROC
       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(3,n) the filesystem can perform
       that action more efficiently.

              typedef int Tcl_FSCopyFileProc(
                Tcl_Obj *srcPathPtr,
                Tcl_Obj *destPathPtr);

       The return value is a standard Tcl result indicating whether  an  error(8,n)
       occurred in(1,8) the copying process.  Note that, destPathPtr is the name of
       the file(1,n) which should become the copy of srcPathPtr. It  is  never  the
       name  of  a  directory  into which srcPathPtr could be copied (i.e. the
       function is much simpler than the Tcl level  'file(1,n)  copy'  subcommand).
       Note  that,  if(3,n) the filesystem supports symbolic links, Tcl will always
       call this function and not Tcl_FSCopyDirectoryProc when needed to  copy
       them (even if(3,n) they are symbolic links to directories).

RENAMEFILEPROC
       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(3,n)  the  filesystem can perform that action more effi-
       ciently.

              typedef int Tcl_FSRenameFileProc(
                Tcl_Obj *srcPathPtr,
                Tcl_Obj *destPathPtr);

       The return value is a standard Tcl result indicating whether  an  error(8,n)
       occurred in(1,8) the renaming process.

COPYDIRECTORYPROC
       Function  to process a Tcl_FSCopyDirectory() call.  If not implemented,
       Tcl will fall back on a  recursive  create-dir,  file(1,n)  copy  mechanism.
       Therefore  it  need  only  be implemented if(3,n) the filesystem can perform
       that action more efficiently.

              typedef int Tcl_FSCopyDirectoryProc(
                Tcl_Obj *srcPathPtr,
                Tcl_Obj *destPathPtr,
                Tcl_Obj **errorPtr);

       The return value is a standard Tcl result indicating whether  an  error(8,n)
       occurred  in(1,8)  the copying process.  If an error(8,n) does occur, the name of
       the file(1,n) or directory which  caused  the  error(8,n)  should  be  placed  in(1,8)
       errorPtr.  Note  that,  destPathPtr  is  the name of the directory-name
       which should become the mirror-image of srcPathPtr. It is not the  name
       of  a  directory into which srcPathPtr should be copied (i.e. the func-
       tion is much simpler than the Tcl level 'file(1,n) copy' subcommand).

LOADFILEPROC
       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(3,n)  the
       filesystem  can  load(7,n) code directly, or it can be implemented simply to
       return TCL_ERROR to  disable  load(7,n)  functionality  in(1,8)  this  filesystem
       entirely.

              typedef int Tcl_FSLoadFileProc(
                Tcl_Interp * interp,
                Tcl_Obj *pathPtr,
                Tcl_LoadHandle * handlePtr,
                Tcl_FSUnloadFileProc * unloadProcPtr);

       Returns  a  standard Tcl completion code.  If an error(8,n) occurs, an error(8,n)
       message is left in(1,8) the interp's result.  The function dynamically loads
       a  binary  code  file(1,n) into memory.  On a successful load(7,n), the handlePtr
       should be filled with a token for the dynamically loaded file(1,n), and  the
       unloadProcPtr should be filled in(1,8) with the address of a procedure.  The
       procedure will be called with the  given  Tcl_LoadHandle  as  its  only
       parameter when Tcl needs to unload the file.

UNLOADFILEPROC
       Function  to unload a previously successfully loaded file.  If load(7,n) was
       implemented, then this should also be  implemented,  if(3,n)  there  is  any
       cleanup action required.

              typedef void Tcl_FSUnloadFileProc(
                Tcl_LoadHandle loadHandle);

GETCWDPROC
       Function  to  process a Tcl_FSGetCwd() call.  Most filesystems need not
       implement this.  It will usually only be called once,  if(3,n)  'getcwd'  is
       called before 'chdir'.  May be NULL.

              typedef Tcl_Obj* Tcl_FSGetCwdProc(
                Tcl_Interp *interp);

       If  the filesystem supports a native notion of a current working direc-
       tory (which might perhaps change independent  of  Tcl),  this  function
       should  return that cwd as the result, or NULL if(3,n) the current directory
       could not be determined (e.g. the user does not have  appropriate  per-
       missions  on the cwd directory).  If NULL is returned, an error(8,n) message
       is left in(1,8) the interp's result.


CHDIRPROC
       Function to process a Tcl_FSChdir() call.  If filesystems do not imple-
       ment  this, it will be emulated by a series of directory access(2,5) checks.
       Otherwise, virtual(5,8) filesystems which do implement it need only  respond
       with  a  positive  return  result if(3,n) the dirName is a valid, accessible
       directory in(1,8) 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).

              typedef int Tcl_FSChdirProc(
                Tcl_Obj *pathPtr);

       The  Tcl_FSChdirProc changes the applications current working directory
       to the value specified in(1,8) pathPtr. The function returns -1 on error(8,n)  or
       0 on success.

KEYWORDS
       stat(1,2) access(2,5) filesystem vfs



Tcl                                   8.4                        Filesystem(3)

References for this manual (incoming links)