DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_FSJoinPath(3tcl)




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_FSRemoveDirectory, Tcl_FSRenameFile,  Tcl_FSListVolumes,
     Tcl_FSEvalFile,       Tcl_FSEvalFileEx,      Tcl_FSLoadFile,
     Tcl_FSMatchInDirectory,       Tcl_FSLink,       Tcl_FSLstat,
     Tcl_FSUtime,     Tcl_FSFileAttrsGet,     Tcl_FSFileAttrsSet,
     Tcl_FSFileAttrStrings,       Tcl_FSStat,       Tcl_FSAccess,
     Tcl_FSOpenFileChannel,       Tcl_FSGetCwd,      Tcl_FSChdir,
     Tcl_FSPathSeparator,    Tcl_FSJoinPath,     Tcl_FSSplitPath,
     Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath,
     Tcl_FSConvertToPathType,               Tcl_FSGetInternalRep,
     Tcl_FSGetTranslatedPath,      Tcl_FSGetTranslatedStringPath,
     Tcl_FSNewNativePath,                    Tcl_FSGetNativePath,
     Tcl_FSFileSystemInfo,   Tcl_AllocStatBuf   -  procedures  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(pathPtr)

     Tcl_PathType
     Tcl_FSGetPathType(pathPtr)

     int
     Tcl_FSCopyFile(srcPathPtr, destPathPtr)

     int
     Tcl_FSCopyDirectory(srcPathPtr, destPathPtr, errorPtr)

     int
     Tcl_FSCreateDirectory(pathPtr)

     int

Tcl                     Last change: 8.4                        1

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     Tcl_FSDeleteFile(pathPtr)

     int
     Tcl_FSRemoveDirectory(pathPtr, int recursive, errorPtr)

     int
     Tcl_FSRenameFile(srcPathPtr, destPathPtr)

     Tcl_Obj*
     Tcl_FSListVolumes(void)

     int                                                           |
     Tcl_FSEvalFileEx(interp, pathPtr, encodingName)               |

     int
     Tcl_FSEvalFile(interp, pathPtr)

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

     int
     Tcl_FSMatchInDirectory(interp, resultPtr, 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                     Last change: 8.4                        2

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     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)                         Points to
                                                        a  struc-
                                                        ture con-
                                                        taining

Tcl                     Last change: 8.4                        3

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

                                                        the
                                                        addresses
                                                        of   pro-
                                                        cedures
                                                        that  can
                                                        be called
                                                        to   per-
                                                        form  the
                                                        various
                                                        filesys-
                                                        tem
                                                        opera-
                                                        tions.

     Tcl_Obj *pathPtr (in)                              The  path
                                                        represented
                                                        by   this
                                                        object is
                                                        used  for
                                                        the
                                                        operation
                                                        in  ques-
                                                        tion.  If
                                                        the
                                                        object
                                                        does  not
                                                        already
                                                        have   an
                                                        internal
                                                        path
                                                        represen-
                                                        tation,
                                                        it   will
                                                        be   con-
                                                        verted to
                                                        have one.

     Tcl_Obj *srcPathPtr (in)                           As    for
                                                        pathPtr,
                                                        but  used
                                                        for   the
                                                        source
                                                        file  for
                                                        a copy or
                                                        rename
                                                        opera-
                                                        tion.

     Tcl_Obj *destPathPtr (in)                          As    for
                                                        pathPtr,
                                                        but  used
                                                        for   the

Tcl                     Last change: 8.4                        4

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

                                                        destina-
                                                        tion
                                                        filename
                                                        for     a
                                                        copy   or
                                                        rename
                                                        opera-
                                                        tion.

     const char *encodingName (in)                      The
                                                        encoding
                                                        of    the
                                                        data
                                                        stored in
                                                        the  file
                                                        identi-
                                                        fied   by
                                                        pathPtr
                                                        and to be
                                                        evaluated.

     const char *pattern (in)                           Only
                                                        files  or
                                                        direc-
                                                        tories
                                                        matching
                                                        this pat-
                                                        tern will
                                                        be
                                                        returned.

     Tcl_GlobTypeData *types (in)                       Only
                                                        files  or
                                                        direc-
                                                        tories
                                                        matching
                                                        the  type
                                                        descrip-
                                                        tions
                                                        contained
                                                        in   this
                                                        structure
                                                        will   be
                                                        returned.
                                                        This
                                                        parameter
                                                        may    be
                                                        NULL.

     Tcl_Interp *interp (in)                            Interpreter
                                                        to    use
                                                        either

Tcl                     Last change: 8.4                        5

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

                                                        for
                                                        results,
                                                        evalua-
                                                        tion,  or
                                                        reporting
                                                        error
                                                        messages.

     ClientData clientData (in)                         The
                                                        native
                                                        descrip-
                                                        tion   of
                                                        the  path
                                                        object to
                                                        create.

     Tcl_Obj *firstPtr (in)                             The first
                                                        of    two
                                                        path
                                                        objects
                                                        to   com-
                                                        pare.
                                                        The
                                                        object
                                                        may    be
                                                        converted
                                                        to   path
                                                        type.

     Tcl_Obj *secondPtr (in)                            The
                                                        second of
                                                        two  path
                                                        objects
                                                        to   com-
                                                        pare.
                                                        The
                                                        object
                                                        may    be
                                                        converted
                                                        to   path
                                                        type.

     Tcl_Obj *listObj (in)                              The  list
                                                        of   path
                                                        elements
                                                        to
                                                        operate
                                                        on with a
                                                        join
                                                        opera-
                                                        tion.

