tventi-file.3 - 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
---
tventi-file.3 (5844B)
---
1 .TH VENTI-FILE 3
2 .SH NAME
3 VtFile,
4 vtfileblock,
5 vtfileblockscore,
6 vtfileclose,
7 vtfilecreate,
8 vtfilecreateroot,
9 vtfileflush,
10 vtfileflushbefore,
11 vtfilegetdirsize,
12 vtfilegetentry,
13 vtfilegetsize,
14 vtfileincref,
15 vtfilelock,
16 vtfilelock2,
17 vtfileopen,
18 vtfileopenroot,
19 vtfileread,
20 vtfileremove,
21 vtfilesetdirsize,
22 vtfilesetentry,
23 vtfilesetsize,
24 vtfiletruncate,
25 vtfileunlock,
26 vtfilewrite \- Venti files
27 .SH SYNOPSIS
28 .ta +\w'\fLVtBlock* 'u
29 .PP
30 .B
31 VtFile* vtfilecreateroot(VtCache *c, int psize, int dsize, int type);
32 .PP
33 .B
34 VtFile* vtfileopenroot(VtCache *c, VtEntry *e);
35 .PP
36 .B
37 VtFile* vtfileopen(VtFile *f, u32int n, int mode);
38 .PP
39 .B
40 VtFile* vtfilecreate(VtFile *f, int psize, int dsize, int type);
41 .PP
42 .B
43 void vtfileincref(VtFile *f);
44 .PP
45 .B
46 void vtfileclose(VtFile *f);
47 .PP
48 .B
49 int vtfileremove(VtFile *f);
50 .PP
51 .B
52 VtBlock* vtfileblock(VtFile *f, u32int n, int mode);
53 .PP
54 .B
55 long vtfileread(VtFile *f, void *buf, long n, vlong offset);
56 .PP
57 .B
58 long vtfilewrite(VtFile *f, void *buf, long n, vlong offset);
59 .PP
60 .B
61 int vtfileflush(VtFile *f);
62 .PP
63 .B
64 int vtfileflushbefore(VtFile *f, vlong offset);
65 .PP
66 .B
67 int vtfiletruncate(VtFile *f);
68 .PP
69 .B
70 uvlong vtfilegetsize(VtFile *f);
71 .PP
72 .B
73 int vtfilesetsize(VtFile *f, vlong size);
74 .PP
75 .B
76 u32int vtfilegetdirsize(VtFile *f);
77 .PP
78 .B
79 int vtfilesetdirsize(VtFile *f, u32int size);
80 .PP
81 .B
82 int vtfilegetentry(VtFile *f, VtEntry *e);
83 .PP
84 .B
85 int vtfilesetentry(VtFile *f, VtEntry *e);
86 .PP
87 .B
88 int vtfileblockscore(VtFile *f, u32int n,
89 uchar score[VtScoreSize]);
90 .PP
91 .B
92 int vtfilelock(VtFile *f, int mode);
93 .PP
94 .B
95 int vtfilelock2(VtFile *f, VtFile *f, int mode);
96 .PP
97 .B
98 void vtfileunlock(VtFile *f);
99 .SH DESCRIPTION
100 These routines provide a simple interface to create and
101 manipulate Venti file trees (see
102 .MR venti (7) ).
103 .PP
104 .I Vtfilecreateroot
105 creates a new Venti file.
106 .I Type
107 must be either
108 .B VtDataType
109 or
110 .BR VtDirType ,
111 specifying a data or directory file.
112 .I Dsize
113 is the block size to use for leaf (data or directory) blocks in the hash tree;
114 .I psize
115 is the block size to use for internal (pointer) blocks.
116 .PP
117 .I Vtfileopenroot
118 opens an existing Venti file described by
119 .IR e .
120 .PP
121 .I Vtfileopen
122 opens the Venti file described by the
123 .IR n th
124 entry in the directory
125 .IR f .
126 .I Mode
127 should be one of
128 .BR VtOREAD ,
129 .BR VtOWRITE ,
130 or
131 .BR VtORDWR ,
132 indicating how the returned file is to be used.
133 The
134 .BR VtOWRITE
135 and
136 .BR VtORDWR
137 modes can only be used if
138 .IR f
139 is open with mode
140 .BR VtORDWR .
141 .PP
142 .I Vtfilecreate
143 creates a new file in the directory
144 .I f
145 with block type
146 .I type
147 and block sizes
148 .I dsize
149 and
150 .I psize
151 (see
152 .I vtfilecreateroot
153 above).
154 .PP
155 Each file has an associated reference count
156 and holds a reference to its parent in the file tree.
157 .I Vtfileincref
158 increments this reference count.
159 .I Vtfileclose
160 decrements the reference count.
161 If there are no other references,
162 .I vtfileclose
163 releases the reference to
164 .IR f 's
165 parent and then frees the in-memory structure
166 .IR f .
167 The data stored in
168 .I f
169 is still accessible by reopening it.
170 .PP
171 .I Vtfileremove
172 removes the file
173 .I f
174 from its parent directory.
175 It also acts as
176 .IR vtfileclose ,
177 releasing the reference to
178 .I f
179 and potentially freeing the structure.
180 .PP
181 .I Vtfileblock
182 returns the
183 .IR n th
184 block in the file
185 .IR f .
186 If there are not
187 .I n
188 blocks in the file and
189 .I mode
190 is
191 .BR VtOREAD ,
192 .I vtfileblock
193 returns nil.
194 If the mode is
195 .B VtOWRITE
196 or
197 .BR VtORDWR ,
198 .I vtfileblock
199 grows the file as needed and then returns the block.
200 .PP
201 .I Vtfileread
202 reads at most
203 .I n
204 bytes at offset
205 .I offset
206 from
207 .I f
208 into memory at
209 .IR buf .
210 It returns the number of bytes read.
211 .PP
212 .I Vtfilewrite
213 writes the
214 .I n
215 bytes in memory at
216 .I buf
217 into the file
218 .I f
219 at offset
220 .IR n .
221 It returns the number of bytes written,
222 or \-1 on error.
223 Writing fewer bytes than requested will only happen
224 if an error is encountered.
225 .PP
226 .I Vtfilewrite
227 writes to an in-memory copy of the data blocks
228 (see
229 .MR venti-cache (3) )
230 instead of writing directly to Venti.
231 .I Vtfileflush
232 writes all copied blocks associated with
233 .I f
234 to the Venti server.
235 .I Vtfileflushbefore
236 flushes only those blocks corresponding to data in the file before
237 byte
238 .IR offset .
239 Loops that
240 .I vtfilewrite
241 should call
242 .I vtfileflushbefore
243 regularly to avoid filling the block cache with unwritten blocks.
244 .PP
245 .I Vtfiletruncate
246 changes the file
247 .I f
248 to have zero length.
249 .PP
250 .I Vtfilegetsize
251 returns the length (in bytes) of file
252 .IR f .
253 .PP
254 .I Vtfilesetsize
255 sets the length (in bytes) of file
256 .IR f .
257 .PP
258 .I Vtfilegetdirsize
259 returns the length (in directory entries)
260 of the directory
261 .IR f .
262 .PP
263 .I Vtfilesetdirsize
264 sets the length (in directory entries)
265 of the directory
266 .IR f .
267 .PP
268 .I Vtfilegetentry
269 fills
270 .I e
271 with an entry that can be passed to
272 .IR vtfileopenroot
273 to reopen
274 .I f
275 at a later time.
276 .PP
277 .I Vtfilesetentry
278 sets the entry associated with
279 .I f
280 to be
281 .IR e .
282 .PP
283 .I Vtfileblockscore
284 returns in
285 .I score
286 the score of the
287 .IR n th
288 block in the file
289 .IR f .
290 .PP
291 Venti files are locked and unlocked
292 via
293 .I vtfilelock
294 and
295 .I vtfileunlock
296 to moderate concurrent access.
297 Only one thread at a time\(emthe one that has the file locked\(emcan
298 read or modify the file.
299 The functions that return files
300 .RI ( vtfilecreateroot ,
301 .IR vtfileopenroot ,
302 .IR vtfilecreate ,
303 and
304 .IR vtfileopen )
305 return them unlocked.
306 When files are passed to any of the functions documented in
307 this manual page, it is the caller's responsibility to ensure that
308 they are already locked.
309 .PP
310 Internally, a file is locked by locking the
311 block that contains its directory entry.
312 When two files in the same
313 directory both need to be locked,
314 .I vtfilelock2
315 must be used.
316 It locks both its arguments, taking special care
317 not to deadlock if their entries are stored
318 in the same directory block.
319 .SH SOURCE
320 .B \*9/src/libventi/file.c
321 .SH SEE ALSO
322 .MR venti-cache (3) ,
323 .MR venti-conn (3) ,
324 .MR venti-client (3) ,
325 .MR venti (7)