done

11 files changed, 200 insertions, 123 deletions

diff --git a/man/man3/venti-cache.3 b/man/man3/venti-cache.3
index bdd18ec4..d74145a2 100644
--- a/man/man3/venti-cache.3
+++ b/man/man3/venti-cache.3
@@ -24,6 +24,8 @@ vtlocaltoglobal \- Venti block cache
 #include <venti.h>
 .ta +\w'\fLxxxx 'u
 .PP
+.ft L
+.nf
 typedef struct VtBlock
 {
 	uchar *data;
@@ -35,16 +37,13 @@ typedef struct VtBlock
 .ta +\w'\fLVtBlock* 'u +\w'\fLxxxxxxxx'u
 .PP
 .B
-VtCache*	vtcachealloc(VtConn *z, int blocksize, ulong nblocks, int mode);
+VtCache*	vtcachealloc(VtConn *z, int blocksize, ulong nblocks);
 .PP
 .B
 void	vtcachefree(VtCache *c);
 .PP
 .B
 u32int	vtcacheblocksize(VtCache *c);
-.br
-.B
-		int (*write)(VtConn*, uchar[VtScoreSize], uint, uchar*, int));
 .PP
 .B
 u32int	vtglobaltolocal(uchar score[VtScoreSize])
@@ -72,6 +71,9 @@ int	vtblockwrite(VtBlock *b);
 .PP
 .B
 void	vtcachesetwrite(VtCache *c,
+.br
+.B
+	   int (*write)(VtConn*, uchar[VtScoreSize], uint, uchar*, int));
 .PP
 .B
 VtBlock*	vtblockcopy(VtBlock *b);
@@ -83,6 +85,37 @@ These functions provide access to a simple in-memory
 cache of blocks already stored on a Venti server
 and blocks that will eventually be stored on a Venti server.
 .PP
+A 
+.B VtBlock
+represents a venti data block.
+Blocks stored on a venti server,
+called
+.IR "global blocks" ,
+are named by the SHA1 hash of their contents.
+This hash is recorded as the block's
+.IR score .
+Such blocks are immutable.
+The cache also stores mutable blocks that have not yet been
+written to a venti server.  These blocks are called
+.IR "local blocks" ,
+and have special scores that are 16 zero bytes
+followed by a 4-byte big-endian
+.IR address .
+The address is an index into the internal set of cache blocks.
+.PP
+The user-visible contents of a
+.B VtBlock
+are
+.BR data ,
+a pointer to the data;
+.BR type ,
+the venti block type;
+.BR score ,
+the block's score;
+and
+.BR addr ,
+the block's cache address.
+.PP
 .I Vtcachealloc
 allocates a new cache using the client connection
 .I z
@@ -99,8 +132,22 @@ of maximum block size
 frees a cache and all the associated blocks.
 .PP
 .I Vtcacheblocksize
-.PP
-XXX global vs local blocks
+returns the cache's maximum block size.
+.PP
+.I Vtglobaltolocal
+returns the local address corresponding to the given
+local
+.IR score .
+If passed a global score,
+.I vtglobaltolocal
+returns the special constant
+.B NilBlock
+.RB ( ~0 ).
+.I Vtlocaltoglobal
+is the opposite, setting
+.I score
+to the local score for the cache address
+.IR local .
 .PP
 .I Vtcacheallocblock
 allocates a new local block with the given
@@ -124,8 +171,9 @@ from the cache, consulting the Venti server
 if necessary.
 If passed a local score,
 .I vtcacheglobal
-behaves as
-.IR vtcachelocal .
+invokes
+.I vtcachelocal
+appropriately.
 .PP
 The block references returned by
 .IR vtcacheallocblock ,
@@ -191,8 +239,8 @@ or, more commonly, that cache blocks are being leaked.
 .SH SOURCE
 .B \*9/src/libventi
 .SH SEE ALSO
-.IR venti (1),
 .IR venti (3),
 .IR venti-client (3),
 .IR venti-conn (3),
