* doc/vfs-fsapi.man: Clarified description of the close callback

	the handler method 'open' may set up. Especially noted that
	'close' must not be called from within this callback, that it is
	done by the caller itself.

diff --git a/ChangeLog b/ChangeLog
index d307fab5d4af1bcb281fbd8182f3ee654255c2f5..eda8f776fc8c3f6beb2584a9519ea224421ec7a0 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2004-07-15  Andreas Kupries  <andreask@activestate.com>
+
+       * doc/vfs-fsapi.man: Clarified description of the close callback
+       the handler method 'open' may set up. Especially noted that
+       'close' must not be called from within this callback, that it is
+       done by the caller itself.
+
 2004-07-15  Vince Darley <vincentdarley@sourceforge.net>
 
        * doc/*: fix to removedirectory docs which should say to return

diff --git a/doc/vfs-fsapi.man b/doc/vfs-fsapi.man
index a2b2f2cb4468d67ef48c23e94bef310d81beec1e..ba5c32e95c3e722265e056cdfc46e643b80a854d 100644 (file)
--- a/doc/vfs-fsapi.man
+++ b/doc/vfs-fsapi.man
@@ -55,6 +55,7 @@ directory [file xxx],
 [enum]
 and the command executed is [cmd {file exists yyy}].
 [list_end]
+[nl]
 
 The file separator between [arg root] and [arg relative] is omitted.
 Most filesystem operations need only the [arg relative] argument for
@@ -198,22 +199,31 @@ throws an error describing how the operation failed.
 The list returned upon success contains at least one and at most two
 elements. The first, obligatory, element is always the handle of the
 channel which was created to allow access to the contents of the
-file. If specified the second element will be interpreted as a
-callback, i.e. a command prefix. This prefix will always be executed
-as is, i.e. without additional arguments. Any required arguments have
-to be returned as part of the result of the call to [method open].
+file.
+
+[nl]
+
+If specified the second element will be interpreted as a callback,
+i.e. a command prefix. This prefix will always be executed as is,
+i.e. without additional arguments. Any required arguments have to be
+returned as part of the result of the call to [method open].
+
+[nl]
+
+If present the specified callback will be evaluated just before the
+channel is closed [emph {by the generic filesystem layer}]. The
+callback itself [emph {must not}] call [cmd close].
 
 [nl]
 
-If present the specified callback will be evaluated by the generic
-filesystem layer just before the channel whose handle was returned as
-the first element of the list is closed. Additionally all available
-data will have been flushed into it. This means, for example, that the
-callback can seek to the beginning of the said channel, read its
-contents and then store the gathered data elsewhere. In other words,
-this callback is not only crucial to the cleanup of any resources
-associated with an opened file, but also for the ability to implement
-a filesystem which can be written to.
+The channel however is live enough to allow [cmd seek] and [cmd read]
+operations. In addition all available data will have been flushed into
+it already. This means, for example, that the callback can seek to the
+beginning of the said channel, read its contents and then store the
+gathered data elsewhere. In other words, this callback is not only
+crucial to the cleanup of any resources associated with an opened
+file, but also for the ability to implement a filesystem which can be
+written to.
 
 [nl]