Tcl                     Last change: 8.4                        6

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     int elements (in)                                  If   non-
                                                        negative,
                                                        the
                                                        number of
                                                        elements
                                                        in    the
                                                        listObj
                                                        which
                                                        should be
                                                        joined
                                                        together.
                                                        If  nega-
                                                        tive,
                                                        then  all
                                                        elements
                                                        are
                                                        joined.

     Tcl_Obj **errorPtr (out)                           In    the
                                                        case   of
                                                        an error,
                                                        filled
                                                        with   an
                                                        object
                                                        contain-
                                                        ing   the
                                                        name   of
                                                        the  file
                                                        which
                                                        caused an
                                                        error  in
                                                        the vari-
                                                        ous
                                                        copy/rename
                                                        opera-
                                                        tions.

     Tcl_Obj **objPtrRef (out)                          Filled
                                                        with   an
                                                        object
                                                        contain-
                                                        ing   the
                                                        result of
                                                        the
                                                        opera-
                                                        tion.

     Tcl_Obj *resultPtr (out)                           Pre-
                                                        allocated
                                                        object in
                                                        which  to
                                                        store

Tcl                     Last change: 8.4                        7

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

                                                        (using
                                                        Tcl_ListObjAppendElement)
                                                        the  list
                                                        of  files
                                                        or direc-
                                                        tories
                                                        which are
                                                        success-
                                                        fully
                                                        matched.

     int mode (in)                                      Mask con-
                                                        sisting
                                                        of one or
                                                        more   of
                                                        R_OK,
                                                        W_OK,
                                                        X_OK  and
                                                        F_OK.
                                                        R_OK,
                                                        W_OK  and
                                                        X_OK
                                                        request
                                                        checking
                                                        whether
                                                        the  file
                                                        exists
                                                        and   has
                                                        read,
                                                        write and
                                                        execute
                                                        permis-
                                                        sions,
                                                        respec-
                                                        tively.
                                                        F_OK just
                                                        requests
                                                        checking
                                                        for   the
                                                        existence
                                                        of    the
                                                        file.

     Tcl_StatBuf *statPtr (out)                         The
                                                        structure
                                                        that con-
                                                        tains the
                                                        result of
                                                        a stat or
                                                        lstat
                                                        opera-
                                                        tion.

Tcl                     Last change: 8.4                        8

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     const char *sym1 (in)                              Name of a
                                                        procedure
                                                        to   look
                                                        up in the
                                                        file's
                                                        symbol
                                                        table

     const char *sym2 (in)                              Name of a
                                                        procedure
                                                        to   look
                                                        up in the
                                                        file's
                                                        symbol
                                                        table

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

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

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

     Tcl_LoadHandle *handlePtr (out)                    Filled
                                                        with   an
                                                        abstract
                                                        token
                                                        represent-
                                                        ing   the
                                                        loaded
                                                        file.

Tcl                     Last change: 8.4                        9

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

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

     utimbuf *tval (in)                                 The
                                                        access
                                                        and
                                                        modifica-
                                                        tion
                                                        times  in
                                                        this
                                                        structure
                                                        are  read
                                                        and  used
                                                        to    set
                                                        those
                                                        values
                                                        for     a
                                                        given
                                                        file.

     const char *modeString (in)                        Specifies
                                                        how   the
                                                        file   is
                                                        to     be
                                                        accessed.
                                                        May  have
                                                        any    of
                                                        the
                                                        values
                                                        allowed
                                                        for   the
                                                        mode
                                                        argument
                                                        to    the
                                                        Tcl  open
                                                        command.

     int permissions (in)                               POSIX-
                                                        style
                                                        permis-
                                                        sion
                                                        flags
                                                        such   as
                                                        0644.  If
                                                        a     new
                                                        file   is

Tcl                     Last change: 8.4                       10

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

                                                        created,
                                                        these
                                                        permis-
                                                        sions
                                                        will   be
                                                        set    on
                                                        the
                                                        created
                                                        file.

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

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

     int objc (in)                                      The
                                                        number of
                                                        elements
                                                        in objv.

     Tcl_Obj *const objv[] (in)                         The  ele-
                                                        ments  to
                                                        join   to
                                                        the given
                                                        base
                                                        path.

     Tcl_Obj *linkNamePtr (in)                          The  name
                                                        of    the
                                                        link   to
                                                        be
                                                        created
                                                        or read.

     Tcl_Obj *toPtr (in)                                What  the
                                                        link
                                                        called
                                                        linkNamePtr

Tcl                     Last change: 8.4                       11

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

                                                        should be
                                                        linked
                                                        to,    or
                                                        NULL   if
                                                        the  sym-
                                                        bolic
                                                        link
                                                        specified
                                                        by  link-
                                                        NamePtr
                                                        is to  be
                                                        read.

     int linkAction (in)                                OR-ed
                                                        combina-
                                                        tion   of
                                                        flags
                                                        indicat-
                                                        ing  what
                                                        kind   of
                                                        link
                                                        should be
                                                        created
                                                        (will  be
                                                        ignored
                                                        if  toPtr
                                                        is NULL).
                                                        Valid
                                                        bits   to
                                                        set   are
                                                        TCL_CREATE_SYMBOLIC_LINK
                                                        and
                                                        TCL_CREATE_HARD_LINK.
                                                        When both
                                                        flags are
                                                        set   and
                                                        the
                                                        underly-
                                                        ing
                                                        filesys-
                                                        tem   can
                                                        do
                                                        either,
                                                        symbolic
                                                        links are
                                                        pre-
                                                        ferred.
