[tclvfs] is an excellent facility; however, there are some ''gotchas'' (as you'd expect for something that exposes the soft underbelly of [tcl]'s file system).

This page is for folklore and [here be dragons] advice.  Please track changes to any folklore you relate here, so it can be a useful resource for implementors and not a collection of old wives' tales.  

Also please file bug reports or feature requests for problems you run into where you believe there is a better or more correct behaviour.

----
Never error out of the fileattributes command - it is used by tcl core to copy files, and throwing an error from it ''will]' sigsegv. Subject to a bug report [http://sourceforge.net/tracker/index.php?func=detail&aid=1022202&group_id=32692&atid=406308] -- [CMcC] 20040904

[Vince] -- this is fixed in a sufficiently recent version of Tcl/tclvfs.

[CMcC] -- should the bug report be closed, then?  And some sort of [cvs] update to repair the error?  I haven't seen any cvs action after submitting it, and it was definitely present in cvs HEAD of tcl and tclvfs at the date of the bug report submission.

----
Never close the file descriptor passed into the command invoked on file close.  Let tclvfs do it for you. -- [CMcC] 20040904

[SEH] -- Because if you do, Tcl will crash.

[Vince] -- this is fixed in a sufficiently recent version of Tcl/tclvfs.

----
[SEH] -- The vfs api layer will catch all errors in the close callback procedure, so if the procedure aborts due to an error, the close command that invoked the callback will still return OK, giving no indication that the close procedure failed and thus possibly lost data.

----
[SEH] -- Although the ''w'' channel open mode is supported in theory, in practice when the channel is passed to the [close] callback to be handled no capability is provided to read what's been written to the channel.  Thus the written data is inaccessible to the vfs programmer.

So unless you want to limit yourself to read-only filesystems, you must kludge things somehow, like silently switching the mode to w+ in the [open] procedure and hoping nobody using the vfs assumes a file opened for writing only will have reads blocked.

[CMcC] I had problems with an old version of [memchan] which aped this.  I see this problem, at base, is that the implementor of a vfs wants to create a channel in one mode (to give to a user), and subsequently escalate that mode to perform more powerful operations.

It would be possible to achieve this escalation in the tclvfs C code which calls the close callback - automatically escalating mode to the maximum possible.  This would require a [TIP] to expose those mode bits to extensions.

----
[SEH] -- You can't use [fcopy] in the close callback, or otherwise pass data directly from one file channel to another.  You have to read channel data into a variable, then write it from the variable to the target channel.

[CMcC] Once a channel is closed, the only file facilities which the i/o core will permit are    read and write.  Asynchronous operations ought to be possible, but are probably risky.

----
[[[Category VFS]]]