-.IR venti-file (3)
+.IR venti-file (3),
+.IR venti (7)
diff --git a/man/man3/venti-client.3 b/man/man3/venti-client.3
index ec18fc4e..cc8d14f4 100644
--- a/man/man3/venti-client.3
+++ b/man/man3/venti-client.3
@@ -8,7 +8,7 @@ vtconnect, vthello, vtread, vtwrite, vtreadpacket, vtwritepacket, vtsync, vtping
 #include <libc.h>
 .br
 #include <venti.h>
-.ta +\w'\fLextern int 'u +\w'\fLxxxxxxxx'u
+.ta +\w'\fLPacket* 'u +\w'\fLxxxxxxxx'u
 .PP
 .B
 Packet*	vtrpc(VtConn *z, Packet *p)
@@ -50,7 +50,7 @@ int	vtsync(VtConn *z)
 int	vtping(VtConn *z)
 .PP
 .B
-extern int	ventidoublechecksha1;	/* default 1 */
+extern int ventidoublechecksha1;  /* default 1 */
 .SH DESCRIPTION
 These routines execute the client side of the 
 .IR venti (7)
@@ -73,10 +73,8 @@ is typically called only indirectly, via the functions below.
 .I Vthello
 executes a
 .B hello
-transaction
-(see
-.IR venti (7)), setting
-.IB z -> sid
+transaction, setting
+.IB z ->sid
 to the name used by the server.
 .I Vthello
 is typically called only indirectly, via
@@ -103,11 +101,11 @@ reads the block with the given
 and
 .I type
 from the server,
-writes the returned data
-to
+stores the returned data
+in memory at
 .IR buf ,
-and returns the number of bytes retrieved.
-If the stored block has size larger than
+and returns the number of bytes read.
+If the server's block has size larger than
 .IR n ,
 .I vtread 
 does not modify
@@ -120,7 +118,7 @@ writes the
 .I n
 bytes in 
 .I buf
-with type
+as a block of the given
 .IR type ,
 setting 
 .IR score .
@@ -177,7 +175,6 @@ as described in
 .SH SOURCE
 .B \*9/src/libventi
 .SH SEE ALSO
-.IR venti (1),
 .IR venti (3),
 .IR venti-conn (3),
 .IR venti-packet (3),
@@ -190,5 +187,4 @@ return nil on error.
 The other routines return \-1 on error.
 .PP
 .I Vtwrite
-returns 0 on success,
-meaning it wrote the entire block.
+returns 0 on success: there are no partial writes.
diff --git a/man/man3/venti-conn.3 b/man/man3/venti-conn.3
index bc2de00d..293777c2 100644
--- a/man/man3/venti-conn.3
+++ b/man/man3/venti-conn.3
@@ -61,6 +61,18 @@ A
 .B VtConn
 structure represents a connection to a Venti server
 (when used by a client) or to a client (when used by a server).
+It contains the following user-visible fields:
+.BR debug ,
+a flag enabling debugging prints;
+.BR version ,
+the protocol version in use;
+.BR uid ,
+the (unverified) name of the client;
+.BR sid ,
+the (unverified) name of the server;
+and
+.BR addr ,
+the network address of the remote side.
 .PP
 .I Vtconn
 initializes a new connection structure using file descriptors
@@ -81,7 +93,7 @@ exchanges version information with the remote side
 as described in
 .IR venti (7).
 The negotiated version is stored in
-.IB z -> version \fR.
+.IB z ->version \fR.
 .PP
 .I Vtsend
 writes a packet
@@ -146,7 +158,7 @@ must be the connection structure
 .I Vtdebug
 prints the formatted message to standard error
 when
-.IB z -> debug
+.IB z ->debug
 is set.  Otherwise it is a no-op.
 .PP
 .I Vthangup
diff --git a/man/man3/venti-fcall.3 b/man/man3/venti-fcall.3
index e5bdfa9e..2eb0cea3 100644
--- a/man/man3/venti-fcall.3
+++ b/man/man3/venti-fcall.3
@@ -14,7 +14,7 @@ vtputstring,
 vtrootpack,
 vtrootunpack,
 vtparsescore,
-vtscorefmt \- Venti external data representation
+vtscorefmt \- venti data formats
 .SH SYNOPSIS
 .PP
 .ft L