_________________________________________________________________


DESCRIPTION


Tcl                     Last change: 8.4                       12

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     There are several reasons for calling the Tcl_FS  API  func-
     tions (e.g. Tcl_FSAccess and Tcl_FSStat) rather than calling
     system  level  functions  like  access  and  stat  directly.
     First,  they will work cross-platform, so an extension which
     calls them should  work  unmodified  on  Unix  and  Windows.
     Second,  the  Windows  implementation of some of these func-
     tions 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 subse-
     quent calls).  Fourth, and perhaps most importantly, all  of
     these functions are "virtual filesystem aware".  Any virtual
     filesystem  (VFS  for  short)  which  has  been   registered
     (through Tcl_FSRegister) may reroute file access to alterna-
     tive media or access methods.  This means that all of  these
     functions  (and therefore the corresponding file, glob, pwd,
     cd, open, etc.  Tcl commands)  may  be  operate  on  "files"
     which  are  not native files in the native filesystem.  This
     also  means  that  any  Tcl  extension  which  accesses  the
     filesystem  (FS for short) through this API is automatically
     "virtual filesystem aware".   Of  course,  if  an  extension
     accesses  the  native filesystem directly (through platform-
     specific APIs, for example), then Tcl cannot intercept  such
     calls.

     If appropriate VFSes have been registered, the "files"  may,
     to  give  two examples, be remote (e.g. situated on a remote
     ftp server) or archived (e.g. lying inside a .zip  archive).
     Such  registered filesystems provide a lookup table of func-
     tions to implement all or some of the  functionality  listed
     here.    Finally,   the  Tcl_FSStat  and  Tcl_FSLstat  calls
     abstract away from what the "struct stat" buffer is actually
     declared  to  be,  allowing the same code to be used both on
     systems with and systems without support  for  files  larger
     than 2GB in size.

     The  Tcl_FS  API  is  objectified  and  may  cache  internal
     representations  and  other  path-related  strings (e.g. the
     current working directory).  One side-effect of this is that
     one  must not pass in objects with a reference count of zero
     to any of these functions.  If such calls were handled, they
     might  result in memory leaks (under some circumstances, the
     filesystem code may wish to retain a reference to the passed
     in  object,  and  so  one  must not assume that after any of
     these calls return, the object still has a  reference  count
     of  zero - it may have been incremented) or in a direct seg-
     mentation fault (or other memory access error)  due  to  the
     object being freed part way through the complex object mani-
     pulation required to ensure that the path is  fully  normal-
     ized and absolute for filesystem determination.  The practi-
     cal lesson to learn from this is that
          Tcl_Obj *path = Tcl_NewStringObj(...);

