done
diff --git a/man/man3/venti-cache.3 b/man/man3/venti-cache.3
index bdd18ec..d74145a 100644
--- a/man/man3/venti-cache.3
+++ b/man/man3/venti-cache.3
@@ -24,6 +24,8 @@
#include <venti.h>
.ta +\w'\fLxxxx 'u
.PP
+.ft L
+.nf
typedef struct VtBlock
{
uchar *data;
@@ -35,16 +37,13 @@
.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 @@
.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 @@
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 @@
frees a cache and all the associated blocks.
.PP
.I Vtcacheblocksize
+returns the cache's maximum block size.
.PP
-XXX global vs local blocks
+.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 @@
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 @@
.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 ec18fc4..cc8d14f 100644
--- a/man/man3/venti-client.3
+++ b/man/man3/venti-client.3
@@ -8,7 +8,7 @@
#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 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 @@
.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 @@
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 @@
.I n
bytes in
.I buf
-with type
+as a block of the given
.IR type ,
setting
.IR score .
@@ -177,7 +175,6 @@
.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 @@
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 bc2de00..293777c 100644
--- a/man/man3/venti-conn.3
+++ b/man/man3/venti-conn.3
@@ -61,6 +61,18 @@
.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 @@
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 @@
.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 e5bdfa9..2eb0cea 100644
--- a/man/man3/venti-fcall.3
+++ b/man/man3/venti-fcall.3
@@ -14,7 +14,7 @@
vtrootpack,
vtrootunpack,
vtparsescore,
-vtscorefmt \- Venti external data representation
+vtscorefmt \- venti data formats
.SH SYNOPSIS
.PP
.ft L
@@ -31,7 +31,6 @@
{
VtEntrySize = 40,
VtRootSize = 300,
- VtRootVersion = 2,
VtScoreSize = 20,
};
.PP
@@ -39,9 +38,9 @@
.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 @@
{
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 @@
.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 @@
.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 @@
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 @@
.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 dfb7bf4..690fd45 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 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 @@
.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 @@
.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 @@
.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 @@
.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 @@
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 @@
.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 bc4efe7..6b74c6c 100644
--- a/man/man3/venti-log.3
+++ b/man/man3/venti-log.3
@@ -50,17 +50,19 @@
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 @@
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 46b2bb3..0a872a0 100644
--- a/man/man3/venti-mem.3
+++ b/man/man3/venti-mem.3
@@ -39,10 +39,9 @@
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 7d5a518..1b70673 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 @@
Packet* packetalloc(void);
.PP
.B
-void packetfree(Packet *p)
-.PP
-.B
-Packet* packetforeign(uchar *buf, int n,
-.br
-.B
- void (*free)(void *a), void *a)
-.PP
-.B
-Packet* packetdup(Packet *p, int offset, int n)
-.PP
-.B
-Packet* packetsplit(Packet *p, int n)
-.PP
-.B
-int packetconsume(Packet *p, uchar *buf, int n)
-.PP
-.B
-int packettrim(Packet *p, int offset, int n)
-.PP
-.B
-uchar* packetheader(Packet *p, int n)
-.PP
-.B
-uchar* packettrailer(Packet *p, int n)
-.PP
-.B
-void packetprefix(Packet *p, uchar *buf, int n)
-.PP
-.B
void packetappend(Packet *p, uchar *buf, int n)
.PP
.B
-void packetconcat(Packet *p, Packet *q)
-.PP
-.B
-uchar* packetpeek(Packet *p, uchar *buf, int offset, int n)
-.PP
-.B
-int packetcopy(Packet *p, uchar *buf, int offset, int n)
-.PP
-.B
-int packetfragments(Packet *p, IOchunk *io, int nio,
-.br
-.B
- int offset)
-.PP
-.B
-uint packetsize(Packet *p)
-.PP
-.B
uint packetasize(Packet *p)
.PP
.B
int packetcmp(Packet *p, Packet *q)
.PP
.B
-void packetstats(void)
+void packetconcat(Packet *p, Packet *q)
+.PP
+.B
+int packetconsume(Packet *p, uchar *buf, int n)
+.PP
+.B
+int packetcopy(Packet *p, uchar *buf, int offset, int n)
+.PP
+.B
+Packet* packetdup(Packet *p, int offset, int n)
+.PP
+.B
+Packet* packetforeign(uchar *buf, int n,
+.br
+.B
+ void (*free)(void *a), void *a)
+.PP
+.B
+int packetfragments(Packet *p, IOchunk *io, int nio,
+.br
+.B
+ int offset)
+.PP
+.B
+void packetfree(Packet *p)
+.PP
+.B
+uchar* packetheader(Packet *p, int n)
+.PP
+.B
+uchar* packetpeek(Packet *p, uchar *buf, int offset, int n)
+.PP
+.B
+void packetprefix(Packet *p, uchar *buf, int n)
.PP
.B
void packetsha1(Packet *p, uchar sha1[20])
+.PP
+.B
+uint packetsize(Packet *p)
+.PP
+.B
+Packet* packetsplit(Packet *p, int n)
+.PP
+.B
+void packetstats(void)
+.PP
+.B
+uchar* packettrailer(Packet *p, int n)
+.PP
+.B
+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 @@
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 @@
.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 @@
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 9dd6f34..a4a84b9 100644
--- a/man/man3/venti-server.3
+++ b/man/man3/venti-server.3
@@ -110,12 +110,13 @@
.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 c163b88..270b768 100644
--- a/man/man3/venti-zero.3
+++ b/man/man3/venti-zero.3
@@ -30,14 +30,14 @@
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 @@
.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 a2581e9..632d599 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 @@
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 @@
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 @@
.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
