changelog shortlog tags branches files raw gz bz2 help

Mercurial > hg > ventivac / changeset: welcome vac manual page. perhaps need to add a few more con declarations for Direntry.

changeset 148: 6a1948263a76
parent 147: a81c5fb2810f
child 149: da8fa3932d50
author: Mechiel Lukkien <mechiel@ueber.net>
date: Thu, 30 Aug 2007 19:17:45 +0200
files: man/2/vac
description: welcome vac manual page. perhaps need to add a few more con declarations for Direntry.
     1.1--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2+++ b/man/2/vac	Thu Aug 30 19:17:45 2007 +0200
     1.3@@ -0,0 +1,361 @@
     1.4+.TH VAC 2
     1.5+.SH NAME
     1.6+vac \- read/write venti archives
     1.7+.SH SYNOPSIS
     1.8+.EX
     1.9+include "vac.m";
    1.10+vac := load Vac Vac->PATH;
    1.11+Direntry: import vac;
    1.12+Source, Vacdir, Vacfile: import vac;
    1.13+File, Sink, MSink: import vac;
    1.14+
    1.15+init:		fn();
    1.16+
    1.17+Direntry: adt {
    1.18+	new:	fn(): ref Direntry;
    1.19+	mk:	fn(d: Sys->Dir): ref Direntry;
    1.20+	mkdir:	fn(de: self ref Direntry): ref Sys->Dir;
    1.21+	pack:	fn(de: self ref Direntry): array of byte;
    1.22+	unpack:	fn(d: array of byte): ref Direntry;
    1.23+};
    1.24+
    1.25+Source: adt {
    1.26+	new:	fn(s: ref Venti->Session, e: ref Venti->Entry): ref Source;
    1.27+	get:	fn(s: self ref Source, i: big, d: array of byte): int;
    1.28+	oget:	fn(s: self ref Source, offset: big): array of byte;
    1.29+};
    1.30+
    1.31+Vacfile: adt {
    1.32+	mk:	fn(s: ref Source): ref Vacfile;
    1.33+	new:	fn(session: ref Venti->Session, e: ref Venti->Entry): ref Vacfile;
    1.34+	read:	fn(v: self ref Vacfile, d: array of byte, n: int): int;
    1.35+	seek:	fn(v: self ref Vacfile, offset: big): big;
    1.36+	pread:	fn(v: self ref Vacfile, d: array of byte, n: int, offset: big): int;
    1.37+};
    1.38+
    1.39+Vacdir: adt {
    1.40+	mk:	fn(vf: ref Vacfile, ms: ref Source): ref Vacdir;
    1.41+	new:	fn(session: ref Venti->Session, e, me: ref Venti->Entry): ref Vacdir;
    1.42+	walk:	fn(v: self ref Vacdir, elem: string): ref Direntry;
    1.43+	open:	fn(v: self ref Vacdir, de: ref Direntry):
    1.44+			(ref Venti->Entry, ref Venti->Entry);
    1.45+	readdir:	fn(v: self ref Vacdir):
    1.46+				(int, ref Direntry);
    1.47+	rewind:	fn(v: self ref Vacdir);
    1.48+};
    1.49+
    1.50+File: adt {
    1.51+	new:	fn(s: ref Venti->Session, dtype, dsize, varblocks: int): ref File;
    1.52+	write:	fn(f: self ref File, d: array of byte): int;
    1.53+	finish:	fn(f: self ref File): ref Venti->Entry;
    1.54+	mkstate:	fn(session: ref Venti->Session, e: ref Venti->Entry, varblocks: int): ref File;
    1.55+};
    1.56+
    1.57+Sink: adt {
    1.58+	new:	fn(s: ref Venti->Session, dsize: int): ref Sink;
    1.59+	add:	fn(m: self ref Sink, e: ref Venti->Entry): int;
    1.60+	finish:	fn(m: self ref Sink): ref Venti->Entry;
    1.61+};
    1.62+
    1.63+MSink: adt {
    1.64+	new:	fn(s: ref Venti->Session, dsize: int): ref MSink;
    1.65+	add:	fn(m: self ref MSink, de: ref Direntry): int;
    1.66+	finish:	fn(m: self ref MSink): ref Venti->Entry;
    1.67+};
    1.68+
    1.69+blocksread, blockswritten, bytesread, byteswritten: big;
    1.70+
    1.71+openroot:
    1.72+	fn(session: ref Venti->Session, score: Venti->Score):
    1.73+		(ref Vacdir, ref Direntry, string);
    1.74+readscore:
    1.75+	fn(path: string):
    1.76+		(string, ref Venti->Score, string);
    1.77+.EE
    1.78+.SH DESCRIPTION
    1.79+.I Vac
    1.80+is a module for reading and writing venti archives.
    1.81+.B Init
    1.82+initialises the module and must be called before any other function.
    1.83+Adt's
    1.84+.IR Source ,
    1.85+.IR Vacfile and
    1.86+.I Vacdir
    1.87+provide functions for reading venti archives, along with
    1.88+.B openroot
    1.89+and
    1.90+.BR readscore .
    1.91+Adt's
    1.92+.IR File ,
    1.93+.IR Sink and
    1.94+.I MSink 
    1.95+facilitate writing archives.
    1.96+.PP
    1.97+A
    1.98+.B Direntry
    1.99+is used for both writing and reading and is the vac equivalent of a
   1.100+.BR Sys->Dir .
   1.101+.TP
   1.102+.IB Direntry .new()
   1.103+Returns a new, empty
   1.104+.BR Direntry .
   1.105+.TP
   1.106+.IB Direntry .mk(\fIdir\fP)
   1.107+Returns the
   1.108+.B Direntry
   1.109+equivalent of
   1.110+.IR dir .
   1.111+.TP
   1.112+.IB d .mkdir()
   1.113+Returns the
   1.114+.B Dir
   1.115+equivalent of
   1.116+.IR d .
   1.117+.TP
   1.118+.IB d .pack()
   1.119+Packs
   1.120+.I d
   1.121+into
   1.122+.I Direntrysize
   1.123+bytes.
   1.124+.TP
   1.125+.IB Direntry .unpack(\fIdata\fP)
   1.126+Unpacks
   1.127+.I data
   1.128+into a
   1.129+.BR Direntry .
   1.130+
   1.131+.PP
   1.132+.B Source
   1.133+holds a
   1.134+.B Venti->Entry
   1.135+from which
   1.136+whole blocks of data from the hash tree are read from.
   1.137+The difference with a plain
   1.138+entry
   1.139+is that it has a
   1.140+.B Venti->Session
   1.141+associated with it.
   1.142+.TP
   1.143+.BI s .new(\fIsession\fP,\ \fIentry\fP)
   1.144+Create a new
   1.145+.B Source
   1.146+from the
   1.147+.I session
   1.148+and the
   1.149+.IR Entry .
   1.150+Always succeeds.
   1.151+.TP
   1.152+.BI s .get(\fIindex\fP,\ \fIdata\fP)
   1.153+Read a block from the hash tree into buffer
   1.154+.IR data .
   1.155+.I Index
   1.156+denotes which data block to read, considering only data blocks (not pointer blocks).  The first data block is 0.
   1.157+This function performs zero-extension and only works on entries that do not have the
   1.158+.I Entryvarblocks
   1.159+bit set.
   1.160+.TP
   1.161+.BI s .oget(\fIoffset\fP)
   1.162+Read a block from the hash tree starting at
   1.163+.I offset .
   1.164+The data returned has been zero-extended.
   1.165+This functions also works on
   1.166+.B Entries
   1.167+with the
   1.168+.I Entryvarblocks
   1.169+bit set.
   1.170+
   1.171+.PP
   1.172+.B Vacfile
   1.173+is a
   1.174+.B Source
   1.175+with with an offset associated with it.  It provides the standard functions
   1.176+.BR read ,
   1.177+.B pread
   1.178+and
   1.179+.BR seek .
   1.180+A
   1.181+.B Vacfile
   1.182+can be created by
   1.183+.BI Vacfile.mk(\fIsource\fP)
   1.184+and
   1.185+.BI Vacfile.new(\fIsession\fP,\ \fIentry\fP) .
   1.186+These functions always succeed.
   1.187+
   1.188+.PP
   1.189+.B Vacdir
   1.190+represents a directory stored in a venti archive.  A venti directory is stored in Venti as two hash trees: one containing Entries representing the (data) contents of files and one containing all meta-information (direntries) for those files.  A file in a directory is represented as a
   1.191+.IR Direntry .
   1.192+.TP
   1.193+.BI vd .mk(\fIvacfile\fP,\ \fImetasource\fP)
   1.194+Open a venti directory.
   1.195+.I Vacfile
   1.196+should contain Entries,
   1.197+.I metasource
   1.198+should contain Direntries.
   1.199+.TP
   1.200+.BI vd .new(\fIsession\fP,\ \fIentry\fP,\ \fImetaentry\fP)
   1.201+Open a venti directory from a
   1.202+.I entry
   1.203+and
   1.204+.IR metaentry ,
   1.205+such as those as returned by 
   1.206+.IR Vacdir.open .
   1.207+.TP
   1.208+.BI vd .walk(\fIelem\fP)
   1.209+Return the
   1.210+.B Direntry
   1.211+representing the file
   1.212+.IR elem .
   1.213+.B Nil
   1.214+is returned when the file does not exist and the system error string set.
   1.215+.TP
   1.216+.BI vd .open(\fIdirentry\fP)
   1.217+`Open' the file represented by
   1.218+.IR direntry ,
   1.219+by returning its
   1.220+entry and metaentry.
   1.221+The metaentry (second element of the tuple) is
   1.222+nil
   1.223+for files and
   1.224+non-nil
   1.225+for directories.
   1.226+.TP
   1.227+.BI vd .readdir()
   1.228+Read files in a directory.  The number of direntries returned depends on the block size of the underlying archive.
   1.229+The first element of the tuple has the number of direntries returned and is < 0 for errors, and 0 when all files have been returned.  
   1.230+.TP
   1.231+.BI vd .rewind()
   1.232+Rewind the directory offset to 0.  Subsequent reads again return files.
   1.233+
   1.234+.PP
   1.235+A
   1.236+.B File
   1.237+is used for writing files to Venti as hash trees, eventually resulting in an
   1.238+.B Entry.
   1.239+.TP
   1.240+.IB f .new(\fIsession\fP,\ \fIdtype\fP,\ \fIdsize\fP,\ \fIvarblocks\fP)
   1.241+Start a new, empty file.
   1.242+.I Dtype
   1.243+is the type of the data being written, typically
   1.244+.I Venti->Datatype
   1.245+for a regular file.
   1.246+.I Dsize
   1.247+is the data and pointer block size.  Constant
   1.248+.I Dsize
   1.249+is currently defined to 8192.
   1.250+.I Varblocks
   1.251+denotes whether the hash tree should be considered to have a variable block size.
   1.252+If it is non-zero,
   1.253+.I dsize
   1.254+has no meaning for the data block size and is only used for the pointer block size.
   1.255+.TP
   1.256+.BI f .write(\fIdata\fP)
   1.257+Write
   1.258+.I data
   1.259+to the hash tree.
   1.260+The data is flushed to venti immediately and considered to be a single data block in the hash tree.  Zero-truncation is performed on it.
   1.261+On failure -1 is returned, on success 0 is returned.
   1.262+Pointer blocks that have filled up by this write are flushed as well.
   1.263+.TP
   1.264+.BI f .finish()
   1.265+Flush all remaining pointer blocks and the top-level
   1.266+.B Entry to Venti and return the
   1.267+.B Entry.
   1.268+.TP
   1.269+.BI f .mkstate(\fIsession\fP,\ \fIentry\fP,\ \fIvarblocks\fP)
   1.270+Initialise a
   1.271+.B File
   1.272+from an existing
   1.273+.BR Entry .
   1.274+This can be used to append data to an already existing file.
   1.275+
   1.276+.PP
   1.277+A
   1.278+.B Sink
   1.279+is used to write venti directories.
   1.280+It consists of a
   1.281+.B File
   1.282+to which
   1.283+.B Entries
   1.284+can be added.  Note that
   1.285+.B Direntries
   1.286+are written using an
   1.287+.BR MSink .
   1.288+Data is only written to the
   1.289+.B File
   1.290+when a data block has been filled with entries.
   1.291+.TP
   1.292+.BI s .new(\fIsession\fP,\ \fIdsize\fP)
   1.293+Make a new, empty directory.  The size of the blocks in which entries are stored is
   1.294+.IR dsize .
   1.295+.TP
   1.296+.BI s .add(\fIentry\fP)
   1.297+Add an entry to the directory.
   1.298+If a block is filled, it is flushed to Venti.
   1.299+.TP
   1.300+.BI s .finish()
   1.301+Flush the underlying file and return the
   1.302+.B Entry
   1.303+representing the directory.
   1.304+
   1.305+.PP
   1.306+An
   1.307+.B MSink
   1.308+is used to write the
   1.309+.I Direntries
   1.310+of a venti directory.  It behaves identical to a
   1.311+.BR Sink ,
   1.312+with the difference that function
   1.313+.B add
   1.314+writes a
   1.315+.B Direntry
   1.316+by extracting the
   1.317+.B Entry
   1.318+from it,
   1.319+and another
   1.320+.B Entry
   1.321+for the meta-information if the
   1.322+.B Direntry
   1.323+represents a directory.
   1.324+
   1.325+.PP
   1.326+The variables
   1.327+.IR blocksread ,
   1.328+.IR blockswritten ,
   1.329+.IR bytesread and
   1.330+.I byteswritten
   1.331+are kept up to date during module use.
   1.332+They contain the total number of blocks and bytes read from and
   1.333+written to the venti server.  Venti protocol overhead is ignored,
   1.334+only the message payloads are accounted for.
   1.335+.PP
   1.336+.B Readscore
   1.337+parses a score from the file represented by
   1.338+.IR path .
   1.339+The returned tuple contains the type of the score (e.g.
   1.340+.I vac
   1.341+if the score references a
   1.342+.B Root
   1.343+block), the second element is the parsed score itself.  The third element describes an error if it is not
   1.344+.IR nil .
   1.345+.PP
   1.346+.B Openroot
   1.347+opens the top-level directory of a vac archive by the
   1.348+.I score
   1.349+of its
   1.350+.B Root
   1.351+block.
   1.352+The tuple returned contains the 
   1.353+.BI Vacdir ,
   1.354+and the
   1.355+.B Direntry
   1.356+containing information about the root directory.  The third element describes an error if it is not
   1.357+.RI nil .
   1.358+.SH SOURCE
   1.359+.B /appl/lib/vac.b
   1.360+.SH "SEE ALSO"
   1.361+.IR venti (2)
   1.362+.SH DIAGNOSTICS
   1.363+The functions unpacking data structures return nil for badly formed data, and set the system error string.
   1.364+.SH BUGS