document storeIOState->offset

diff --git a/doc/Programming-Guide/prog-guide.sgml b/doc/Programming-Guide/prog-guide.sgml
index 5077aa3d4cbb8ac7b9deed0daab77d2ef4a70913..226ceb165e40f11c09c734a405e0728cc5f70d40 100644 (file)
--- a/doc/Programming-Guide/prog-guide.sgml
+++ b/doc/Programming-Guide/prog-guide.sgml
@@ -718,6 +718,14 @@ Squid consists of the following major components
        <em/swap_file_number/ is the 32-bit swap file number for the
        object, taken from the <em/StoreEntry/.
 
+       <em/offset/ represents the file (byte) offset after the
+       last operation completed.  For example, after a read operation,
+       <em/offset/ must be incremented by the number of bytes read.
+       The same goes for write operations.  This means that the
+       filesystem layer needs explicit (callback) notification
+       for writes.  It is wrong to increment <em/offset/ before
+       an I/O operation has been known to succeed.
+
        Note that there are two callback functions.  The first,
        <em/callback/, of type <em/STIOCB/ (store I/O callback),
        is callback for the <em/storeIOState/ as a whole.  This
@@ -890,6 +898,15 @@ Squid consists of the following major components
        called if the read operation is successful.  If it fails,
        then the <em/STIOCB/ callback will be called instead.
 
+<sect2>Todo...
+
+       <P>
+       Note there is much work yet to be done in defining
+       this programming interface.  All of the code for
+       rebuilding the disk store at startup is still very
+       UFS-specific.  The configuration file and <em/SquidConfig/
+       data structures are still sort of specific to UFS.
+
 
 <!-- %%%% Chapter : FORWARDING SELECTION %%%% -->
 <sect>Forwarding Selection