Tcl                     Last change: 8.4                       13

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

          Tcl_FSWhatever(path);
          Tcl_DecrRefCount(path);
     is wrong, and may cause memory errors. The  path  must  have
     its  reference  count  incremented  before passing it in, or
     decrementing it.  For this reason, objects with a  reference
     count  of  zero  are  considered  not to be valid filesystem
     paths and calling any  Tcl_FS  API  function  with  such  an
     object will result in no action being taken.

  FS API FUNCTIONS
     Tcl_FSCopyFile attempts to copy the file given by srcPathPtr
     to  the  path  name  given by destPathPtr.  If the two paths
     given   lie   in   the   same   filesystem   (according   to
     Tcl_FSGetFileSystemForPath)  then  that  filesystem's  "copy
     file" function is called (if it is non-NULL).  Otherwise the
     function  returns -1 and sets the errno global C variable to
     the "EXDEV" POSIX error  code  (which  signifies  a  "cross-
     domain link").

     Tcl_FSCopyDirectory attempts to copy the directory given  by
     srcPathPtr  to  the  path name given by destPathPtr.  If the
     two paths given lie in the  same  filesystem  (according  to
     Tcl_FSGetFileSystemForPath)  then  that  filesystem's  "copy
     file" function is called (if it is non-NULL).  Otherwise the
     function  returns -1 and sets the errno global C variable to
     the "EXDEV" POSIX error  code  (which  signifies  a  "cross-
     domain link").

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

     Tcl_FSDeleteFile  attempts  to  delete  the  file  given  by
     pathPtr  by  calling  the  owning filesystem's "delete file"
     function.

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

     Tcl_FSRenameFile attempts to rename the  file  or  directory
     given  by  srcPathPtr to the path name given by destPathPtr.
     If the two paths given lie in the same filesystem (according
     to   Tcl_FSGetFileSystemForPath)   then   that  filesystem's
     "rename file" function is called (if it is non-NULL).   Oth-
     erwise  the  function returns -1 and sets the errno global C
     variable to the "EXDEV" POSIX error code (which signifies  a
     "cross-domain link").

     Tcl_FSListVolumes calls each filesystem which has a non-NULL
     "list  volumes"  function and asks them to return their list
     of root volumes.  It accumulates the return values in a list

Tcl                     Last change: 8.4                       14

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     which  is  returned to the caller (with a reference count of
     0).

     Tcl_FSEvalFileEx reads the file given by pathPtr  using  the  |
     encoding  identified  by encodingName and evaluates its con-  |
     tents as a Tcl script.  It returns the same  information  as  |
     Tcl_EvalObjEx.  If encodingName is NULL, the system encoding  |
     is used for reading the file contents.  If  the  file  could  |
     not be read then a Tcl error is returned to describe why the  |
     file could not be read.  The eofchar for files is "\32" (^Z)  |
     for all platforms.  If you require a "^Z" in code for string  |
     comparison, you can use "\032" or "\u001a",  which  will  be  |
     safely   substituted  by  the  Tcl  interpreter  into  "^Z".  |
     Tcl_FSEvalFile is a simpler version of Tcl_FSEvalFileEx that  |
     always uses the system encoding when reading the file.

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

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

     Tcl_FSMatchInDirectory is  used  by  the  globbing  code  to
     search  a  directory  for all files which match a given pat-
     tern.  The appropriate function for the filesystem to  which
     pathPtr belongs will be called.

     The return value is a standard Tcl result indicating whether
     an error occurred in globbing.  Error messages are placed in
     interp (unless interp is NULL, which is allowed),  but  good
     results are placed in the resultPtr given.

     Note that the glob code implements recursive patterns inter-
     nally, so this function will only ever be passed simple pat-
     terns, 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.  A special  case
     of  being called with a NULL pattern indicates that the path
     needs to be checked only for the correct type.

     Tcl_FSLink replaces the library  version  of  readlink,  and
     extends  it to support the creation of links.  The appropri-
     ate function for the filesystem to which linkNamePtr belongs
     will be called.

Tcl                     Last change: 8.4                       15

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     If the toPtr is NULL, a "read  link"  action  is  performed.
     The  result is a Tcl_Obj specifying the contents of the sym-
     bolic link given by linkNamePtr, or NULL if the  link  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
     of one of the types passed in in the linkAction flag.   This
     flag  is an ORed combination of TCL_CREATE_SYMBOLIC_LINK and
     TCL_CREATE_HARD_LINK.  Where a choice exists (i.e. more than
     one flag is passed in), the Tcl convention is to prefer sym-
     bolic links.  When  a  link  is  successfully  created,  the
     return  value  should  be  toPtr (which is therefore already
     owned by the caller).  If unsuccessful, NULL is returned.

     Tcl_FSLstat fills the stat structure statPtr  with  informa-
     tion  about  the specified file.  You do not need any access
     rights to the file to get  this  information  but  you  need
     search  rights  to all directories named in the path leading
     to the file.  The stat  structure  includes  info  regarding
     device,  inode  (always 0 on Windows), privilege mode, nlink
     (always 1 on Windows), user id (always 0 on Windows),  group
     id  (always 0 on Windows), rdev (same as device on Windows),
     size, last access time, last  modification  time,  and  last
     metadata change time.

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

     Tcl_FSUtime replaces the library version of utime.

     This returns 0 on success and -1 on error (as per the  utime
     documentation).  If successful, the function will update the
     "atime" and "mtime" values of the file given.

     Tcl_FSFileAttrsGet implements read access for  the  hookable
     file  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
     objPtrRef,  which  will  only  be  temporarily valid (unless
     Tcl_IncrRefCount is called).

     Tcl_FSFileAttrsSet implements write access for the  hookable
     file  attributes  subcommand.   The appropriate function for
     the filesystem to which pathPtr belongs will be called.

     Tcl_FSFileAttrStrings implements part of the  hookable  file
     attributes  subcommand.   The  appropriate  function for the
     filesystem to which pathPtr belongs will be called.

Tcl                     Last change: 8.4                       16

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     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  incre-
     ment  its reference count before using it.  On completion of
     that use, Tcl will decrement its reference count.  Hence  if
     the  list  should be disposed of by Tcl when done, it should
     have a reference count of zero, and if the list  should  not
     be  disposed  of,  the filesystem should ensure it retains a
     reference count to the object.

     Tcl_FSAccess checks whether the process would be allowed  to
     read,  write  or  test  for  existence of the file (or other
     filesystem 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.

     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.

     Tcl_FSStat fills the stat structure statPtr with information
     about the specified file.  You do not need any access rights
     to the file to get this  information  but  you  need  search
     rights  to  all directories named in the path leading to the
     file.  The stat structure includes  info  regarding  device,
     inode (always 0 on Windows), privilege mode, nlink (always 1
     on Windows), user id (always 0 on Windows), group id (always
     0  on Windows), rdev (same as device on Windows), size, last
     access time,  last  modification  time,  and  last  metadata
     change time.

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

     Tcl_FSOpenFileChannel opens a file 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 similar to those  given  in  the
     Tcl  open  command  when opening a file.  If an error occurs
     while opening  the  channel,  Tcl_FSOpenFileChannel  returns
     NULL  and  records  a POSIX error code that can be retrieved
     with Tcl_GetErrno.  In  addition,  if  interp  is  non-NULL,
     Tcl_FSOpenFileChannel  leaves  an  error message in interp's
     result after any error.

     The newly created channel is not registered in the  supplied
     interpreter;  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

Tcl                     Last change: 8.4                       17

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     assigns it as a replacement for the standard channel.

     Tcl_FSGetCwd replaces the library version of getcwd.

     It returns the  Tcl  library's  current  working  directory.
     This  may  be  different  to  the  native platform's working
     directory, which happens when the current working  directory
     is not in the native filesystem.

     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 reference count  incremented  for
     the  caller.   When  it  is no longer needed, that reference
     count should be decremented.  This  is  needed  for  thread-
     safety  purposes,  to  allow multiple threads to access this
     and related functions, while ensuring the results are always
     valid.

     Tcl_FSChdir 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  per-
     missions.

     For results, see chdir  documentation.   If  successful,  we
     keep  a record of the successful path in cwdPathPtr for sub-
     sequent calls to Tcl_FSGetCwd.

     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
     of length 1.  If the path is invalid, NULL is returned.

     Tcl_FSJoinPath takes the given  Tcl_Obj,  which  must  be  a
     valid  list  (which  is allowed to have a reference count of
     zero), and returns the path object given by considering  the
     first  elements  elements  as valid path segments (each path
     segment may be a complete path, a partial  path  or  just  a
     single  possible  directory or file name).  If any path seg-
     ment is actually an absolute path, then all prior path  seg-
     ments are discarded.  If elements is less than 0, we use the
     entire list.

     It is possible that the returned object is actually an  ele-
     ment  of  the given list, so the caller should be careful to
     increment the reference count of the result  before  freeing

Tcl                     Last change: 8.4                       18

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     the list.

     The returned object, typically with  a  reference  count  of
     zero  (but  it  could be shared under some conditions), con-
     tains the joined path.  The  caller  must  add  a  reference
     count  to  the  object  before using it.  In particular, the
     returned object could be an element of the  given  list,  so
     freeing  the  list  might  free the object prematurely if no
     reference count has been taken.  If the number  of  elements
     is  zero,  then  the returned object will be an empty-string
     Tcl_Obj.

     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.   It  returns  a  list
     object  with  a  reference  count of zero.  If the passed in
     lenPtr is non-NULL,  the  variable  it  points  to  will  be
     updated  to  contain  the number of elements in the returned
     list.

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

     It returns 1 if the paths are equal, and 0 if they are  dif-
     ferent.  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 value can be used as  a  unique
     identifier for the file.

     It returns the normalized path object, owned by Tcl, or NULL
     if  the  path was invalid or could otherwise not be success-
     fully converted.  Extraction of absolute,  normalized  paths
     is  very efficient (because the filesystem operates on these
     representations internally), although the  result  when  the
     filesystem  contains  numerous symbolic links may not be the
     most user-friendly version of a path.  The return  value  is
     owned  by  Tcl  and has a lifetime equivalent to that of the
     pathPtr passed in (unless that is a relative path, in  which
     case  the  normalized  path object may be freed any time the
     cwd changes) -  the  caller  can  of  course  increment  the
     refCount if it wishes to maintain a copy for longer.

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

     Returns object, typically with  refCount  of  zero  (but  it
     could  be  shared  under  some  conditions),  containing the
     joined path.  The caller must add a refCount to  the  object
     before  using  it.   If  any of the objects passed into this

Tcl                     Last change: 8.4                       19

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     function (pathPtr or path elements) have a refCount of zero,
     they will be freed when this function returns.

     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 this object is already sup-
     posedly  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 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.

     Tcl_FSGetInternalRep 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
     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 message may be  left  in  the  inter-
     preter.  A "translated" path is one which contains no "~" or
     "~user" sequences (these have been expanded to their current
     representation  in  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_FSGetNormalizedPath  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 or
     NULL.  The string  returned  is  dynamically  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 purposes.

     Tcl_FSNewNativePath performs something like the  reverse  of
     the  usual  obj->path->nativerep  conversions.  If some code
     retrieves a path in native form (from, e.g.  readlink  or  a

Tcl                     Last change: 8.4                       20

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     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.

     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.

     Tcl_FSGetNativePath  is  for  use  by  the  Win/Unix  native
     filesystems,  so  that  they  can easily retrieve the native
     (char* or TCHAR*) representation of a path.   This  function
     is  a  convenience  wrapper around Tcl_FSGetInternalRep, and
     assumes the native representation is string-based.   It  may
     be  desirable  in the future to have non-string-based native
     representations (for example, on  MacOSX,  a  representation
     using  a  fileSpec of FSRef structure would probably be more
     efficient).  On Windows a full Unicode representation  would
     allow   for   paths  of  unlimited  length.   Currently  the
     representation is simply a character string which  may  con-
     tain  either  the relative path or a complete, absolute nor-
     malized path in the native encoding (complex conditions dic-
     tate  which  of  these  will  be provided, so neither can be
     relied upon, unless the path is known to be  absolute).   If
     you  need  a  native  path  which must be absolute, then you
     should ask for the native version of a normalized path.   If
     for  some  reason  a non-absolute, non-normalized version of
     the path is needed,  that  must  be  constructed  separately
     (e.g. using Tcl_FSGetTranslatedPath).

     The native representation is cached so that  repeated  calls
     to  this  function  will not require additional conversions.
     The return  value  is  owned  by  Tcl  and  has  a  lifetime
     equivalent  to that of the pathPtr passed in (unless that is
     a relative path, in which case the native representation may
     be freed any time the cwd changes).

     Tcl_FSFileSystemInfo returns a list of  two  elements.   The
     first element is the name of the filesystem (e.g.  "native",
     "vfs", "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 categori-
     zation of files.

     A valid list object is returned, unless the path  object  is
     not recognized, 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 the path, NULL is returned.

Tcl                     Last change: 8.4                       21

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     Tcl_FSGetPathType determines whether the given path is rela-
     tive  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
     turn depends on the flags used to build Tcl.


THE VIRTUAL FILESYSTEM API

     A filesystem provides a Tcl_Filesystem structure  that  con-
     tains  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.

     The Tcl_Filesystem structures are manipulated using the fol-
     lowing methods.

     Tcl_FSRegister takes a pointer to a filesystem structure and
     an  optional  piece of data to associated with that filesys-
     tem.  On calling this function, Tcl will attach the filesys-
     tem  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.

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

     Tcl_FSData will return the ClientData  associated  with  the
     given  filesystem, if that filesystem is registered.  Other-
     wise it will return NULL.

     Tcl_FSMountsChanged is used to inform the  Tcl's  core  that
     the  set  of mount points for the given (already registered)
     filesystem have changed, and that  cached  file  representa-
     tions may therefore no longer be correct.

  THE TCL_FILESYSTEM STRUCTURE
     The Tcl_Filesystem structure contains the following fields:
          typedef struct Tcl_Filesystem {
              const char *typeName;
              int structureLength;
              Tcl_FSVersion version;
              Tcl_FSPathInFilesystemProc *pathInFilesystemProc;

Tcl                     Last change: 8.4                       22

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

              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  this  structure  which
     contain  simple data elements, all entries contain addresses
     of functions called by the generic filesystem layer to  per-
     form the complete range of filesystem related actions.

     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  Tcl_FSRenameFileProc,  Tcl's   core   will
     instead  fallback on a combination of other filesystem func-
     tions  (it   will   use   Tcl_FSCopyFileProc   followed   by
     Tcl_FSDeleteFileProc,   and  if  Tcl_FSCopyFileProc  is  not
     implemented there is a further  fallback).   However,  if  a
     Tcl_FSRenameFileProc  command  is  issued at the C level, no

Tcl                     Last change: 8.4                       23

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     such fallbacks occur.  This is true except for the last four
     entries  in  the  filesystem  table (lstat, load, getcwd and
     chdir) for which fallbacks do in fact occur at the C level.

     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.

  EXAMPLE FILESYSTEM DEFINITION
     Here is the filesystem lookup table used by the "vfs" exten-
     sion  which  allows  filesystem actions to be implemented in
     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; use the core fallback mechanism */
              NULL,
              /* No rename file; use the core fallback mechanism */
              NULL,
              /* No copy directory; use the core fallback mechanism */

Tcl                     Last change: 8.4                       24

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

              NULL,
              /* Core will use stat for lstat */
              NULL,
              /* No load; use the core fallback mechanism */
              NULL,
              /* We don't need a getcwd or chdir; the core's own
               * internal value is suitable */
              NULL,
              NULL
          };


FILESYSTEM INFRASTRUCTURE

     These fields contain basic information about the  filesystem
     structure and addresses of functions which are used to asso-
     ciate a particular filesystem with a  file  path,  and  deal
     with  the  internal  handling  of  path representations, for
     example copying and freeing such representations.

  TYPENAME
     The typeName field contains a  null-terminated  string  that
     identifies  the  type  of  the  filesystem implemented, e.g.
     "native", "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 the size of the structure changes
     in a future Tcl release.

  VERSION
     The version field should be set to TCL_FILESYSTEM_VERSION_1.

  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 functions 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);

Tcl                     Last change: 8.4                       25

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

  DUPINTERNALREPPROC
     This function makes a copy of a path's internal  representa-
     tion,  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  internal  representations  need  freeing  (i.e.  if some
     memory is allocated when an internal representation is  gen-
     erated), but may otherwise be NULL.

          typedef void Tcl_FSFreeInternalRepProc(
                  ClientData clientData);

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

          typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
                  ClientData clientData);

  CREATEINTERNALREPPROC
     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  Tcl_FSPathInFilesystemProc for
     this  filesystem  always  immediately  creates  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
     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 "~", a path containing  symbolic
     links,  etc).   If  the very last component in the path is a
     symbolic link, it should not be converted into the object it
     points  to  (but  its  case  or other aspects should be made

Tcl                     Last change: 8.4                       26

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     unique).  All other path components should be converted from
     symbolic  links.   This  one  exception is required to agree
     with Tcl's semantics with file  delete,  file  rename,  file
     copy  operating  on  symbolic  links.   This function may be
     called with nextCheckpoint either at the  beginning  of  the
     path  (i.e.  zero), at the end of the path, or at any inter-
     mediate file separator in the path.  It will never point  to
     any other arbitrary position in the path. In the last of the
     three valid cases, the implementation can  assume  that  the
     path  up  to  and  including the file separator is known and
     normalized.

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


FILESYSTEM OPERATIONS

     The  fields  in  this  section  of  the  structure   contain
     addresses  of  functions  which  are called to carry out the
     basic filesystem operations.  A filesystem which expects  to
     be  used  with  the  complete  standard Tcl command set must
     implement all of these.  If some  of  them  are  not  imple-
     mented, 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 filesys-
     tem which does not support symbolic links need not implement
     the readlink function, etc.  The Tcl core  expects  filesys-
     tems to behave in this way).

  FILESYSTEMPATHTYPEPROC
     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".
     The Tcl_Obj result is owned by the  filesystem  and  so  Tcl
     will  increment  the refCount of that object if 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.  This need only be implemented if the filesystem
     wishes to use a different separator than the standard string
     "/".  Amongst other uses, it is returned by the file separa-
     tor command.  The return value  should  be  an  object  with
     refCount of zero.

Tcl                     Last change: 8.4                       27

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

          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 atime, file isdirectory,
     file size, glob).

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

     The Tcl_FSStatProc fills the  stat  structure  statPtr  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 Win-
     dows),  group id (always 0 on Windows), rdev (same as device
     on Windows), size, last access time, last modification time,
     and last metadata change time.

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

  ACCESSPROC
     Function to process a Tcl_FSAccess  call.   Must  be  imple-
     mented  for  any reasonable filesystem, since many Tcl level
     commands depend crucially upon it (e.g.  file  exists,  file
     readable).

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

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

     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.

  OPENFILECHANNELPROC

