diff options
Diffstat (limited to 'man/man3')
| -rw-r--r-- | man/man3/venti-cache.3 | 68 | ||||
| -rw-r--r-- | man/man3/venti-client.3 | 24 | ||||
| -rw-r--r-- | man/man3/venti-conn.3 | 16 | ||||
| -rw-r--r-- | man/man3/venti-fcall.3 | 28 | ||||
| -rw-r--r-- | man/man3/venti-file.3 | 63 | ||||
| -rw-r--r-- | man/man3/venti-log.3 | 15 | ||||
| -rw-r--r-- | man/man3/venti-mem.3 | 3 | ||||
| -rw-r--r-- | man/man3/venti-packet.3 | 81 | ||||
| -rw-r--r-- | man/man3/venti-server.3 | 7 | ||||
| -rw-r--r-- | man/man3/venti-zero.3 | 8 | ||||
| -rw-r--r-- | man/man3/venti.3 | 10 |
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 |