vfs(n)																	    vfs(n)

__________________________________________________________________________________________________________________________________________________

NAME

       vfs - Filesystem management in Tcl

SYNOPSIS

       package require Tcl  8.4

       package require vfs  ?1.2.1?

       vfs::filesystem mount ?-volume? path command

       vfs::filesystem unmount path

       vfs::filesystem info ?path?

       vfs::filesystem fullynormalize path

       vfs::filesystem posixerror int

       vfs::filesystem internalerror command

_________________________________________________________________

DESCRIPTION

       The  package  vfs provides commands to query, mount and unmount virtual filesystems implemented in Tcl. This is further facilitated through
       the provison of helper commands in a tcl script library. See section "HANDLER ENVIRONMENT" of vfs-fsapi for more information.

       Once a virtual filesystem is in place, the standard Tcl commands, like file, glob, cd, pwd, open, including all their C	APIs  in  the  Tcl
       library	(e.g.	Tcl_FSOpenFileChannel,	Tcl_FSMatchInDirectory, extensions such as Tk which may open or read files will also transparently
       access the virtual filesystem).

       Because all of Tcl's filesystem activity passes through a single layer, every operation can be intercepted. This package  does  just  that.
       This  is  also quite different from simply overloading the file command in Tcl.	We are actually providing replacements for C commands like
       access, stat, etc.  By implementing a small number of low-level commands we ensure that all commands at higher levels will  function  irre-
       spective of what is going on inside the filesystem layer.

       Tcl's  filesystem hooks operate on a per-process basis.	This means every Tcl interpreter in the same process/application will see the same
       filesystem, including any virtual filesystems.

       To access this package use the command package require vfs.  This automatically registers the vfs hooks into Tcl's filesystem and  provides
       the command vfs::filesystem. The latter allows the registration of actual virtual filesystems. More in the upcoming section API.  The hooks
       will not be removed until Tcl exits. If desired, control over this could be exposed to Tcl in the future.  By and  in  itself  the  command
       above  will  have  no  further  effect.	Only after filesystem implementations have been registered and filesystems using them been mounted
       filesystem commands will actually be intercepted, and handled by the Tcl code of the mounted virtual filesystem.

API

       vfs::filesystem mount ?-volume? path command
	      Mounts a virtual filesystem at path, making it useable. After completion of the call any access to a subdirectory of  path  will	be
	      handled by that filesystem. The filesystem is represented here by the command prefix which will be executed whenever an operation on
	      a file or directory within path has to be performed.

	      Whether the command is implemented in C or Tcl is of no relevance as long as it adheres to the API specified  in	vfs-fsapi  and	is
	      present in the interpreter where the mount operation is executed.

	      If  the  option -volume is specified the new mount point is also registered with Tcl as a new volume and will therefore from then on
	      appear in the output of the command file volumes. This is useful (and required for reasonable operation) for mounts like ftp://.	It
	      should not be used for paths mounted inside the native filesystem.

	      The  new	filesystem  mounts  will  be observed immediately in all interpreters in the current process.  If the interpreter is later
	      deleted, all mounts which are intercepted by it will be automatically removed (and will therefore affect the view of the	filesystem
	      seen by all interpreters).

       vfs::filesystem unmount path
	      This  unmounts  the  virtual filesystem which was mounted at path. An error is thrown if no filesystem was mounted there.  After the
	      completion of the operation the filesystem is not visible anymore, and any previous filesystem accessible through this path  becomes
	      accessible again.

       vfs::filesystem info ?path?
	      A list of all filesystems mounted in all interpreters is returned, if no path argument was specified.  Else the filesystem responsi-
	      ble for that path is examined and the command prefix used to handle all filesystem operations returned.  An error is  thrown  if	no
	      filesystem is mounted for that path.

	      There is currently no facility for examining in which interpreter each command will be evaluated.

       vfs::filesystem fullynormalize path
	      Performs a full expansion of path, (as per file normalize). This includes the following of any links in the last element of path.

       vfs::filesystem posixerror int
	      This  command  can  be called by filesystem implementations during the execution of a filesystem operation to signal the posix error
	      code of a failure. See also vfs-fsapi.

       vfs::filesystem internalerror command
	      When used the specified command is registerd as the command to trap and report any internal errors thrown by filesystem  implementa-
	      tions.

LIMITATIONS

       The code of the package vfs has only a few limitations.

       [1]    One subtlety one has to be aware of is that mixing case-(in)sensitive filesystems and application code may yield unexpected results.

	      For example mounting a case-sensitive virtual filesystem into a case-insensitive system (like the standard Windows or MacOS filesys-
	      tems) and then using this with code relying on case-insensitivity problems will appear when accessing the virtual filesystem.

	      Note that application code relying on case-insensitivity will not under Unix either, i.e. is inherently non-portable, and should	be
	      fixed.

       [2]    The  C-API's for link and lstat are currently not exposed to the Tcl level. This may be done in the future to allow virtual filesys-
	      tems implemented in Tcl to support the reading and writing of links.

       [3]    The public C-API filesystem function Tcl_FSMatchInDirectory is given a variety of type information in a Tcl_GlobTypeData	structure.
	      Currently  only  the  type  field  of said strcuture is exposed to the tcl-level. Fields like permissions and MacOS type/creator are
	      ignored.

SEE ALSO

       vfs-filesystems, vfs-fsapi

KEYWORDS

       file, filesystem, vfs

COPYRIGHT

       Copyright (c) 2001-2003 Vince Darley <vincentdarley@users.sourceforge.net>
       Copyright (c) 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>

Tcl-level Virtual Filesystems						1.0								    vfs(n)