Tcl                     Last change: 8.4                       28

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     Function to process a Tcl_FSOpenFileChannel call.   Must  be
     implemented  for any reasonable filesystem, since any opera-
     tions which require open or accessing a file's contents will
     use it (e.g. open, encoding, 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  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 similar to  those
     given in the Tcl open command when opening a file, where the
     mode argument is a combination of the POSIX flags  O_RDONLY,
     O_WRONLY,  etc.   If an error occurs while opening the chan-
     nel, the Tcl_FSOpenFileChannelProc returns NULL and  records
     a  POSIX error code that can be retrieved with Tcl_GetErrno.
     In    addition,    if    interp     is     non-NULL,     the
     Tcl_FSOpenFileChannelProc   leaves   an   error  message  in
     interp's result after any error.

     The newly created channel must not registered  in  the  sup-
     plied  interpreter;  that  task  is  up  to  the  caller  of
     Tcl_FSOpenFileChannel (if necessary). 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.

  MATCHINDIRECTORYPROC
     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 inter-
     nally).

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

     The function should return  all  files  or  directories  (or
     other  filesystem objects) which match the given pattern and
     accord with the types specification given.   There  are  two
     ways  in  which  this function may be called.  If pattern is
     NULL, then pathPtr is a full path specification of a  single
     file  or directory which should be checked for existence and

