From 710bfd25143e889199b76d1b01e688de8a408cf2 Mon Sep 17 00:00:00 2001 From: Andreas Kupries Date: Thu, 15 Jul 2004 16:59:14 +0000 Subject: [PATCH] * 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. --- ChangeLog | 7 +++++++ doc/vfs-fsapi.man | 36 +++++++++++++++++++++++------------- 2 files changed, 30 insertions(+), 13 deletions(-) diff --git a/ChangeLog b/ChangeLog index d307fab..eda8f77 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2004-07-15 Andreas Kupries + + * 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 * doc/*: fix to removedirectory docs which should say to return diff --git a/doc/vfs-fsapi.man b/doc/vfs-fsapi.man index a2b2f2c..ba5c32e 100644 --- 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] -- 2.23.0