@@ -31,7 +31,6 @@ enum
 {
 	VtEntrySize = 40,
 	VtRootSize = 300,
-	VtRootVersion = 2,
 	VtScoreSize = 20,
 };
 .PP
@@ -39,9 +38,9 @@ enum
 .nf
 typedef struct VtEntry
 {
-	ulong gen;			/* generation number */
-	ushort psize;			/* pointer block size */
-	ushort dsize;			/* data block size */
+	ulong gen;    /* generation number */
+	ushort psize;   /* pointer block size */
+	ushort dsize;   /* data block size */
 	uchar type;
 	uchar flags;
 	uvlong size;
@@ -54,9 +53,9 @@ typedef struct VtRoot
 {
 	char name[128];
 	char type[128];
-	uchar score[VtScoreSize];	/* to a Dir block */
-	ushort blocksize;		/* maximum block size */
-	uchar prev[VtScoreSize];	/* previous root block */
+	uchar score[VtScoreSize];  /* to a Dir block */
+	ushort blocksize;          /* maximum block size */
+	uchar prev[VtScoreSize];   /* previous root block */
 } VtRoot;
 .ta +\w'\fLPacket* 'u
 .PP
@@ -110,7 +109,7 @@ converts a
 .B VtEntry
 structure describing a Venti file
 (see
-.IR venti (1))
+.IR venti (7))
 into a 40-byte
 .RB ( VtEntrySize )
 structure at
@@ -150,7 +149,7 @@ frees the strings
 .IB f ->uid \fR,
 .IB f ->sid \fR,
 the buffers
-.I f ->crypto
+.IB f ->crypto
 and
 .IB f ->codec \fR,
 and the packet
@@ -159,11 +158,11 @@ and the packet
 The block type enumeration defined in
 .B <venti.h>
 (presented in 
-.IR venti (1))
+.IR venti (7))
 differs from the one used on disk and in the network
 protocol.
 The disk and network representation uses different
-constants does not distinguish between
+constants and does not distinguish between
 .BI VtDataType+ n
 and
 .BI VtDirType+ n
@@ -173,7 +172,10 @@ converts a
 .B <venti.h>
 enumeration value to the disk value;
 .I vtfromdisktype
-converts a disk value to the enumeration value.
+converts a disk value to the enumeration value,
+always using the
+.B VtDataType
+pointers.
 The
 .B VtFcall
 field
diff --git a/man/man3/venti-file.3 b/man/man3/venti-file.3
index dfb7bf41..690fd45c 100644
--- a/man/man3/venti-file.3
+++ b/man/man3/venti-file.3
@@ -1,29 +1,29 @@
 .TH VENTI-FILE 3
 .SH NAME
 VtFile,
-vtfileopenroot,
-vtfilecreateroot,
-vtfileopen,
-vtfilecreate,
 vtfileblock,
-vtfileread, 
-vtfilewrite,
-vtfileflush,
-vtfileincref,
-vtfileclose,
-vtfilegetentry,
-vtfilesetentry,
 vtfileblockscore,
+vtfileclose,
+vtfilecreate,
+vtfilecreateroot,
+vtfileflush,
+vtfileflushbefore,
 vtfilegetdirsize,
-vtfilesetdirsize,
-vtfileunlock,
+vtfilegetentry,
+vtfilegetsize,
+vtfileincref,
 vtfilelock,
 vtfilelock2,
-vtfileflushbefore,
-vtfiletruncate,
-vtfilegetsize,
+vtfileopen,
+vtfileopenroot,
+vtfileread, 
+vtfileremove,
+vtfilesetdirsize,
+vtfilesetentry,
 vtfilesetsize,
-vtfileremove \- Venti files
+vtfiletruncate,
+vtfileunlock,
+vtfilewrite \- Venti files
 .SH SYNOPSIS
 .ta +\w'\fLVtBlock* 'u
 .PP
@@ -85,7 +85,8 @@ int	vtfilegetentry(VtFile *f, VtEntry *e);
 int	vtfilesetentry(VtFile *f, VtEntry *e);
 .PP
 .B
