tdone - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
(DIR) commit 3aec33fee92d97715e648bd8205823ddc7e5cbba
(DIR) parent 9f95eb6fd6e5fa8a3be78f8b1b85310f50e49380
(HTM) Author: rsc <devnull@localhost>
Date: Mon, 18 Jul 2005 22:41:58 +0000
done
Diffstat:
M man/man1/0intro.1 | 1 +
M man/man1/hist.1 | 7 ++++++-
D man/man1/vbackup.1 | 263 -------------------------------
M man/man1/venti.1 | 14 +++++++-------
M man/man1/yesterday.1 | 11 +++++------
M man/man3/venti-cache.3 | 68 ++++++++++++++++++++++++++-----
M man/man3/venti-client.3 | 24 ++++++++++--------------
M man/man3/venti-conn.3 | 16 ++++++++++++++--
M man/man3/venti-fcall.3 | 28 +++++++++++++++-------------
M man/man3/venti-file.3 | 63 ++++++++++++++++---------------
M man/man3/venti-log.3 | 15 +++++++++------
M man/man3/venti-mem.3 | 3 +--
M man/man3/venti-packet.3 | 81 ++++++++++++++++++-------------
M man/man3/venti-server.3 | 8 +++++---
M man/man3/venti-zero.3 | 8 ++++----
M man/man3/venti.3 | 10 +++++-----
A man/man7/mpictures.7 | 151 +++++++++++++++++++++++++++++++
M man/man7/venti.7 | 39 ++++++++++++++++++-------------
M man/man8/vbackup.8 | 244 ++++++++++++++++++++-----------
M man/man8/venti.8 | 71 ++++++++++++++++++++++++-------
20 files changed, 610 insertions(+), 515 deletions(-)
---
(DIR) diff --git a/man/man1/0intro.1 b/man/man1/0intro.1
t@@ -311,6 +311,7 @@ the
variable in
.IR mk (1),
.IR namespace (1),
+.IR netfiles (1),
.IR page (1),
.IR psfonts (1),
.IR rio (1),
(DIR) diff --git a/man/man1/hist.1 b/man/man1/hist.1
t@@ -65,11 +65,16 @@ Examine changes in block.c:
hist -d block.c
.EE
.SH FILES
+.TF /dump
+.TP
.B /dump
+by convention, root of dump file system
+.PD
.SH SOURCE
.B /home/am3/rsc/src/backup/cmd/history.c
.SH SEE ALSO
-.IR yesterday (1)
+.IR yesterday (1),
+.IR vbackup (8)
.SH BUGS
Should be called
.IR history ,
(DIR) diff --git a/man/man1/vbackup.1 b/man/man1/vbackup.1
t@@ -1,263 +0,0 @@
-.TH VBACKUP 8
-.SH NAME
-vbackup, vcat, vftp, vmount, vmount0, vnfs \-
-back up Unix file systems to Venti
-.SH SYNOPSIS
-.B vbackup
-[
-.B -DVnv
-]
-[
-.B -s
-.I secs
-]
-[
-.B -w
-.I n
-]
-.I disk
-[
-.I score
-]
-.PP
-.B vcat
-[
-.B -z
-]
-.I disk
-|
-.I score
-.B >
-.I disk
-.PP
-.B vftp
-.I disk
-|
-.I score
-.PP
-.B vmount
-[
-.B -v
-]
-.I addr
-.I mtpt
-.PP
-.B vmount0
-[
-.B -v
-]
-[
-.B -h
-.I handle
-]
-.I addr
-.I mtpt
-.PP
-.B vnfs
-[
-.B -LLMRVr
-]
-[
-.B -a
-.I addr
-]
-[
-.B -m
-.I mntaddr
-]
-[
-.B -b
-.I blocksize
-]
-[
-.B -c
-.I cachesize
-]
-.I config
-.SH DESCRIPTION
-These programs back up and restore standard
-Unix file system images stored in
-.IR venti (8).
-Images stored in
-.I venti
-are named by
-.IR scores ,
-which consist of a file system type followed
-by a colon and forty hexadecimal digits, as in:
-.IP
-.EX
-ffs:0123456789abcdef0123456789abcdef01234567
-.EE
-.PP
-(The hexadecimal data is the SHA1 hash of the Venti
-root block representing the file system image.)
-.PP
-These programs expect the environment variable
-.B $venti
-to be set to the network address of the Venti server to use
-(for example,
-.B yourhost
-or
-.BR tcp!yourhost!venti ).
-.PP
-.I Vbackup
-copies the file system stored on
-.I disk
-to the Venti server and prints the
-score for the newly-stored image.
-The argument
-.I disk
-should be a disk or disk partition device
-that would be appropriate to pass to
-.IR mount (8).
-.PP
-The optional argument
-.I score
-is the score of a previous backup of the disk image.
-If
-.I score
-is given,
-.I vbackup
-will not write to Venti any blocks that have not changed
-since the previous backup.
-This is only a speed optimization: since the blocks are already
-stored on Venti they need not be sent to the Venti server again.
-.PP
-The options to
-.I vbackup
-are:
-.TP
-.B -D
-.TP
-.B -V
-.TP
-.B -n
-.TP
-.B -v
-.TP
-.B -w \fIn
-.TP
-.B -s \fIsecs
-.PP
-.I Vcat
-writes the named disk image to standard output.
-Unused file system blocks are printed zeroed regardless
-of their actual content.
-.PP
-If the
-.B -z
-flag is given,
-.I vcat
-will attempt to seek over unused blocks instead of writing to them.
-The
-.B -z
-flag should only be used when standard output is seekable
-.RI ( i.e. ,
-when it has been redirected to a file or disk).
-.PP
-.I Vftp
-presents the
-file system image named by
-.I disk
-or
-.I score
-in a shell-like
-interactive session.
-Type
-.B help
-at the
-.B vftp>
-prompt for details.
-.PP
-.I Vmount
-mounts the NFS service at the network connection
-.I address
-onto
-.IR mountpoint .
-On most operating systems,
-.I vmount
-must be run by the user
-.BR root .
-.PP
-.I Vmount0
-is a simple C program that
-.I vmount
-uses if
-.IR mount (8)
-does not suffice.
-.PP
-.I Vnfs
-serves, using the
-NFS version 3 protocol,
-one or more disk images in a synthetic tree defined
-by the configuration file
-.IR config .
-.I Vnfs
-announces NFS service at
-.IR addr
-(default
-.BR udp!*!nfs )
-and NFS mount service at
-.IR mntaddr
-(default
-.BR udp!*!\fI999 ),
-registering both with the port mapper.
-If no port mapper is found running (on port 111),
-.I vnfs
-starts its own port mapper.
-The options are:
-.TP
-.B -r
-Reply to all NFS requests with RPC rejections.
-.TP
-.B -M
-Do not announce an NFS mount service.
-.TP
-.B -P
-Do not register service with the port mapper.
-.TP
-.B -a
-
-
-.SH EXAMPLES
-.PP
-Back up the file system stored on
-.BR /dev/da0s1a :
-.IP
-.EX
-% vbackup /dev/da0s1a
-ffs:0123456789abcdef0123456789abcdef01234567
-%
-.EE
-.PP
-Serve that backup and a few others in a tree reminiscent
-of Plan 9's dump file system, but hide each day's contents of
-.B /tmp :
-.IP
-.EX
-% cat config
-mount /2005/0510 ffs:0123456789abcdef\fI...\fP
-mount /2005/0510/home ffs:0123456789abcdef\fI...\fP
-mount /2005/0510 ffs:0123456789abcdef\fI...\fP
-mount /2005/0510/home ffs:0123456789abcdef\fI...\fP
-hide /*/*/tmp
-% vnfs -m -b 16k -c 1k config
-%
-.EE
-.PP
-Mount the backups on a client machine using
-.IR vmount :
-.IP
-.EX
-# vmount udp!yourserver!nfs /dump
-# ls /dump
-2005
-#
-.EE
-.PP
-Mount the backups using the standard NFS mount program:
-.IP
-.EX
-# mount -t nfs -o soft,intr,ro,nfsv3,rsize=8192,timeo=100 \
- -o nfsvers=3,nolock,noatime,nodev,nosuid \
-.EE
(DIR) diff --git a/man/man1/venti.1 b/man/man1/venti.1
t@@ -85,7 +85,7 @@ If the
.B -z
option is given,
.I write
-truncates the block before writing it to the server.
+zero truncates the block before writing it to the server.
.PP
.I Copy
expects
t@@ -114,14 +114,15 @@ and
.B -r
option control
.IR copy 's
-behavior upon encountering errors while reading
-from srchost.
+reaction to errors reading
+from
+.IR srchost .
.I Copy
always prints information to standard error
about each read error.
By default,
.I copy
-immediately exits after printing the first error.
+exits after printing the first error.
If the
.B -i
option is given, read errors are ignored.
t@@ -138,12 +139,11 @@ It writes the new root score to standard output.
.B \*9/src/cmd/venti/cmd
.SH SEE ALSO
.IR vac (1),
-.IR vbackup (1),
.IR venti (3),
.IR vacfs (4),
-.IR vnfs (4),
.IR venti (7),
+.IR vbackup (8),
.IR venti (8)
.SH BUGS
There should be programs to read and write
-streams and directories.
+venti files and directories.
(DIR) diff --git a/man/man1/yesterday.1 b/man/man1/yesterday.1
t@@ -84,16 +84,15 @@ Restore your profile from yesterday:
yesterday -c ~/.profile
.EE
.SH FILES
+.TF /dump
.B /dump
+by convention, root of the dump file system
+.PD
.SH SOURCE
.B /usr/local/bin/yesterday
.SH SEE ALSO
.IR diff (1),
-.IR hist (1)
+.IR hist (1),
+.IR vbackup (8)
.SH BUGS
-Backups are only available on
-.B amsterdam
-and
-.BR toil .
-.PP
It's hard to use this command without singing.
(DIR) diff --git a/man/man3/venti-cache.3 b/man/man3/venti-cache.3
t@@ -24,6 +24,8 @@ vtlocaltoglobal \- Venti block cache
#include <venti.h>
.ta +\w'\fLxxxx 'u
.PP
+.ft L
+.nf
typedef struct VtBlock
{
uchar *data;
t@@ -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])
t@@ -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);
t@@ -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
t@@ -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
t@@ -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 ,
t@@ -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)
(DIR) diff --git a/man/man3/venti-client.3 b/man/man3/venti-client.3
t@@ -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)
t@@ -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)
t@@ -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
t@@ -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
t@@ -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 .
t@@ -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),
t@@ -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.
(DIR) diff --git a/man/man3/venti-conn.3 b/man/man3/venti-conn.3
t@@ -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
t@@ -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
t@@ -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
(DIR) diff --git a/man/man3/venti-fcall.3 b/man/man3/venti-fcall.3
t@@ -14,7 +14,7 @@ vtputstring,
vtrootpack,
vtrootunpack,
vtparsescore,
-vtscorefmt \- Venti external data representation
+vtscorefmt \- venti data formats
.SH SYNOPSIS
.PP
.ft L
t@@ -31,7 +31,6 @@ enum
{
VtEntrySize = 40,
VtRootSize = 300,
- VtRootVersion = 2,
VtScoreSize = 20,
};
.PP
t@@ -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;
t@@ -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
t@@ -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
t@@ -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
t@@ -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
t@@ -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
(DIR) diff --git a/man/man3/venti-file.3 b/man/man3/venti-file.3
t@@ -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
t@@ -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);
t@@ -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
t@@ -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
t@@ -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
t@@ -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
t@@ -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
t@@ -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)
(DIR) diff --git a/man/man3/venti-log.3 b/man/man3/venti-log.3
t@@ -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 .
t@@ -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)
(DIR) diff --git a/man/man3/venti-mem.3 b/man/man3/venti-mem.3
t@@ -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 ,
(DIR) diff --git a/man/man3/venti-packet.3 b/man/man3/venti-packet.3
t@@ -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>
t@@ -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
t@@ -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
t@@ -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
t@@ -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.
(DIR) diff --git a/man/man3/venti-server.3 b/man/man3/venti-server.3
t@@ -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
(DIR) diff --git a/man/man3/venti-zero.3 b/man/man3/venti-zero.3
t@@ -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
t@@ -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)
(DIR) diff --git a/man/man3/venti.3 b/man/man3/venti.3
t@@ -1,6 +1,6 @@
.TH VENTI 3
.SH NAME
-xxx \- Venti storage server
+venti \- archival storage server
.SH SYNOPSIS
.PP
.ft L
t@@ -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.
t@@ -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
t@@ -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
(DIR) diff --git a/man/man7/mpictures.7 b/man/man7/mpictures.7
t@@ -0,0 +1,151 @@
+.TH MPICTURES 7
+.SH NAME
+mpictures \- picture inclusion macros
+.SH SYNOPSIS
+.B troff -mpictures
+[
+.I options
+]
+.I file ...
+.SH DESCRIPTION
+.I Mpictures
+macros insert PostScript pictures into
+.IR troff (1)
+documents.
+The macros are:
+.TP
+.BI .BP " source height width position offset flags label
+Define a frame and place a picture in it.
+Null arguments, represented by \f5""\fR,
+are interpreted as defaults.
+The arguments are:
+.RS
+.TP
+.I source
+Name of a PostScript picture file, optionally
+suffixed with
+.RI ( n )
+to select page number
+.I n
+from the file (first page by default).
+.PD0
+.TP
+.I height
+Vertical size of the frame, default
+.BR 3.0i .
+.TP
+.I width
+Horizontal size of the frame, current line length by default.
+.TP
+.I position
+.L l
+(default),
+.LR c ,
+or
+.L r
+to left-justify, center, or right-justify the frame.
+.TP
+.I offset
+Move the frame horizontally from the original
+.I position
+by this amount, default
+.BR 0i .
+.TP
+.I flags
+One or more of:
+.RS
+.PD 0v
+.TP
+.BI a d
+Rotate the picture clockwise
+.I d
+degrees, default
+.IR d =90.
+.TP
+.B o
+Outline the picture with a box.
+.TP
+.B s
+Freely scale both picture dimensions.
+.TP
+.B w
+White out the area to be occupied by the picture.
+.TP
+.BR l , r , t ,\fPb
+Attach the picture to the left right, top, or bottom of the frame.
+.RE
+.TP
+.I label
+Place
+.I label
+at distance
+.B 1.5v
+below the frame.
+.PD
+.PP
+If there's room,
+.B .BP
+fills text around the frame.
+Everything destined for either side of the frame
+goes into a diversion to be retrieved when the accumulated
+text sweeps past the trap set by
+.B .BP
+or when the diversion is explicitly closed
+by
+.BR .EP .
+.RE
+.TP
+.BI .PI " source height" , width , "yoffset\fB,\fPxoffset flags.
+This low-level macro, used by
+.BR .BP ,
+can help do more complex things.
+The two arguments not already described are:
+.RS
+.TP
+.I xoffset
+Offset the frame from the left margin by this amount, default
+.BR 0i .
+.PD0
+.TP
+.I yoffset
+Offset the frame from the current baseline,
+measuring positive downward, default
+.BR 0i .
+.PD
+.RE
+.TP
+.B .EP
+End a picture started by
+.BR .BP ;
+.B .EP
+is usually called implicitly by a trap
+at frame bottom.
+.PP
+If a PostScript file lacks page-delimiting comments,
+the entire file is included.
+If no
+.B %%BoundingBox
+comment is present, the picture is
+assumed to fill an 8.5\(mu11-inch page.
+Nothing prevents the picture from being placed off the page.
+.SH SEE ALSO
+.IR troff (1)
+.SH DIAGNOSTICS
+A picture file that can't be read by the PostScript
+postprocessor is replaced by white space.
+.SH BUGS
+A picture and associated text silently disappear if
+a diversion trap set by
+.B .BP
+isn't reached.
+Call
+.B .EP
+at the end of the document to retrieve it.
+.br
+Macros in other packages may break the adjustments
+made to the line length and indent when text is being placed
+around a picture.
+.br
+A missing or improper
+.B %%BoundingBox
+comment may cause the frame to be filled incorrectly.
(DIR) diff --git a/man/man7/venti.7 b/man/man7/venti.7
t@@ -17,19 +17,15 @@ block storage using Venti as well as the Venti network protocol.
.IR Venti (1)
documents some simple clients.
.IR Vac (1),
-.IR vbackup (1),
.IR vacfs (4),
and
-.IR vnfs (4)
+.IR vbackup (8)
are more complex clients.
.PP
.IR Venti (3)
describes a C library interface for accessing
Venti servers and manipulating Venti data structures.
.PP
-.IR Venti.conf (7)
-describes the Venti server configuration file.
-.PP
.IR Venti (8)
describes the programs used to run a Venti server.
.PP
t@@ -86,9 +82,20 @@ Scores passed between programs conventionally refer
to
.B VtRoot
blocks, which contain descriptive information
-as well as the score of a block containing a small number
-of
-.B VtEntries .
+as well as the score of a directory block containing a small number
+of directory entries.
+.PP
+Conventionally, programs do not mix data and directory entries
+in the same file. Instead, they keep two separate files, one with
+directory entries and one with metadata referencing those
+entries by position.
+Keeping this parallel representation is a minor annoyance
+but makes it possible for general programs like
+.I venti/copy
+(see
+.IR venti (1))
+to traverse the block tree without knowing the specific details
+of any particular program's data.
.SS "Block Types
To allow programs to traverse these structures without
needing to understand their higher-level meanings,
t@@ -127,7 +134,7 @@ For example, if a 1024-byte data block contains the
followed by 1013 zero bytes,
a client would store only the 11-byte block.
When the client later read the block from the server,
-it would append zeros to the end as necessary to
+it would append zero bytes to the end as necessary to
reach the expected size.
.PP
When truncating pointer blocks
t@@ -140,12 +147,12 @@ instead of trailing zero bytes.
.PP
Because of the truncation convention,
any file consisting entirely of zero bytes,
-no matter what the length, will be represented by the zero score:
+no matter what its length, will be represented by the zero score:
the data blocks contain all zeros and are thus truncated
to the empty block, and the pointer blocks contain all zero scores
and are thus also truncated to the empty block,
and so on up the hash tree.
-.SS NETWORK PROTOCOL
+.SS Network Protocol
A Venti session begins when a
.I client
connects to the network address served by a Venti
t@@ -163,7 +170,7 @@ The
field is a list of acceptable versions separated by
colons.
The protocol described here is version
-.B 02 .
+.BR 02 .
The client is responsible for choosing a common
version and sending it in the
.B VtThello
t@@ -193,14 +200,14 @@ followed by
bytes of data.
Text strings are represented similarly,
using a two-byte count with
-the text itself stored as a UTF-8 encoded sequence
+the text itself stored as a UTF-encoded sequence
of Unicode characters (see
.IR utf (7)).
Text strings are not
.SM NUL\c
-terminated:
.I n
-counts the bytes of UTF-8 data, which include no final
+counts the bytes of UTF data, which include no final
zero byte.
The
.SM NUL
t@@ -215,7 +222,7 @@ in the enumeration in the include file
.BR <venti.h> .
The next byte is an identifying
.IR tag ,
-used to match responses with requests.
+used to match responses to requests.
The remaining bytes are parameters of different sizes.
In the message descriptions, the number of bytes in a field
is given in brackets after the field name.
t@@ -382,7 +389,7 @@ The
message requests a block with the given
.I score
and
-.I type .
+.IR type .
Use
.I vttodisktype
and
(DIR) diff --git a/man/man8/vbackup.8 b/man/man8/vbackup.8
t@@ -30,11 +30,6 @@ back up Unix file systems to Venti
.B >
.I disk
.PP
-.B vftp
-.I disk
-|
-.I score
-.PP
.B vmount
[
.B -v
t@@ -42,30 +37,15 @@ back up Unix file systems to Venti
.I addr
.I mtpt
.PP
-.B vmount0
-[
-.B -v
-]
-[
-.B -h
-.I handle
-]
-.I addr
-.I mtpt
-.PP
.B vnfs
[
-.B -LLMRVr
+.B -ELLRVr
]
[
.B -a
.I addr
]
[
-.B -m
-.I mntaddr
-]
-[
.B -b
.I blocksize
]
t@@ -128,46 +108,68 @@ The options to
are:
.TP
.B -D
+Turn on debugging output.
.TP
.B -V
+Trace interactions with Venti server.
+.TP
+.B -m \fImntname
+Set backup name
+(defaults to
+.IR sysname (3)):
+this name is used in the printed
+.B mount
+command.
.TP
.B -n
+No-op mode: do not write any blocks to the server
.TP
.B -v
+Print verbose output.
.TP
.B -w \fIn
+Write parallelism: keep
+.I n
+writes to the server in progress at a time.
.TP
.B -s \fIsecs
+Status interval: every
+.I secs
+seconds, print a line tracking progress of the backup.
+.PD
+.PP
+When
+.I vbackup
+finishes, it prints a single line of the form
+.IP
+.EX
+mount /\fImntname\fL/\fIyyyy\fL/\fImmdd\fL/\fImntpath\fL \fIscore\fL \fIyyyy\fL/\fImmdd\fL/\fIhhmm
+.EE
+.LP
+This line is a valid configuration line for
+.I vnfs
+.RI ( q.v. ).
+.I Mntpath
+is the path on which
+.I disk
+is currently mounted.
.PP
.I Vcat
writes the named disk image to standard output.
Unused file system blocks are printed zeroed regardless
of their actual content.
.PP
-If the
-.B -z
-flag is given,
+By default,
.I vcat
-will attempt to seek over unused blocks instead of writing to them.
+will assume that its standard output is seekable
+.RI ( i.e.,
+it has been redirected to a file or disk)
+and seek over unused blocks instead of writing to them.
The
.B -z
-flag should only be used when standard output is seekable
-.RI ( i.e. ,
-when it has been redirected to a file or disk).
-.PP
-.I Vftp
-presents the
-file system image named by
-.I disk
-or
-.I score
-in a shell-like
-interactive session.
-Type
-.B help
-at the
-.B vftp>
-prompt for details.
+option causes
+.I vcat
+to zero unused blocks instead.
.PP
.I Vmount
mounts the NFS service at the network connection
t@@ -179,13 +181,6 @@ On most operating systems,
must be run by the user
.BR root .
.PP
-.I Vmount0
-is a simple C program that
-.I vmount
-uses if
-.IR mount (8)
-does not suffice.
-.PP
.I Vnfs
serves, using the
NFS version 3 protocol,
t@@ -193,40 +188,123 @@ one or more disk images in a synthetic tree defined
by the configuration file
.IR config .
.I Vnfs
-announces NFS service at
+serves both NFS mount protocol
+and NFS protocol
+RPCs at
.IR addr
(default
-.BR udp!*!nfs )
-and NFS mount service at
-.IR mntaddr
-(default
-.BR udp!*!\fI999 ),
-registering both with the port mapper.
-If no port mapper is found running (on port 111),
-.I vnfs
-starts its own port mapper.
+.BR udp!*!nfs ).
The options are:
.TP
+.B -E
+Disable `encrypted' handles.
+By default handles are encrypted with a random key to avoid
+leaking information about the backed-up file systems.
+If encryption is disabled, the NFS handles exposed to the client
+may leak information about the root scores of the disks as well
+as inode numbers.
+.TP
+.B -L
+Local service only: serve only requests from the loopback interface (127.0.0.1).
+.TP
+.B -LL
+Local service only, with paranoia: serve only requests from loopback,
+and only from the first source port that sends a request.
+This option is intended to be used to make sure that once the local
+host has mounted the service, no other local users can access it.
+.TP
+.B -R
+Print all NFS and NFS mount RPCs to standard error.
+.TP
+.B -V
+Print all Venti transactions to standard error.
+.TP
+.BI -a " addr
+Serve requests on
+.IR addr
+(see above).
+.TP
+.BI -b " blocksize
+Set block size used by the in-memory venti block cache.
+Must be as large as the maximum block size in any
+file system mentioned in the configuration.
+.TP
+.BI -c " cachesize
+Set the number of blocks stored by the in-memory venti cache.
+.TP
.B -r
-Reply to all NFS requests with RPC rejections.
+Respond to all requests with a Sun RPC rejection.
+This is useful during debugging.
+.PD
+.PP
+.I Config
+is a text file describing the
+backup hierarchy for
+.I vnfs
+to serve.
+Lines beginning with a sharp
+.RB ( # )
+are ignored.
+The rest of the file is a sequence of commands, one per line.
+The commands are:
.TP
-.B -M
-Do not announce an NFS mount service.
+.BI mount " mtpt score time
+Add the file system with the given
+.I score
+to the tree at the mount point
+.IR mtpt .
+The path to the mount point will be created
+if necessary.
+If
+.B /dev/null
+is given as the score, an empty file system is mounted at
+.IR mtpt ,
+excluding
+.IR mtpt 's
+contents from view.
+.I Time
+is the modification time to return for the directory
+.IR mtpt ,
+either a decimal number of seconds since the epoch
+or a string of the form
+.IB yyyy / mmdd / hhmm
+giving the year, month, day, hour, and minute.
+.RI ( Vnfs
+does not use the modification time of the root in order
+to avoid accessing every mounted file system on common
+actions like
+.B ls
+.B -l
+.BR /dump/sys/2005 .)
.TP
-.B -P
-Do not register service with the port mapper.
+.BI allow " ip\fR[\fL/\fImask\fR]
.TP
-.B -a
-
-
+.BI deny " ip\fR[\fL/\fImask\fR]
+These two commands define access permissions based on IP address.
+The optional
+.I mask
+can be a decimal number (24) or an equivalent IP mask (255.255.255.0).
+Each request is filtered through the rules listed in the configuration file.
+The first rule that matches is used.
+If any
+.B allow
+or
+.B deny
+rules are given, the default action is to reject the request.
+In the absence of any rules, the default action is to accept all requests.
+.PD
.SH EXAMPLES
.PP
-Back up the file system stored on
-.BR /dev/da0s1a :
+Running on the server
+.IR bob ,
+back up the file system stored on
+.BR /dev/da0s1a ,
+which is mounted on
+.BR /home :
.IP
.EX
% vbackup /dev/da0s1a
-ffs:0123456789abcdef0123456789abcdef01234567
+mount /bob/2005/0510/home ffs:0123456789abcdef\fI...\fP 2005/0510/0831
%
.EE
.PP
t@@ -236,12 +314,13 @@ of Plan 9's dump file system, but hide each day's contents of
.IP
.EX
% cat config
-mount /2005/0510 ffs:0123456789abcdef\fI...\fP
-mount /2005/0510/home ffs:0123456789abcdef\fI...\fP
-mount /2005/0510 ffs:0123456789abcdef\fI...\fP
-mount /2005/0510/home ffs:0123456789abcdef\fI...\fP
-hide /*/*/tmp
-% vnfs -m -b 16k -c 1k config
+mount /bob/2005/0510 ffs:0123456789abcdef\fI...\fP 2005/0510/0829
+mount /bob/2005/0510/home ffs:0123456789abcdef\fI...\fP 2005/0510/0831
+mount /bob/2005/0510/tmp /dev/null 1
+mount /bob/2005/0511 ffs:0123456789abcdef\fI...\fP 2005/0511/0827
+mount /bob/2005/0511/home ffs:0123456789abcdef\fI...\fP 2005/0511/0828
+mount /bob/2005/0511/tmp /dev/null 1
+% vnfs -b 16k -c 1k config
%
.EE
.PP
t@@ -250,14 +329,11 @@ Mount the backups on a client machine using
.IP
.EX
# vmount udp!yourserver!nfs /dump
-# ls /dump
-2005
+# ls /dump/bob/2005
+0510
+0511
#
.EE
.PP
-Mount the backups using the standard NFS mount program:
-.IP
-.EX
-# mount -t nfs -o soft,intr,ro,nfsv3,rsize=8192,timeo=100 \
- -o nfsvers=3,nolock,noatime,nodev,nosuid \
-.EE
+(Users of fancy shells may need to quote the address argument.)
+
(DIR) diff --git a/man/man8/venti.8 b/man/man8/venti.8
t@@ -1,6 +1,41 @@
.TH VENTI 8
.SH NAME
-venti.conf \- venti configuration
+venti \- archival storage server
+.SH SYNOPSIS
+.B venti/venti
+[
+.B -Ldsw
+]
+[
+.B -a
+.I address
+]
+[
+.B -B
+.I blockcachesize
+]
+[
+.B -c
+.I config
+]
+.PP
+.B " "
+[
+.B -C
+.I lumpcachesize
+]
+[
+.B -h
+.I httpaddress
+]
+[
+.B -I
+.I indexcachesize
+]
+[
+.B -W
+.I webroot
+]
.SH DESCRIPTION
Venti is a SHA1-addressed archival storage server.
See
t@@ -83,12 +118,10 @@ and the total bitmap size
.PP
The bloom filter should be sized so that
.I nhash
-\(ti
+\(mu
.I nblock
-\(ti
-0.7
\(<=
-0.7 \(ti
+0.7 \(mu
.IR b ,
where
.I nblock
t@@ -349,22 +382,17 @@ or
(case-insensitive)
to indicate kilobytes, megabytes, or gigabytes respectively.
.SS Command Line
-Options to
-.I venti
-are:
+Many of the options to Venti duplicate parameters that
+can be specified in the configuration file.
+The command line options override those found in a
+configuration file.
+Additional options are:
.TP
.BI -c " config
The server configuration file
(default
.BR venti.conf )
.TP
-.BI -o " line
-Set a server parameter, using the same syntax
-as in the configuration file.
-The
-.B -o
-options override the configuration file.
-.TP
.B -d
Produce various debugging information on standard error.
Implies
t@@ -413,6 +441,8 @@ Start the server and check the storage statistics:
% venti/venti
% hget http://$sysname/storage
.EE
+.SH SOURCE
+.B \*9/src/cmd/venti/srv
.SH "SEE ALSO"
.IR venti (1),
.IR venti (3),
t@@ -429,3 +459,14 @@ Setting up a venti server is too complicated.
.PP
Venti should not require the user to decide how to
partition its memory usage.
+.PP
+Users of shells other than
+.IR rc (1)
+will not be able to use the program names shown.
+One solution is to define
+.B "V=$PLAN9/bin/venti"
+and then substitute
+.B $V/
+for
+.B venti/
+in the paths above.