1
0

venti-file 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325
  1. .TH VENTI-FILE 2
  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. .IR venti (6)).
  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. .IR venti-cache (2))
  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 /sys/src/libventi/file.c
  321. .SH SEE ALSO
  322. .IR venti-cache (2),
  323. .IR venti-conn (2),
  324. .IR venti-client (2),
  325. .IR venti (6)