-int	vtfileblockscore(VtFile *f, u32int n, uchar score[VtScoreSize]);
+int	vtfileblockscore(VtFile *f, u32int n, 
+	    uchar score[VtScoreSize]);
 .PP
 .B
 int	vtfilelock(VtFile *f, int mode);
@@ -98,11 +99,11 @@ void	vtfileunlock(VtFile *f);
 .SH DESCRIPTION
 These routines provide a simple interface to create and
 manipulate Venti file trees (see
-.IR venti (1)).
+.IR venti (7)).
 .PP
 .I Vtfilecreateroot
 creates a new Venti file.
-.I Btype
+.I Type
 must be either
 .B VtDataType
 or
@@ -111,7 +112,7 @@ specifying a data or directory file.
 .I Dsize
 is the block size to use for leaf (data or directory) blocks in the hash tree;
 .I psize
-is the block size to use for intermediate (pointer) blocks.
+is the block size to use for internal (pointer) blocks.
 .PP
 .I Vtfileopenroot
 opens an existing Venti file described by
@@ -124,19 +125,19 @@ entry in the directory
 .IR f .
 .I Mode
 should be one of
-.IR VtOREAD ,
-.IR VtOWRITE ,
+.BR VtOREAD ,
+.BR VtOWRITE ,
 or
-.IR VtORDWR ,
+.BR VtORDWR ,
 indicating how the returned file is to be used.
 The
-.IR VtOWRITE
+.BR VtOWRITE
 and
-.IR VtORDWR
+.BR VtORDWR
 modes can only be used if
 .IR f
 is open with mode
-.IR VtORDWR .
+.BR VtORDWR .
 .PP
 .I Vtfilecreate
 creates a new file in the directory
@@ -239,7 +240,7 @@ Loops that
 .I vtfilewrite
 should call
 .I vtfileflushbefore
-regularly to avoid filling the block cache with dirty blocks.
+regularly to avoid filling the block cache with unwritten blocks.
 .PP
 .I Vtfiletruncate
 changes the file
@@ -283,7 +284,7 @@ to be
 returns in
 .I score
 the score of the
-.I n th
+.IR n th
 block in the file
 .IR f .
 .PP
@@ -318,7 +319,7 @@ in the same directory block.
 .SH SOURCE
 .B \*9/src/libventi/file.c
 .SH SEE ALSO
-.IR venti (1),
 .IR venti-cache (3),
 .IR venti-conn (3),
-.IR venti-client (3)
+.IR venti-client (3),
+.IR venti (7)
diff --git a/man/man3/venti-log.3 b/man/man3/venti-log.3
index bc4efe76..6b74c6cd 100644
--- a/man/man3/venti-log.3
+++ b/man/man3/venti-log.3
@@ -50,17 +50,19 @@ extern char *VtServerLog;    /* "libventi/server" */
 These routines provide an in-memory circular log
 structure used by the Venti library and the Venti server
 to record events for debugging purposes.
-The logs have textual names represented as UTF strings.
+The logs are named by UTF strings.
 .PP
 .I Vtlogopen
-returns a reference to the log named
+returns a reference to the log with the given
 .I name .
 If a log with that name does not exist and
 .I size 
-is non-zero, a new log capable of holding at
+is non-zero,
+.I vtlogopen
+creates a new log capable of holding at
 least
 .I size
-bytes is allocated and returned.
+bytes and returns it.
 .I Vtlogclose
 releases the reference returned by
 .IR vtlogopen .
@@ -126,8 +128,9 @@ and
 writes debugging information to the log named
 .IR VtServerLog ,
 which defaults to the string