Tcl                     Last change: 8.4                       29

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     correct type.  Otherwise, pathPtr is a directory,  the  con-
     tents  of  which  the  function  should  search for files or
     directories which have the correct 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 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  occurred in the matching process.  Error messages
     are placed in interp, unless interp in NULL in which case no
     error message need be generated; on a TCL_OK result, results
     should be added to the resultPtr object given (which can  be
     assumed to be a valid unshared Tcl list).  The matches added
     to resultPtr should include any path prefix given in pathPtr
     (this  usually  means  they will be absolute path specifica-
     tions).  Note that if no  matches  are  found,  that  simply
     leads  to  an  empty  result;  errors  are only signaled for
     actual file or filesystem problems which  may  occur  during
     the matching process.

     The Tcl_GlobTypeData structure passed in the types parameter
     contains the following fields:
          typedef struct Tcl_GlobTypeData {
                  /* Corresponds to bcdpfls as in 'find -t' */
                  int type;
                  /* Corresponds to file permissions */
                  int perm;
                  /* Acceptable mac type */
                  Tcl_Obj *macType;
                  /* Acceptable mac creator */
                  Tcl_Obj *macCreator;
          } Tcl_GlobTypeData;

     There are two specific cases which it is important to handle
     correctly,  both  when  types is non-NULL. The two cases are
     when types->types  &  TCL_GLOB_TYPE_DIR  or  types->types  &
     TCL_GLOB_TYPE_MOUNT  are  true  (and  in particular when the
     other flags are false).  In the first of  these  cases,  the
     function must list the contained directories.  Tcl uses this
     to implement recursive globbing,  so  it  is  critical  that
     filesystems  implement directory matching correctly.  In the
     second  of  these  cases,  with   TCL_GLOB_TYPE_MOUNT,   the
     filesystem  must  list the mount points which lie within the
     given pathPtr (and in this case, pathPtr need not lie within
     the  same filesystem - different to all other cases in which
     this function is called).  Support for this is  critical  if
     Tcl  is  to  have  seamless  transitions  between  from  one
     filesystem to another.

  UTIMEPROC

