From be7cbb4ef2cb02aa9ac48c02dc1ee585a8e49043 Mon Sep 17 00:00:00 2001 From: rsc Date: Tue, 12 Jul 2005 15:24:18 +0000 Subject: venti, now with documentation! --- man/man3/venti-cache.3 | 198 +++++++++++++++++++++++++++++ man/man3/venti-client.3 | 194 +++++++++++++++++++++++++++++ man/man3/venti-conn.3 | 188 ++++++++++++++++++++++++++++ man/man3/venti-fcall.3 | 273 ++++++++++++++++++++++++++++++++++++++++ man/man3/venti-file.3 | 324 ++++++++++++++++++++++++++++++++++++++++++++++++ man/man3/venti-log.3 | 133 ++++++++++++++++++++ man/man3/venti-mem.3 | 67 ++++++++++ man/man3/venti-packet.3 | 266 +++++++++++++++++++++++++++++++++++++++ man/man3/venti-server.3 | 121 ++++++++++++++++++ man/man3/venti-zero.3 | 56 +++++++++ man/man3/venti.3 | 75 +++++++++++ 11 files changed, 1895 insertions(+) create mode 100644 man/man3/venti-cache.3 create mode 100644 man/man3/venti-client.3 create mode 100644 man/man3/venti-conn.3 create mode 100644 man/man3/venti-fcall.3 create mode 100644 man/man3/venti-file.3 create mode 100644 man/man3/venti-log.3 create mode 100644 man/man3/venti-mem.3 create mode 100644 man/man3/venti-packet.3 create mode 100644 man/man3/venti-server.3 create mode 100644 man/man3/venti-zero.3 create mode 100644 man/man3/venti.3 (limited to 'man/man3') diff --git a/man/man3/venti-cache.3 b/man/man3/venti-cache.3 new file mode 100644 index 00000000..bdd18ec4 --- /dev/null +++ b/man/man3/venti-cache.3 @@ -0,0 +1,198 @@ +.TH VENTI-CACHE 3 +.SH NAME +VtBlock, VtCache, +vtblockcopy, +vtblockdirty, +vtblockduplock, +vtblockput, +vtblockwrite, +vtcachealloc, +vtcacheallocblock, +vtcacheblocksize, +vtcachefree, +vtcacheglobal, +vtcachelocal, +vtcachesetwrite, +vtglobaltolocal, +vtlocaltoglobal \- Venti block cache +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLxxxx 'u +.PP +typedef struct VtBlock +{ + uchar *data; + uchar type; + uchar score[VtScoreSize]; + u32int addr; + ... +} VtBlock; +.ta +\w'\fLVtBlock* 'u +\w'\fLxxxxxxxx'u +.PP +.B +VtCache* vtcachealloc(VtConn *z, int blocksize, ulong nblocks, int mode); +.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]) +.br +.B +void vtlocaltoglobal(u32int local, uchar score[VtScoreSize]) +.PP +.B +VtBlock* vtcacheallocblock(VtCache *c, int type); +.PP +.B +VtBlock* vtcachelocal(VtCache *c, u32int addr, int type); +.PP +.B +VtBlock* vtcacheglobal(VtCache *c, uchar[VtScoreSize], int type); +.PP +.B +void vtblockput(VtBlock *b); +.PP +.B +void vtblockduplock(VtBlock *b); +.PP +.B +int vtblockwrite(VtBlock *b); +.PP +.B +void vtcachesetwrite(VtCache *c, +.PP +.B +VtBlock* vtblockcopy(VtBlock *b); +.PP +.B +int vtblockdirty(VtBlock *b); +.SH DESCRIPTION +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 +.I Vtcachealloc +allocates a new cache using the client connection +.I z +(see +.IR venti-conn (3) +and +.IR venti-client (3)), +with room for +.I nblocks +of maximum block size +.I blocksize . +.PP +.I Vtcachefree +frees a cache and all the associated blocks. +.PP +.I Vtcacheblocksize +.PP +XXX global vs local blocks +.PP +.I Vtcacheallocblock +allocates a new local block with the given +.IR type . +.PP +.I Vtcachelocal +retrieves the local block at address +.I addr +from the cache. +The given +.I type +must match the type of the block found at +.IR addr . +.PP +.I Vtcacheglobal +retrieves the block with the given +.I score +and +.I dtype +from the cache, consulting the Venti server +if necessary. +If passed a local score, +.I vtcacheglobal +behaves as +.IR vtcachelocal . +.PP +The block references returned by +.IR vtcacheallocblock , +.IR vtcachelocal , +and +.I vtcacheglobal +must be released when no longer needed. +.I Vtblockput +releases such a reference. +.PP +It is occasionally convenient to have multiple variables +refer to the same block. +.I Vtblockduplock +increments the block's reference count so that +an extra +.I vtblockput +will be required in order to release the block. +.PP +.I Vtblockwrite +writes a local block to the Venti server, +changing the block to a global block. +It calls the cache's +.I write +function +to write the block to the server. +The default +.I write +function is +.I vtwrite +(see +.IR venti-client (3)); +.I vtsetcachewrite +sets it. +.I Vtsetcachewrite +is used by clients to install replacement functions +that run writes in the background or perform other +additional processing. +.PP +.I Vtblockcopy +copies a block in preparation for modifying its contents. +The old block may be a local or global block, +but the new block will be a local block. +.PP +The cache only evicts global blocks. +Local blocks can only leave the cache via +.IR vtblockwrite , +which turns them into global blocks, making them candidates for +eviction. +.PP +If a new cache block must be allocated (for +.IR vtcacheallocblock , +.IR vtcachelocal , +.IR vtcacheglobal , +or +.IR vtblockcopy ), +but the cache is filled (with local blocks and blocks that +have not yet been released with +.IR vtblockput ), +the library prints the score and reference count of +every block in the cache and then aborts. +A full cache indicates either that the cache is too small, +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) diff --git a/man/man3/venti-client.3 b/man/man3/venti-client.3 new file mode 100644 index 00000000..ec18fc4e --- /dev/null +++ b/man/man3/venti-client.3 @@ -0,0 +1,194 @@ +.TH VENTI-CLIENT 3 +.SH NAME +vtconnect, vthello, vtread, vtwrite, vtreadpacket, vtwritepacket, vtsync, vtping, vtrpc, ventidoublechecksha1 \- Venti client +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLextern int 'u +\w'\fLxxxxxxxx'u +.PP +.B +Packet* vtrpc(VtConn *z, Packet *p) +.PP +.B +int vthello(VtConn *z) +.PP +.B +int vtconnect(VtConn *z) +.PP +.B +int vtread(VtConn *z, uchar score[VtScoreSize], +.br +.B + uint type, uchar *buf, int n) +.PP +.B +int vtwrite(VtConn *z, uchar score[VtScoreSize], +.br +.B + uint type, uchar *buf, int n) +.PP +.B +Packet* vtreadpacket(VtConn *z, uchar score[VtScoreSize], +.br +.B + uint type, int n) +.PP +.B +int vtwritepacket(VtConn *z, uchar score[VtScoreSize], +.br +.B + uint type, Packet *p) +.PP +.B +int vtsync(VtConn *z) +.PP +.B +int vtping(VtConn *z) +.PP +.B +extern int ventidoublechecksha1; /* default 1 */ +.SH DESCRIPTION +These routines execute the client side of the +.IR venti (7) +protocol. +.PP +.I Vtrpc +executes a single Venti RPC transaction, sending the request +packet +.IR p +and then waiting for and returning the response packet. +.I Vtrpc +will set the tag in the packet. +.I Vtrpc +frees +.IR p , +even on error. +.I Vtrpc +is typically called only indirectly, via the functions below. +.PP +.I Vthello +executes a +.B hello +transaction +(see +.IR venti (7)), setting +.IB z -> sid +to the name used by the server. +.I Vthello +is typically called only indirectly, via +.IR vtconnect . +.PP +.I Vtconnect +calls +.I vtversion +(see +.IR venti-conn (3)) +and +.IR vthello , +in that order, returning success only +if both succeed. +This sequence (calling +.I vtversion +and then +.IR vthello ) +must be done before the functions below can be called. +.PP +.I Vtread +reads the block with the given +.I score +and +.I type +from the server, +writes the returned data +to +.IR buf , +and returns the number of bytes retrieved. +If the stored block has size larger than +.IR n , +.I vtread +does not modify +.I buf +and +returns an error. +.PP +.I Vtwrite +writes the +.I n +bytes in +.I buf +with type +.IR type , +setting +.IR score . +.PP +.I Vtreadpacket +and +.I vtwritepacket +are like +.I vtread +and +.I vtwrite +but return or accept the block contents in the +form of a +.BR Packet . +They avoid making a copy of the data. +.PP +.I Vtsync +causes the server to flush all pending write requests +to disk before returning. +.PP +.I Vtping +executes a ping transaction with the server. +.PP +By default, +.I vtread +and +.I vtreadpacket +check that the SHA1 hash of the returned data +matches the requested +.IR score , +and +.I vtwrite +and +.I vtwritepacket +check that the returned +.I score +matches the SHA1 hash of the written data. +Setting +.I ventidoublechecksha1 +to zero disables these extra checks, +mainly for benchmarking purposes. +Doing so in production code is not recommended. +.PP +These functions can be called from multiple threads +or procs simultaneously to issue requests +in parallel. +Programs that issue requests from multiple threads +in the same proc should start separate procs running +.I vtsendproc +and +.I vtrecvproc +as described in +.IR venti-conn (3). +.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 (7) +.SH DIAGNOSTICS +.I Vtrpc +and +.I vtpacket +return nil on error. +The other routines return \-1 on error. +.PP +.I Vtwrite +returns 0 on success, +meaning it wrote the entire block. diff --git a/man/man3/venti-conn.3 b/man/man3/venti-conn.3 new file mode 100644 index 00000000..bc2de00d --- /dev/null +++ b/man/man3/venti-conn.3 @@ -0,0 +1,188 @@ +.TH VENTI-CONN 3 +.SH NAME +VtConn, vtconn, vtdial, vtfreeconn, vtsend, vtrecv, vtversion, +vtdebug, vthangup \- Venti network connections +.SH SYNOPSIS +.PP +.ft L +#include +.br +#include +.br +#include +.PP +.ft L +.nf +.ta +\w'\fL 'u +typedef struct VtConn { + int debug; + char *version; + char *uid; + char *sid; + char addr[256]; + ... +} VtConn; +.PP +.ta \w'\fLextern int 'u +.B +VtConn* vtconn(int infd, int outfd) +.PP +.B +VtConn* vtdial(char *addr) +.PP +.B +int vtversion(VtConn *z) +.PP +.B +int vtsend(VtConn *z, Packet *p) +.PP +.B +Packet* vtrecv(VtConn *z) +.PP +.B +void vtrecvproc(void *z) +.PP +.B +void vtsendproc(void *z) +.PP +.B +void vtdebug(VtConn *z, char *fmt, ...) +.PP +.B +void vthangup(VtConn *z) +.PP +.B +void vtfreeconn(VtConn *z) +.PP +.B +extern int chattyventi; /* default 0 */ +.SH DESCRIPTION +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). +.PP +.I Vtconn +initializes a new connection structure using file descriptors +.I infd +and +.I outfd +(which may be the same) +for reading and writing. +.I Vtdial +dials the given network address +(see +.IR dial (3)) +and returns a corresponding connection. +It returns nil if the connection cannot be established. +.PP +.I Vtversion +exchanges version information with the remote side +as described in +.IR venti (7). +The negotiated version is stored in +.IB z -> version \fR. +.PP +.I Vtsend +writes a packet +(see +.IR venti-packet (3)) +on the connection +.IR z . +The packet +.IR p +should be a formatted Venti message as might +be returned by +.IR vtfcallpack ; +.I vtsend +will add the two-byte length field +(see +.IR venti (7)) +at the begnning. +.I Vtsend +frees +.IR p , +even on error. +.PP +.I Vtrecv +reads a packet from the connection +.IR z . +Analogous to +.IR vtsend , +the data read from the connection must start with +a two-byte length, but the returned packet will omit them. +.PP +By default, +.I vtsend +and +.I vtrecv +block until the packet can be written or read from the network. +In a threaded program +(see +.IR thread (3)), +this may not be desirable. +If the caller arranges for +.IR vtsendproc +and +.IR vtrecvproc +to run in their own procs +(typically by calling +.IR proccreate ), +then +.I vtsend +and +.I vtrecv +will yield the proc in which they are run +to other threads when waiting on the network. +The +.B void* +argument to +.I vtsendproc +and +.I vtrecvproc +must be the connection structure +.IR z . +.PP +.I Vtdebug +prints the formatted message to standard error +when +.IB z -> debug +is set. Otherwise it is a no-op. +.PP +.I Vthangup +hangs up a connection. +It closes the associated file descriptors +and shuts down send and receive procs if they have been +started. +Future calls to +.IR vtrecv +or +.IR vtsend +will return errors. +Additional calls to +.I vthangup +will have no effect. +.PP +.I Vtfreeconn +frees the connection structure, hanging it up first +if necessary. +.PP +If the global variable +.I chattyventi +is set, the library prints all Venti RPCs to standard error +as they are sent or received. +.SH SOURCE +.B \*9/src/libventi +.SH SEE ALSO +.IR venti (1), +.IR venti (3), +.IR venti-client (3), +.IR venti-packet (3), +.IR venti-server (3), +.IR venti (7) +.SH DIAGNOSTICS +Routines that return pointers return nil on error. +Routines returning integers return 0 on success, \-1 on error. +All routines set +.I errstr +on error. diff --git a/man/man3/venti-fcall.3 b/man/man3/venti-fcall.3 new file mode 100644 index 00000000..e5bdfa9e --- /dev/null +++ b/man/man3/venti-fcall.3 @@ -0,0 +1,273 @@ +.TH VENTI-FCALL 3 +.SH NAME +VtEntry, VtFcall, VtRoot, +vtentrypack, +vtentryunpack, +vtfcallclear, +vtfcallfmt, +vtfcallpack, +vtfcallunpack, +vtfromdisktype, +vttodisktype, +vtgetstring, +vtputstring, +vtrootpack, +vtrootunpack, +vtparsescore, +vtscorefmt \- Venti external data representation +.SH SYNOPSIS +.PP +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLxxxx'u +.PP +.ft L +.nf +enum +{ + VtEntrySize = 40, + VtRootSize = 300, + VtRootVersion = 2, + VtScoreSize = 20, +}; +.PP +.ft L +.nf +typedef struct VtEntry +{ + ulong gen; /* generation number */ + ushort psize; /* pointer block size */ + ushort dsize; /* data block size */ + uchar type; + uchar flags; + uvlong size; + uchar score[VtScoreSize]; +} VtEntry; +.PP +.ft L +.nf +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 */ +} VtRoot; +.ta +\w'\fLPacket* 'u +.PP +.B +void vtentrypack(VtEntry *e, uchar *buf, int index) +.br +.B +int vtentryunpack(VtEntry *e, uchar *buf, int index) +.PP +.B +Packet* vtfcallpack(VtFcall *f) +.br +.B +int vtfcallunpack(VtFcall *f, Packet *p) +.PP +.B +void vtfcallclear(VtFcall *f) +.PP +.B +uint vttodisktype(uint type) +.br +.B +uint vtfromdisktype(uint type) +.PP +.B +int vtputstring(Packet *p, char *s) +.br +.B +int vtgetstring(Packet *p, char **s) +.PP +.B +void vtrootpack(VtRoot *r, uchar *buf) +.br +.B +int vtrootunpack(VtRoot *r, uchar *buf) +.PP +.B +int vtparsescore(char *s, char **prefix, uchar score[VtScoreSize]) +.PP +.B +int vtfcallfmt(Fmt *fmt) +.B +int vtscorefmt(Fmt *fmt) +.SH DESCRIPTION +These routines convert between C representations of Venti +structures and serialized representations used on disk and +on the network. +.PP +.I Vtentrypack +converts a +.B VtEntry +structure describing a Venti file +(see +.IR venti (1)) +into a 40-byte +.RB ( VtEntrySize ) +structure at +.IB buf + index *40 \fR. +Vtentryunpack +does the reverse conversion. +.PP +.I Vtfcallpack +converts a +.B VtFcall +structure describing a Venti protocol message +(see +.IR venti (7)) +into a packet. +.I Vtfcallunpack +does the reverse conversion. +.PP +The fields in a +.B VtFcall +are named after the protocol fields described in +.IR venti (7), +except that the +.B type +field is renamed +.BR blocktype . +The +.B msgtype +field holds the one-byte message type: +.BR VtThello , +.BR VtRhello , +and so on. +.PP +.I Vtfcallclear +frees the strings +.IB f ->error \fR, +.IB f ->version \fR, +.IB f ->uid \fR, +.IB f ->sid \fR, +the buffers +.I f ->crypto +and +.IB f ->codec \fR, +and the packet +.IB f ->data \fR. +.PP +The block type enumeration defined in +.B +(presented in +.IR venti (1)) +differs from the one used on disk and in the network +protocol. +The disk and network representation uses different +constants does not distinguish between +.BI VtDataType+ n +and +.BI VtDirType+ n +blocks. +.I Vttodisktype +converts a +.B +enumeration value to the disk value; +.I vtfromdisktype +converts a disk value to the enumeration value. +The +.B VtFcall +field +.B blocktype +is an enumeration value +.RI ( vtfcallpack +and +.I vtfcallunpack +convert to and from the disk values used in packets +automatically), +so most programs will not need to call these functions. +.PP +.I Vtputstring +appends the Venti protocol representation of the string +.I s +to the packet +.IR p . +.I Vtgetstring +reads a string from the packet, returning a pointer to a copy +of the string in +.BI * s \fR. +The copy must be freed by the caller. +These functions are used by +.I vtfcallpack +and +.IR vtfcallunpack ; +most programs will not need to call them directly. +.PP +.I Vtrootpack +converts a +.B VtRoot +structure describing a Venti file tree +into the 300-byte +.RB ( VtRootSize ) +buffer pointed to by +.IR buf . +.I Vtrootunpack does the reverse conversion. +.PP +.I Vtparsescore +parses the 40-digit hexadecimal string +.IR s , +writing its value +into +.IR score . +If the hexadecimal string is prefixed with +a text label followed by a colon, a copy of that +label is returned in +.BI * prefix \fR. +If +.I prefix +is nil, the label is ignored. +.PP +.I Vtfcallfmt +and +.I vtscorefmt +are +.IR print (3) +formatters to print +.B VtFcall +structures and scores. +.I Vtfcallfmt +assumes that +.I vtscorefmt +is installed as +.BR %V . +.SH SOURCE +.B \*9/src/libventi +.SH SEE ALSO +.IR venti (1), +.IR venti (3), +.IR venti (7) +.SH DIAGNOSTICS +.IR Vtentrypack , +.IR vtfcallpack , +.IR vtrootpack , +and +.I vtfcallclear +cannot fail. +.PP +.IR Vtentryunpack , +.IR vtrootunpack , +.IR vtputstring , +.IR vtgetstring , +and +.I vtparsescore +return 0 on success, \-1 on error. +.PP +.I Vtfcallpack +returns a packet on success, nil on error. +.PP +.I Vttodisktype +and +.I vtfromdisktype +return +.B VtCorruptType +(255) +when presented with invalid input. diff --git a/man/man3/venti-file.3 b/man/man3/venti-file.3 new file mode 100644 index 00000000..dfb7bf41 --- /dev/null +++ b/man/man3/venti-file.3 @@ -0,0 +1,324 @@ +.TH VENTI-FILE 3 +.SH NAME +VtFile, +vtfileopenroot, +vtfilecreateroot, +vtfileopen, +vtfilecreate, +vtfileblock, +vtfileread, +vtfilewrite, +vtfileflush, +vtfileincref, +vtfileclose, +vtfilegetentry, +vtfilesetentry, +vtfileblockscore, +vtfilegetdirsize, +vtfilesetdirsize, +vtfileunlock, +vtfilelock, +vtfilelock2, +vtfileflushbefore, +vtfiletruncate, +vtfilegetsize, +vtfilesetsize, +vtfileremove \- Venti files +.SH SYNOPSIS +.ta +\w'\fLVtBlock* 'u +.PP +.B +VtFile* vtfilecreateroot(VtCache *c, int psize, int dsize, int type); +.PP +.B +VtFile* vtfileopenroot(VtCache *c, VtEntry *e); +.PP +.B +VtFile* vtfileopen(VtFile *f, u32int n, int mode); +.PP +.B +VtFile* vtfilecreate(VtFile *f, int psize, int dsize, int dir); +.PP +.B +void vtfileincref(VtFile *f); +.PP +.B +void vtfileclose(VtFile *f); +.PP +.B +int vtfileremove(VtFile *f); +.PP +.B +VtBlock* vtfileblock(VtFile *f, u32int n, int mode); +.PP +.B +long vtfileread(VtFile *f, void *buf, long n, vlong offset); +.PP +.B +long vtfilewrite(VtFile *f, void *buf, long n, vlong offset); +.PP +.B +int vtfileflush(VtFile *f); +.PP +.B +int vtfileflushbefore(VtFile *f, vlong offset); +.PP +.B +int vtfiletruncate(VtFile *f); +.PP +.B +uvlong vtfilegetsize(VtFile *f); +.PP +.B +int vtfilesetsize(VtFile *f, vlong size); +.PP +.B +u32int vtfilegetdirsize(VtFile *f); +.PP +.B +int vtfilesetdirsize(VtFile *f, u32int size); +.PP +.B +int vtfilegetentry(VtFile *f, VtEntry *e); +.PP +.B +int vtfilesetentry(VtFile *f, VtEntry *e); +.PP +.B +int vtfileblockscore(VtFile *f, u32int n, uchar score[VtScoreSize]); +.PP +.B +int vtfilelock(VtFile *f, int mode); +.PP +.B +int vtfilelock2(VtFile *f, VtFile *f, int mode); +.PP +.B +void vtfileunlock(VtFile *f); +.SH DESCRIPTION +These routines provide a simple interface to create and +manipulate Venti file trees (see +.IR venti (1)). +.PP +.I Vtfilecreateroot +creates a new Venti file. +.I Btype +must be either +.B VtDataType +or +.BR VtDirType , +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. +.PP +.I Vtfileopenroot +opens an existing Venti file described by +.IR e . +.PP +.I Vtfileopen +opens the Venti file described by the +.IR n th +entry in the directory +.IR f . +.I Mode +should be one of +.IR VtOREAD , +.IR VtOWRITE , +or +.IR VtORDWR , +indicating how the returned file is to be used. +The +.IR VtOWRITE +and +.IR VtORDWR +modes can only be used if +.IR f +is open with mode +.IR VtORDWR . +.PP +.I Vtfilecreate +creates a new file in the directory +.I f +with block type +.I type +and block sizes +.I dsize +and +.I psize +(see +.I vtfilecreateroot +above). +.PP +Each file has an associated reference count +and holds a reference to its parent in the file tree. +.I Vtfileincref +increments this reference count. +.I Vtfileclose +decrements the reference count. +If there are no other references, +.I vtfileclose +releases the reference to +.IR f 's +parent and then frees the in-memory structure +.IR f . +The data stored in +.I f +is still accessible by reopening it. +.PP +.I Vtfileremove +removes the file +.I f +from its parent directory. +It also acts as +.IR vtfileclose , +releasing the reference to +.I f +and potentially freeing the structure. +.PP +.I Vtfileblock +returns the +.IR n th +block in the file +.IR f . +If there are not +.I n +blocks in the file and +.I mode +is +.BR VtOREAD , +.I vtfileblock +returns nil. +If the mode is +.B VtOWRITE +or +.BR VtORDWR , +.I vtfileblock +grows the file as needed and then returns the block. +.PP +.I Vtfileread +reads at most +.I n +bytes at offset +.I offset +from +.I f +into memory at +.IR buf . +It returns the number of bytes read. +.PP +.I Vtfilewrite +writes the +.I n +bytes in memory at +.I buf +into the file +.I f +at offset +.IR n . +It returns the number of bytes written, +or \-1 on error. +Writing fewer bytes than requested will only happen +if an error is encountered. +.PP +.I Vtfilewrite +writes to an in-memory copy of the data blocks +(see +.IR venti-cache (3)) +instead of writing directly to Venti. +.I Vtfileflush +writes all copied blocks associated with +.I f +to the Venti server. +.I Vtfileflushbefore +flushes only those blocks corresponding to data in the file before +byte +.IR offset . +Loops that +.I vtfilewrite +should call +.I vtfileflushbefore +regularly to avoid filling the block cache with dirty blocks. +.PP +.I Vtfiletruncate +changes the file +.I f +to have zero length. +.PP +.I Vtfilegetsize +returns the length (in bytes) of file +.IR f . +.PP +.I Vtfilesetsize +sets the length (in bytes) of file +.IR f . +.PP +.I Vtfilegetdirsize +returns the length (in directory entries) +of the directory +.IR f . +.PP +.I Vtfilesetdirsize +sets the length (in directory entries) +of the directory +.IR f . +.PP +.I Vtfilegetentry +fills +.I e +with an entry that can be passed to +.IR vtfileopenroot +to reopen +.I f +at a later time. +.PP +.I Vtfilesetentry +sets the entry associated with +.I f +to be +.IR e . +.PP +.I Vtfileblockscore +returns in +.I score +the score of the +.I n th +block in the file +.IR f . +.PP +Venti files are locked and unlocked +via +.I vtfilelock +and +.I vtfileunlock +to moderate concurrent access. +Only one thread at a time\(emthe one that has the file locked\(emcan +read or modify the file. +The functions that return files +.RI ( vtfilecreateroot , +.IR vtfileopenroot , +.IR vtfilecreate , +and +.IR vtfileopen ) +return them unlocked. +When files are passed to any of the functions documented in +this manual page, it is the caller's responsibility to ensure that +they are already locked. +.PP +Internally, a file is locked by locking the +block that contains its directory entry. +When two files in the same +directory both need to be locked, +.I vtfilelock2 +must be used. +It locks both its arguments, taking special care +not to deadlock if their entries are stored +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) diff --git a/man/man3/venti-log.3 b/man/man3/venti-log.3 new file mode 100644 index 00000000..bc4efe76 --- /dev/null +++ b/man/man3/venti-log.3 @@ -0,0 +1,133 @@ +.TH VENTI-LOG 3 +.SH NAME +VtLog, +VtLogChunk, +vtlog, +vtlogclose, +vtlogdump, +vtlognames, +vtlogopen, +vtlogprint, +vtlogremove, +vtlogopen, +ventilogging \- Venti logs +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLVtLog* 'u +.PP +.B +VtLog* vtlogopen(char *name, uint size); +.PP +.B +void vtlogprint(VtLog *log, char *fmt, ...); +.PP +.B +void vtlogclose(VtLog *log); +.PP +.B +void vtlog(char *name, char *fmt, ...); +.PP +.B +void vtlogremove(char *name); +.PP +.B +char** vtlognames(int *n); +.PP +.B +void vtlogdump(int fd, VtLog *log); +.PP +.B +extern int ventilogging; /* default 0 */ +.PP +.B +extern char *VtServerLog; /* "libventi/server" */ +.SH DESCRIPTION +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. +.PP +.I Vtlogopen +returns a reference to the log named +.I name . +If a log with that name does not exist and +.I size +is non-zero, a new log capable of holding at +least +.I size +bytes is allocated and returned. +.I Vtlogclose +releases the reference returned by +.IR vtlogopen . +.PP +.I Vtlogprint +writes to +.IR log , +which must be open. +.PP +.I Vtlog +is a convenient packaging of +.I vtlogopen +followed by +.I vtlogprint +and +.IR vtlogclose . +.PP +.I Vtlogremove +removes the log with the given +.IR name , +freeing any associated storage. +.PP +.I Vtlognames +returns a list of the names of all the logs. +The length of the list is returned in +.BI * n \fR. +The list +should be freed +by calling +.I vtfree +on the returned pointer. +The strings in the list will be freed by this call as well. +(It is an error to call +.I vtfree +on any of the strings in the list.) +.PP +.I Vtlogdump +prints +.IR log , +which must be open, to the file descriptor +.IR fd . +.PP +If +.I ventilogging +is set to zero (the default), +.I vtlognames +and +.I vtlogdump +can inspect existing logs, but +.I vtlogopen +always returns nil +and +.I vtlog +is a no-op. +The other functions are no-ops when +passed nil log structures. +.PP +The server library +(see +.IR venti-conn (3) +and +.IR venti-server (3)) +writes debugging information to the log named +.IR VtServerLog , +which defaults to the string +.LR libventi/server . +.SH SOURCE +.B \*9/src/libventi +.SH SEE ALSO +.IR venti (3) diff --git a/man/man3/venti-mem.3 b/man/man3/venti-mem.3 new file mode 100644 index 00000000..46b2bb31 --- /dev/null +++ b/man/man3/venti-mem.3 @@ -0,0 +1,67 @@ +.TH VENTI-MEM 3 +.SH NAME +vtbrk, +vtmalloc, +vtmallocz, +vtrealloc, +vtstrdup, +vtfree \- error-checking memory allocators +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLvoid* 'u +.PP +.B +void* vtbrk(int size) +.PP +.B +void* vtmalloc(int size) +.PP +.B +void* vtmallocz(int size) +.PP +.B +void* vtrealloc(void *ptr, int size) +.PP +.B +char* vtstrdup(char *s) +.PP +.B +void vtfree(void *ptr) +.SH DESCRIPTION +These routines allocate and free memory. +On failure, they print an error message and call +.IR sysfatal (3). +They do not return. +.PP +.I Vtbrk +returns a pointer to a new block of at least +.I size +bytes. +The block cannot be freed. +.PP +.IR Vtmalloc , +.IR vtrealloc , +and +.I vtstrdup +are like +.IR malloc , +.IR realloc , +and +.IR strdup , +but, as noted above, do not return on error. +.I Vtmallocz +is like +.I vtmalloc +but zeros the block before returning it. +Memory allocated with all four should be freed with +.I vtfree +when no longer needed. +.SH SOURCE +.B \*9/src/libventi +.SH SEE ALSO +.IR venti (3) diff --git a/man/man3/venti-packet.3 b/man/man3/venti-packet.3 new file mode 100644 index 00000000..7d5a518f --- /dev/null +++ b/man/man3/venti-packet.3 @@ -0,0 +1,266 @@ +.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 +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLPacket* 'u +\w'\fLxxxx'u +.PP +.B +.PP +.B +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) +.PP +.B +void packetsha1(Packet *p, uchar sha1[20]) +.SH DESCRIPTION +A +.B Packet +is a list of blocks of data. +Each block is contiguous in memory, but the entire packet +may not be. +This representation helps avoid unnecessary memory copies. +.PP +.I Packetalloc +allocates an empty packet. +.PP +.I Packetappend +appends the +.I n +bytes at +.I buf +to the end of +.IR p . +.PP +.I Packetasize +returns the number of data bytes allocated to +.IR p . +This may be larger than the number of bytes stored +in +.IR p +because individual fragments may not be filled. +.PP +.I Packetcmp +compares the data sections of two packets as +.I memcmp +(see +.IR memory (3)) +would. +.PP +.I Packetconcat +removes all data from +.IR q , +appending it to +.IR p . +.PP +.I Packetconsume +removes +.I n +bytes from the beginning of +.IR p , +storing them into +.IR buf . +.PP +.I Packetcopy +copies +.I n +bytes at +.I offset +in +.I p +to +.IR buf . +.PP +.I Packetdup +creates a new packet initialized with +.I n +bytes from +.I offset +in +.IR p . +.PP +.I Packetforeign +allocates a packet containing `foreign' data: the +.I n +bytes pointed to by +.IR buf . +Once the bytes are no longer needed, they are freed by calling +.IB free ( a )\fR. +.PP +.I Packetfragments +initializes up to +.I nio +of the +.I io +structures with pointers to the data in +.IR p , +starting at +.IR offset . +It returns the total number of bytes represented +by the returned structures. +.I Packetfragments +initializes any unused +.I io +structures with nil pointer and zero length. +.PP +.I Packetfree +frees the packet +.IR p . +.PP +.I Packetheader +returns a pointer to the first +.I n +bytes of +.IR p , +making them contiguous in memory +if necessary. +.PP +.I Packetpeek +returns a pointer to the +.I n +bytes at +.I offset +in +.IR p . +If the requested bytes are already stored contiguously in memory, +the returned pointer points at the internal data storage for +.IR p . +Otherwise, the bytes are copied into +.IR buf , +and +.I packetpeek +returns +.IR buf . +.PP +.I Packetprefix +inserts a copy of the +.I n +bytes at +.I buf +at the beginning of +.IR p . +.PP +.I Packetsha1 +computes the SHA1 hash of the data contained in +.IR p . +.PP +.I Packetsize +returns the number of bytes of data contained in +.IR p . +.PP +.I Packetsplit +returns a new packet initialized with +.I n +bytes removed from the beginning of +.IR p . +.PP +.I Packetstats +prints run-time statistics to standard output. +.PP +.I Packettrailer +returns a pointer to the last +.I n +bytes of +.IR p , +making them contiguous in memory +if necessary. +.PP +.I Packettrim +removes +.I n +bytes at offset +.I offset +from packet +.IR p . +.SH SOURCE +.B \*9/src/libventi +.SH SEE ALSO +.IR venti (3) +.SH DIAGNOSTICS +These functions return errors only when passed +invalid inputs, +.IR e.g. , +requests for data at negative offsets or beyond the end of a packet. +.PP +Functions returning pointers return nil on error; +functions returning integers return \-1 on error. +Most functions returning integers return 0 on success. +The exceptions are +.I packetfragments +and +.IR packetcmp , +whose return values are described above. +.PP +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 new file mode 100644 index 00000000..9dd6f347 --- /dev/null +++ b/man/man3/venti-server.3 @@ -0,0 +1,121 @@ +.TH VENTI-SERVER 3 +.SH NAME +vtsrvhello, vtlisten, vtgetreq, vtrespond \- Venti server +.SH SYNOPSIS +.PP +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLVtReq* 'u +.PP +.ft L +.nf +typedef struct VtReq +{ + VtFcall tx; + VtFcall rx; + ... +} VtReq; +.PP +.B +int vtsrvhello(VtConn *z) +.PP +.B +VtSrv* vtlisten(char *addr) +.PP +.B +VtReq* vtgetreq(VtSrv *srv) +.PP +.B +void vtrespond(VtReq *req) +.SH DESCRIPTION +These routines execute the server side of the +.IR venti (7) +protocol. +.PP +.I Vtsrvhello +executes the server side of the initial +.B hello +transaction. +It sets +.IB z -> uid +with the user name claimed by the other side. +Each new connection must be initialized by running +.I vtversion +and then +.IR vtsrvhello . +The framework below takes care of this detail automatically; +.I vtsrvhello +is provided for programs that do not use the functions below. +.PP +.IR Vtlisten , +.IR vtgetreq , +and +.I vtrespond +provide a simple framework for writing Venti servers. +.PP +.I Vtlisten +announces at the network address +.IR addr , +returning a fresh +.B VtSrv +structure representing the service. +.PP +.I Vtgetreq +waits for and returns +the next +.BR read , +.BR write , +.BR sync , +or +.B ping +request from any client connected to +the service +.IR srv . +.B Hello +and +.B goodbye +messages are handled internally and not returned to the client. +The interface does not distinguish between the +different clients that may be connected at any given time. +The request can be found in the +.I tx +field of the returned +.BR VtReq . +.PP +Once a request has been served and a response stored in +.IB r ->rx \fR, +the server should call +.IR vtrespond +to send the response to the client. +.I Vtrespond +frees the structure +.I r +as well as the packets +.IB r ->tx.data +and +.IB r ->rx.data \fR. +.SH EXAMPLE +.B \*9/src/venti/cmd +contains two simple Venti servers +.B ro.c +and +.B devnull.c +written using these routines. +.I Ro +is a read-only Venti proxy (it rejects +.B write +requests). +.I Devnull +is a 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) diff --git a/man/man3/venti-zero.3 b/man/man3/venti-zero.3 new file mode 100644 index 00000000..c163b888 --- /dev/null +++ b/man/man3/venti-zero.3 @@ -0,0 +1,56 @@ +.TH VENTI-ZERO 3 +.SH NAME +vtzerotruncate, vtzeroextend, vtzeroscore \- Venti block truncation +.SH SYNOPSIS +.ft L +#include +.br +#include +.br +#include +.ta +\w'\fLuint 'u +.PP +.B +uint vtzerotruncate(int type, uchar *buf, uint size) +.PP +.B +void vtzeroextend(int type, uchar *buf, uint size, uint newsize) +.PP +.B +extern uchar vtzeroscore[VtScoreSize]; +.SH DESCRIPTION +These utility functions compute how to truncate or replace +trailing zeros (for data blocks) or trailing zero scores +(for pointer blocks) to canonicalize the blocks before +storing them to Venti. +.PP +.I Vtzerotruncate +returns the size of the +.IR size -byte +buffer pointed to by +.I buf +ignoring trailing zeros or zero scores, +according to the block type +.IR type . +.PP +.I Vtzeroextend +pads +.I buf +with zeros or zero scores, +according to the block type +.IR type , +to grow it from +.I size +bytes to +.I newsize +bytes. +.PP +.I Vtzeroscore +is the score of the zero-length block. +.SH SOURCE +.B \*9/src/libventi/zero.c +.br +.B \*9/src/libventi/zeroscore.c +.SH SEE ALSO +.IR venti (1), +.IR venti (3) diff --git a/man/man3/venti.3 b/man/man3/venti.3 new file mode 100644 index 00000000..a2581e98 --- /dev/null +++ b/man/man3/venti.3 @@ -0,0 +1,75 @@ +.TH VENTI 3 +.SH NAME +xxx \- Venti storage server +.SH SYNOPSIS +.PP +.ft L +#include +.br +#include +.br +#include +.SH DESCRIPTION +The Venti library provides support for writing Venti servers and clients. +This manual page describes general utility functions. +.PP +Other manual pages describe the library functions in detail. +.PP +.IR Venti-cache (3) +describes a simple in-memory block cache to help clients. +.PP +.IR Venti-conn (3) +describes routines for manipulating network connections +between Venti clients and servers. +.IR Venti-client (3) +and +.IR venti-server (3) +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 +and data structures. +It also describes routines that convert between the C representation +and the network and disk representations. +.PP +.IR Venti-file (3) +describes routines for writing clients that manipulate +Venti file trees +(see +.IR venti (1)). +.PP +.IR Venti-log (3) +describes routines to access in-memory log buffers +as well as the logging that is done automatically by +the library. +.PP +.IR Venti-mem (3) +describes wrappers around the canonical +.IR malloc (3) +routines that abort on error. +.PP +.IR Venti-packet (3) +describes routines for +efficiently manipulating chains of +data buffers. +.PP +.IR Venti-zero (3) +describes routines to zero truncate and zero extend blocks +(see +.IR venti (1)). +.SH SOURCE +.B \*9/src/libventi +.SH SEE ALSO +.IR venti (1), +.IR venti-cache (3), +.IR venti-client (3), +.IR venti-fcall (3), +.IR venti-file (3) +.IR venti-log (3), +.IR venti-mem (3), +.IR venti-packet (3), +.IR venti-server (3), +.IR venti-zero (3), +.IR venti (7), +.IR venti (8) -- cgit v1.2.3