venti-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)