Tcl                     Last change: 8.4                       30

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     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.

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

     The access and modification times of the file  specified  by
     pathPtr  should  be  changed to the values given in the tval
     structure.

     The return value should be 0 on success and -1 on an  error,
     as with the system utime.

  LINKPROC
     Function to process a Tcl_FSLink  call.   Should  be  imple-
     mented only if the filesystem supports links, and may other-
     wise 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  the
     contents  of a link.  The result is a Tcl_Obj specifying the
     contents of the link given by linkNamePtr, or  NULL  if  the
     link  could  not be read.  The result is owned by the caller
     (and should therefore have its ref count incremented  before
     being  returned).   Any callers should call Tcl_DecrRefCount
     on this result when it is no longer needed.  If toPtr is not
     NULL,  the  function  should  attempt to create a link.  The
     result in this case should be toPtr if the link was success-
     ful  and  NULL  otherwise.   In  this case the result is not
     owned by the caller  (i.e.  no  ref  count  manipulation  on
     either  end is needed). 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 the filesystem
     adds volumes at the head of the filesystem, so that they can
     be returned by file 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 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

Tcl                     Last change: 8.4                       31

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     then  decrement  that  refCount.  This allows filesystems to
     choose whether they actually want to retain a "master  list"
     of volumes or not (if 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  yes,  then  they simply increment the
     refCount of their master 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 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 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.

          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  incre-
     ment  its reference count before using it.  On completion of
     that use, Tcl will decrement its reference count.  Hence  if
     the  list  should be disposed of by Tcl when done, it should
     have a reference count of zero, and if the list  should  not
     be  disposed  of, the filesystem should ensure it returns an
     object with a reference count of at least one.

  FILEATTRSGETPROC
     Function to process a Tcl_FSFileAttrsGet call, used by  file
     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 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 reference count  of  zero.   Either  way  we  must
     either   store  it  somewhere  (e.g.  the  Tcl  result),  or
     Incr/Decr its reference  count  to  ensure  it  is  properly
     freed.

Tcl                     Last change: 8.4                       32

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

  FILEATTRSSETPROC
     Function to process a Tcl_FSFileAttrsSet call, used by  file
     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  the  list
     returned  by  the Tcl_FSFileAttrStringsProc should be set to
     the objPtr given.

  CREATEDIRECTORYPROC
     Function to process a Tcl_FSCreateDirectory call.  Should be
     implemented 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  occurred  in  the  process.  If successful, a new
     directory should have been added to the  filesystem  in  the
     location specified by pathPtr.

  REMOVEDIRECTORYPROC
     Function to process a Tcl_FSRemoveDirectory call.  Should be
     implemented 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 occurred in the process.  If successful, the direc-
     tory 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  this
     flag  is  not  given,  then and the directory is non-empty a
     POSIX "EEXIST" error should be signaled.  If an  error  does
     occur,  the  name  of the file or directory which caused the
     error should be placed in 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);