-.LR libventi/server .
+.RB ` libventi/server '.
 .SH SOURCE
 .B \*9/src/libventi
 .SH SEE ALSO
-.IR venti (3)
+.IR venti (3),
+.IR venti (8)
diff --git a/man/man3/venti-mem.3 b/man/man3/venti-mem.3
index 46b2bb31..0a872a0a 100644
--- a/man/man3/venti-mem.3
+++ b/man/man3/venti-mem.3
@@ -39,10 +39,9 @@ On failure, they print an error message and call
 They do not return.
 .PP
 .I Vtbrk
-returns a pointer to a new block of at least
+returns a pointer to a new, permanently allocated block of at least
 .I size
 bytes.
-The block cannot be freed.
 .PP
 .IR Vtmalloc ,
 .IR vtrealloc ,
diff --git a/man/man3/venti-packet.3 b/man/man3/venti-packet.3
index 7d5a518f..1b70673f 100644
--- a/man/man3/venti-packet.3
+++ b/man/man3/venti-packet.3
@@ -1,11 +1,26 @@
 .TH VENTI-PACKET 3
 .SH NAME
-Packet, packetalloc, packetfree, packetforeign, packetdup,
-packetsplit, packetconsume, packettrim, packetheader, 
-packettrailer, packetprefix, packetappend, packetconcat,
-packetpeek, packetcopy, packetfragments,
-packetsize, packetasize, packetcompact, packetcmp,
-packetstats, packetsha1 \- zero-copy network buffers
+Packet,
+packetalloc,
+packetappend,
+packetasize,
+packetcmp,
+packetconcat,
+packetconsume,
+packetcopy,
+packetdup,
+packetforeign,
+packetfragments,
+packetfree,
+packetheader,
+packetpeek,
+packetprefix,
+packetsha1,
+packetsize,
+packetsplit,
+packetstats,
+packettrailer,
+packettrim \- zero-copy network buffers
 .SH SYNOPSIS
 .ft L
 #include <u.h>
@@ -21,72 +36,73 @@ packetstats, packetsha1 \- zero-copy network buffers
 Packet*	packetalloc(void);
 .PP
 .B
-void	packetfree(Packet *p)
+void	packetappend(Packet *p, uchar *buf, int n)
 .PP
 .B
-Packet*	packetforeign(uchar *buf, int n,
-.br
-.B
-		void (*free)(void *a), void *a)
+uint	packetasize(Packet *p)
 .PP
 .B
-Packet*	packetdup(Packet *p, int offset, int n)
+int	packetcmp(Packet *p, Packet *q)
 .PP
 .B
-Packet*	packetsplit(Packet *p, int n)
+void	packetconcat(Packet *p, Packet *q)
 .PP
 .B
 int	packetconsume(Packet *p, uchar *buf, int n)
 .PP
 .B
-int	packettrim(Packet *p, int offset, int n)
+int	packetcopy(Packet *p, uchar *buf, int offset, int n)
 .PP
 .B
-uchar*	packetheader(Packet *p, int n)
+Packet*	packetdup(Packet *p, int offset, int n)
 .PP
 .B
-uchar*	packettrailer(Packet *p, int n)
+Packet*	packetforeign(uchar *buf, int n,
+.br
+.B
+		void (*free)(void *a), void *a)
 .PP
 .B
-void	packetprefix(Packet *p, uchar *buf, int n)
+int	packetfragments(Packet *p, IOchunk *io, int nio,
+.br
+.B
+		int offset)
 .PP
 .B
-void	packetappend(Packet *p, uchar *buf, int n)
+void	packetfree(Packet *p)
 .PP
 .B
-void	packetconcat(Packet *p, Packet *q)
+uchar*	packetheader(Packet *p, int n)
 .PP
 .B
 uchar*	packetpeek(Packet *p, uchar *buf, int offset, int n)
 .PP
 .B
-int	packetcopy(Packet *p, uchar *buf, int offset, int n)
+void	packetprefix(Packet *p, uchar *buf, int n)
 .PP
 .B
-int	packetfragments(Packet *p, IOchunk *io, int nio,
-.br
-.B
-		int offset)
+void	packetsha1(Packet *p, uchar sha1[20])
 .PP
 .B
 uint	packetsize(Packet *p)
 .PP
 .B
-uint	packetasize(Packet *p)
+Packet*	packetsplit(Packet *p, int n)
 .PP
 .B
-int	packetcmp(Packet *p, Packet *q)
+void	packetstats(void)
 .PP
 .B
-void	packetstats(void)
+uchar*	packettrailer(Packet *p, int n)
 .PP
 .B
-void	packetsha1(Packet *p, uchar sha1[20])
+int	packettrim(Packet *p, int offset, int n)
 .SH DESCRIPTION
 A
 .B Packet
-is a list of blocks of data.
-Each block is contiguous in memory, but the entire packet
+is a chain of blocks of data.
+Each block, called a fragment,
+is contiguous in memory, but the entire packet
 may not be.
 This representation helps avoid unnecessary memory copies.
 .PP
@@ -107,7 +123,7 @@ returns the number of data bytes allocated to
 This may be larger than the number of bytes stored
 in
 .IR p
-because individual fragments may not be filled.
+because fragments may not be filled completely.
 .PP
 .I Packetcmp
 compares the data sections of two packets as
@@ -214,7 +230,7 @@ computes the SHA1 hash of the data contained in
 .IR p .
 .PP
 .I Packetsize
-returns the number of bytes of data contained in
+returns the length, in bytes, of the data contained in
 .IR p .
 .PP
 .I Packetsplit
@@ -263,4 +279,3 @@ whose return values are described above.
 When these functions run out of memory, they
 print error messages and call
 .IR sysfatal .
-They do not return.
diff --git a/man/man3/venti-server.3 b/man/man3/venti-server.3
index 9dd6f347..a4a84b90 100644
--- a/man/man3/venti-server.3
+++ b/man/man3/venti-server.3
@@ -110,12 +110,13 @@ is a read-only Venti proxy (it rejects
 .B write
 requests).
 .I Devnull
-is a write-only Venti server: it discards all
+is a dangerous write-only Venti server: it discards all
 blocks written to it and returns error on all reads.
 .SH SOURCE
 .B \*9/src/libventi
 .SH SEE ALSO
-.IR venti (1),
 .IR venti (3),
 .IR venti-conn (3),
-.IR venti-packet (3)
+.IR venti-packet (3),
+.IR venti (7),
+.IR venti (8)
\ No newline at end of file
diff --git a/man/man3/venti-zero.3 b/man/man3/venti-zero.3
index c163b888..270b7680 100644
--- a/man/man3/venti-zero.3
+++ b/man/man3/venti-zero.3
@@ -30,14 +30,14 @@ returns the size of the
 buffer pointed to by
 .I buf
 ignoring trailing zeros or zero scores,
-according to the block type
+according to the given
 .IR type .
 .PP
 .I Vtzeroextend
 pads
 .I buf
 with zeros or zero scores,
-according to the block type
+according to the given
 .IR type ,
 to grow it from
 .I size
@@ -52,5 +52,5 @@ is the score of the zero-length block.
 .br
 .B \*9/src/libventi/zeroscore.c
 .SH SEE ALSO
-.IR venti (1),
-.IR venti (3)
+.IR venti (3),
+.IR venti (7)
diff --git a/man/man3/venti.3 b/man/man3/venti.3
index a2581e98..632d5998 100644
--- a/man/man3/venti.3
+++ b/man/man3/venti.3
@@ -1,6 +1,6 @@
 .TH VENTI 3
 .SH NAME
-xxx \- Venti storage server
+venti \- archival storage server
 .SH SYNOPSIS
 .PP
 .ft L
@@ -28,7 +28,7 @@ describe routines for writing clients
 and servers on top of these.
 .PP
 .IR Venti-fcall (3)
-describes the in-memory representation of Venti protocol messages
+describes the C representation of Venti protocol messages
 and data structures.
 It also describes routines that convert between the C representation
 and the network and disk representations.
@@ -37,7 +37,7 @@ and the network and disk representations.
 describes routines for writing clients that manipulate
 Venti file trees
 (see
-.IR venti (1)).
+.IR venti (7)).
 .PP
 .IR Venti-log (3)
 describes routines to access in-memory log buffers
@@ -51,13 +51,13 @@ routines that abort on error.
 .PP
 .IR Venti-packet (3)
 describes routines for 
-efficiently manipulating chains of
+manipulating zero-copy chains of
 data buffers.
 .PP
 .IR Venti-zero (3)
 describes routines to zero truncate and zero extend blocks
 (see
-.IR venti (1)).
+.IR venti (7)).
 .SH SOURCE
 .B \*9/src/libventi
 .SH SEE ALSO