changelog shortlog tags branches changeset files revisions annotate raw help

Mercurial > hg > ventivac / man/2/vac

changeset 150: f041fd652c81
parent: 6a1948263a76
child: 2dd3d57a4d07
author: Mechiel Lukkien <mechiel@ueber.net>
date: Thu, 30 Aug 2007 19:34:34 +0200
permissions: -rw-r--r--
description: fix formatting, very visible in man2html output.
1 .TH VAC 2
2 .SH NAME
3 vac \- read/write venti archives
4 .SH SYNOPSIS
5 .EX
6 include "vac.m";
7 vac := load Vac Vac->PATH;
8 Direntry: import vac;
9 Source, Vacdir, Vacfile: import vac;
10 File, Sink, MSink: import vac;
11 
12 init: fn();
13 
14 Direntry: adt {
15  new: fn(): ref Direntry;
16  mk: fn(d: Sys->Dir): ref Direntry;
17  mkdir: fn(de: self ref Direntry): ref Sys->Dir;
18  pack: fn(de: self ref Direntry): array of byte;
19  unpack: fn(d: array of byte): ref Direntry;
20 };
21 
22 Source: adt {
23  new: fn(s: ref Venti->Session, e: ref Venti->Entry): ref Source;
24  get: fn(s: self ref Source, i: big, d: array of byte): int;
25  oget: fn(s: self ref Source, offset: big): array of byte;
26 };
27 
28 Vacfile: adt {
29  mk: fn(s: ref Source): ref Vacfile;
30  new: fn(session: ref Venti->Session, e: ref Venti->Entry): ref Vacfile;
31  read: fn(v: self ref Vacfile, d: array of byte, n: int): int;
32  seek: fn(v: self ref Vacfile, offset: big): big;
33  pread: fn(v: self ref Vacfile, d: array of byte, n: int, offset: big): int;
34 };
35 
36 Vacdir: adt {
37  mk: fn(vf: ref Vacfile, ms: ref Source): ref Vacdir;
38  new: fn(session: ref Venti->Session, e, me: ref Venti->Entry): ref Vacdir;
39  walk: fn(v: self ref Vacdir, elem: string): ref Direntry;
40  open: fn(v: self ref Vacdir, de: ref Direntry):
41  (ref Venti->Entry, ref Venti->Entry);
42  readdir: fn(v: self ref Vacdir):
43  (int, ref Direntry);
44  rewind: fn(v: self ref Vacdir);
45 };
46 
47 File: adt {
48  new: fn(s: ref Venti->Session, dtype, dsize, varblocks: int): ref File;
49  write: fn(f: self ref File, d: array of byte): int;
50  finish: fn(f: self ref File): ref Venti->Entry;
51  mkstate: fn(session: ref Venti->Session, e: ref Venti->Entry, varblocks: int): ref File;
52 };
53 
54 Sink: adt {
55  new: fn(s: ref Venti->Session, dsize: int): ref Sink;
56  add: fn(m: self ref Sink, e: ref Venti->Entry): int;
57  finish: fn(m: self ref Sink): ref Venti->Entry;
58 };
59 
60 MSink: adt {
61  new: fn(s: ref Venti->Session, dsize: int): ref MSink;
62  add: fn(m: self ref MSink, de: ref Direntry): int;
63  finish: fn(m: self ref MSink): ref Venti->Entry;
64 };
65 
66 blocksread, blockswritten, bytesread, byteswritten: big;
67 
68 openroot:
69  fn(session: ref Venti->Session, score: Venti->Score):
70  (ref Vacdir, ref Direntry, string);
71 readscore:
72  fn(path: string):
73  (string, ref Venti->Score, string);
74 .EE
75 .SH DESCRIPTION
76 .I Vac
77 is a module for reading and writing venti archives.
78 .B Init
79 initialises the module and must be called before any other function.
80 Adt's
81 .IR Source ,
82 .I Vacfile
83 and
84 .I Vacdir
85 provide functions for reading venti archives, along with
86 .B openroot
87 and
88 .BR readscore .
89 Adt's
90 .IR File ,
91 .I Sink
92 and
93 .I MSink
94 facilitate writing archives.
95 .PP
96 A
97 .B Direntry
98 is used for both writing and reading and is the vac equivalent of a
99 .BR Sys->Dir .
100 .TP
101 .IB Direntry .new()
102 Returns a new, empty
103 .BR Direntry .
104 .TP
105 .IB Direntry .mk(\fIdir\fP)
106 Returns the
107 .B Direntry
108 equivalent of
109 .IR dir .
110 .TP
111 .IB d .mkdir()
112 Returns the
113 .B Dir
114 equivalent of
115 .IR d .
116 .TP
117 .IB d .pack()
118 Packs
119 .I d
120 into
121 .I Direntrysize
122 bytes.
123 .TP
124 .IB Direntry .unpack(\fIdata\fP)
125 Unpacks
126 .I data
127 into a
128 .BR Direntry .
129 
130 .PP
131 .B Source
132 holds a
133 .B Venti->Entry
134 from which
135 whole blocks of data from the hash tree are read from.
136 The difference with a plain
137 entry
138 is that it has a
139 .B Venti->Session
140 associated with it.
141 .TP
142 .IB s .new(\fIsession\fP,\ \fIentry\fP)
143 Create a new
144 .B Source
145 from the
146 .I session
147 and the
148 .IR Entry .
149 Always succeeds.
150 .TP
151 .IB s .get(\fIindex\fP,\ \fIdata\fP)
152 Read a block from the hash tree into buffer
153 .IR data .
154 .I Index
155 denotes which data block to read, considering only data blocks (not pointer blocks). The first data block is 0.
156 This function performs zero-extension and only works on entries that do not have the
157 .I Entryvarblocks
158 bit set.
159 .TP
160 .IB s .oget(\fIoffset\fP)
161 Read a block from the hash tree starting at
162 .I offset .
163 The data returned has been zero-extended.
164 This functions also works on
165 .B Entries
166 with the
167 .I Entryvarblocks
168 bit set.
169 
170 .PP
171 .B Vacfile
172 is a
173 .B Source
174 with with an offset associated with it. It provides the standard functions
175 .BR read ,
176 .B pread
177 and
178 .BR seek .
179 A
180 .B Vacfile
181 can be created by
182 .IB Vacfile.mk(\fIsource\fP)
183 and
184 .IB Vacfile.new(\fIsession\fP,\ \fIentry\fP) .
185 These functions always succeed.
186 
187 .PP
188 .B Vacdir
189 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
190 .IR Direntry .
191 .TP
192 .IB vd .mk(\fIvacfile\fP,\ \fImetasource\fP)
193 Open a venti directory.
194 .I Vacfile
195 should contain Entries,
196 .I metasource
197 should contain Direntries.
198 .TP
199 .IB vd .new(\fIsession\fP,\ \fIentry\fP,\ \fImetaentry\fP)
200 Open a venti directory from a
201 .I entry
202 and
203 .IR metaentry ,
204 such as those as returned by
205 .IR Vacdir.open .
206 .TP
207 .IB vd .walk(\fIelem\fP)
208 Return the
209 .B Direntry
210 representing the file
211 .IR elem .
212 .B Nil
213 is returned when the file does not exist and the system error string set.
214 .TP
215 .IB vd .open(\fIdirentry\fP)
216 `Open' the file represented by
217 .IR direntry ,
218 by returning its
219 entry and metaentry.
220 The metaentry (second element of the tuple) is
221 nil
222 for files and
223 non-nil
224 for directories.
225 .TP
226 .IB vd .readdir()
227 Read files in a directory. The number of direntries returned depends on the block size of the underlying archive.
228 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.
229 .TP
230 .IB vd .rewind()
231 Rewind the directory offset to 0. Subsequent reads again return files.
232 
233 .PP
234 A
235 .B File
236 is used for writing files to Venti as hash trees, eventually resulting in an
237 .B Entry.
238 .TP
239 .IB f .new(\fIsession\fP,\ \fIdtype\fP,\ \fIdsize\fP,\ \fIvarblocks\fP)
240 Start a new, empty file.
241 .I Dtype
242 is the type of the data being written, typically
243 .I Venti->Datatype
244 for a regular file.
245 .I Dsize
246 is the data and pointer block size. Constant
247 .I Dsize
248 is currently defined to 8192.
249 .I Varblocks
250 denotes whether the hash tree should be considered to have a variable block size.
251 If it is non-zero,
252 .I dsize
253 has no meaning for the data block size and is only used for the pointer block size.
254 .TP
255 .IB f .write(\fIdata\fP)
256 Write
257 .I data
258 to the hash tree.
259 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.
260 On failure -1 is returned, on success 0 is returned.
261 Pointer blocks that have filled up by this write are flushed as well.
262 .TP
263 .IB f .finish()
264 Flush all remaining pointer blocks and the top-level
265 .B Entry
266 to Venti and return the entry.
267 .TP
268 .IB f .mkstate(\fIsession\fP,\ \fIentry\fP,\ \fIvarblocks\fP)
269 Initialise a
270 .B File
271 from an existing
272 .BR Entry .
273 This can be used to append data to an already existing file.
274 
275 .PP
276 A
277 .B Sink
278 is used to write venti directories.
279 It consists of a
280 .B File
281 to which
282 .B Entries
283 can be added. Note that
284 .B Direntries
285 are written using an
286 .BR MSink .
287 Data is only written to the
288 .B File
289 when a data block has been filled with entries.
290 .TP
291 .IB s .new(\fIsession\fP,\ \fIdsize\fP)
292 Make a new, empty directory. The size of the blocks in which entries are stored is
293 .IR dsize .
294 .TP
295 .IB s .add(\fIentry\fP)
296 Add an entry to the directory.
297 If a block is filled, it is flushed to Venti.
298 .TP
299 .IB s .finish()
300 Flush the underlying file and return the
301 .B Entry
302 representing the directory.
303 
304 .PP
305 An
306 .B MSink
307 is used to write the
308 .I Direntries
309 of a venti directory. It behaves identical to a
310 .BR Sink ,
311 with the difference that function
312 .B add
313 writes a
314 .B Direntry
315 by extracting the
316 .B Entry
317 from it,
318 and another
319 .B Entry
320 for the meta-information if the
321 .B Direntry
322 represents a directory.
323 
324 .PP
325 The variables
326 .IR blocksread ,
327 .IR blockswritten ,
328 .I bytesread
329 and
330 .I byteswritten
331 are kept up to date during module use.
332 They contain the total number of blocks and bytes read from and
333 written to the venti server. Venti protocol overhead is ignored,
334 only the message payloads are accounted for.
335 .PP
336 .B Readscore
337 parses a score from the file represented by
338 .IR path .
339 The returned tuple contains the type of the score (e.g.
340 .I vac
341 if the score references a
342 .B Root
343 block), the second element is the parsed score itself. The third element describes an error if it is not
344 .IR nil .
345 .PP
346 .B Openroot
347 opens the top-level directory of a vac archive by the
348 .I score
349 of its
350 .B Root
351 block.
352 The tuple returned contains the
353 .BR Vacdir ,
354 and the
355 .B Direntry
356 containing information about the root directory. The third element describes an error if it is not
357 .RI nil .
358 .SH SOURCE
359 .B /appl/lib/vac.b
360 .SH "SEE ALSO"
361 .IR venti (2)
362 .SH DIAGNOSTICS
363 The functions unpacking data structures return nil for badly formed data, and set the system error string.