Tcl                     Last change: 8.4                       33

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

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


FILESYSTEM EFFICIENCY

     These functions need not be  implemented  for  a  particular
     filesystem  because  the  core has a fallback implementation
     available. See each individual description  for  the  conse-
     quences of leaving the field NULL.

  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  a  filesystem  can
     differentiate between stat 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 it is applied
     to a symbolic link, it returns information about  the  link,
     not about the target file.

  COPYFILEPROC
     Function to process a Tcl_FSCopyFile call.   If  not  imple-
     mented  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.

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

     The return value is a standard Tcl result indicating whether
     an  error occurred in the copying process.  Note that, dest-
     PathPtr is the name of the file 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 copy subcommand).  Note
     that, if the filesystem supports symbolic  links,  Tcl  will
     always  call  this  function  and not copyDirectoryProc when
     needed to copy them (even if  they  are  symbolic  links  to
     directories).  Finally, if the filesystem determines it can-
     not    support    the    file    copy    action,     calling
     Tcl_SetErrno(EXDEV)  and  returning a non-TCL_OK result will
     tell Tcl to use its standard fallback mechanisms.

Tcl                     Last change: 8.4                       34

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

  RENAMEFILEPROC
     Function to process a Tcl_FSRenameFile call.  If not  imple-
     mented,  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.

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

     The return value is a standard Tcl result indicating whether
     an  error occurred in the renaming process.  If the filesys-
     tem determines it cannot support  the  file  rename  action,
     calling   Tcl_SetErrno(EXDEV)  and  returning  a  non-TCL_OK
     result will tell Tcl to use its  standard  fallback  mechan-
     isms.

  COPYDIRECTORYPROC
     Function to process  a  Tcl_FSCopyDirectory  call.   If  not
     implemented,  Tcl  will fall back on a recursive file mkdir,
     file copy mechanism.  Therefore it need only be  implemented
     if 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 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 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 direc-
     tory into which srcPathPtr should be copied (i.e. the  func-
     tion  is  much  simpler than the Tcl level file copy subcom-
     mand).  Finally, if the filesystem determines it cannot sup-
     port  the directory copy action, calling Tcl_SetErrno(EXDEV)
     and returning a non-TCL_OK result will tell Tcl to  use  its
     standard fallback mechanisms.

  LOADFILEPROC
     Function to process a Tcl_FSLoadFile call.   If  not  imple-
     mented, 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  it  can  be  implemented  simply  to   return
     TCL_ERROR  to  disable load functionality in this filesystem
     entirely.

          typedef int Tcl_FSLoadFileProc(
                  Tcl_Interp *interp,

Tcl                     Last change: 8.4                       35

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

                  Tcl_Obj *pathPtr,
                  Tcl_LoadHandle *handlePtr,
                  Tcl_FSUnloadFileProc *unloadProcPtr);

     Returns a standard Tcl completion code.  If an error occurs,
     an  error message is left in the interp's result.  The func-
     tion dynamically loads a binary code file into memory.  On a
     successful load, the handlePtr should be filled with a token
     for the  dynamically  loaded  file,  and  the  unloadProcPtr
     should  be  filled  in with the address of a procedure.  The
     unload   procedure   will   be   called   with   the   given
     Tcl_LoadHandle  as  its  only  parameter  when  Tcl needs to
     unload the file.  For example, for  the  native  filesystem,
     the  Tcl_LoadHandle  returned is currently a token which can
     be used in the private TclpFindSymbol to access functions in
     the  new  code.   Each  filesystem  is  free  to  define the
     Tcl_LoadHandle as it requires.  Finally, if  the  filesystem
     determines  it  cannot support the file load action, calling
     Tcl_SetErrno(EXDEV) and returning a non-TCL_OK  result  will
     tell Tcl to use its standard fallback mechanisms.

  UNLOADFILEPROC
     Function to unload a previously  successfully  loaded  file.
     If  load  was  implemented,  then this should also be imple-
     mented, if 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 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 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.

  CHDIRPROC
     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 pathPtr is a valid,  accessible  direc-
     tory  in  their  filesystem.   They  need  not  remember the

Tcl                     Last change: 8.4                       36

Filesystem(3)        Tcl Library Procedures         Filesystem(3)

     result, since that will be automatically remembered for  use
     by  Tcl_FSGetCwd.   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 pathPtr. The function
     returns -1 on error or 0 on success.


SEE ALSO

     cd(n), file(n), load(n), open(n), pwd(n), unload(n)


KEYWORDS

     stat, access, filesystem, vfs, virtual

Tcl                     Last change: 8.4                       37


Man(1) output converted with man2html