VENTI-FILE(3)

💖 NAME 💖

okay bestie, this is VENTI-FILE(3) from the Library Functions Manual — the Venti files page. It stars VtFile plus all these functions: vtfileblock, vtfileblockscore, vtfileclose, vtfilecreate, vtfilecreateroot, vtfileflush, vtfileflushbefore, vtfilegetdirsize, vtfilegetentry, vtfilegetsize, vtfileincref, vtfilelock, vtfilelock2, vtfileopen, vtfileopenroot, vtfileread, vtfileremove, vtfilesetdirsize, vtfilesetentry, vtfilesetsize, vtfiletruncate, vtfileunlock, vtfilewrite. They’re the whole vibe for creating and manipulating Venti files ✨.

🌸 SYNOPSIS 🌸

VtFile*  vtfilecreateroot(VtCache *c, int psize, int dsize, int type);

VtFile*  vtfileopenroot(VtCache *c, VtEntry *e);

VtFile*  vtfileopen(VtFile *f, u32int n, int mode);

VtFile*  vtfilecreate(VtFile *f, int psize, int dsize, int type);

void     vtfileincref(VtFile *f);

void     vtfileclose(VtFile *f);

int      vtfileremove(VtFile *f);

VtBlock* vtfileblock(VtFile *f, u32int n, int mode);

long     vtfileread(VtFile *f, void *buf, long n, vlong offset);

long     vtfilewrite(VtFile *f, void *buf, long n, vlong offset);

int      vtfileflush(VtFile *f);

int      vtfileflushbefore(VtFile *f, vlong offset);

int      vtfiletruncate(VtFile *f);

uvlong   vtfilegetsize(VtFile *f);

int      vtfilesetsize(VtFile *f, vlong size);

u32int   vtfilegetdirsize(VtFile *f);

int      vtfilesetdirsize(VtFile *f, u32int size);

int      vtfilegetentry(VtFile *f, VtEntry *e);

int      vtfilesetentry(VtFile *f, VtEntry *e);

int      vtfileblockscore(VtFile *f, u32int n, uchar score[VtScoreSize]);

int      vtfilelock(VtFile *f, int mode);

int      vtfilelock2(VtFile *f, VtFile *f, int mode);

void     vtfileunlock(VtFile *f);

🦋 DESCRIPTION 🦋

These routines give you a simple interface to create and manipulate Venti file trees (see venti(7)). slay.

🎀 creating + opening files

• vtfilecreateroot — creates a new Venti file. type must be either VtDataType or VtDirType, specifying a data or directory file. dsize is the block size to use for leaf (data or directory) blocks in the hash tree; psize is the block size to use for internal (pointer) blocks.
• vtfileopenroot — opens an existing Venti file described by e.
• vtfileopen — opens the Venti file described by the nth entry in the directory f. mode should be one of VtOREAD, VtOWRITE, or VtORDWR, indicating how the returned file is to be used. The VtOWRITE and VtORDWR modes can only be used if f is open with mode VtORDWR.
• vtfilecreate — creates a new file in the directory f with block type type and block sizes dsize and psize (see vtfilecreateroot above).

💅 reference counts + remove

• vtfileincref — each file has an associated reference count and holds a reference to its parent in the file tree. This increments that reference count.
• vtfileclose — decrements the reference count. If there are no other references, vtfileclose releases the reference to f’s parent and then frees the in-memory structure f. The data stored in f is still accessible by reopening it.
• vtfileremove — removes the file f from its parent directory. It also acts as vtfileclose, releasing the reference to f and potentially freeing the structure.

🧚 blocks, reading, writing, flushing

• vtfileblock — returns the nth block in the file f. If there are not n blocks in the file and mode is VtOREAD, vtfileblock returns nil. If the mode is VtOWRITE or VtORDWR, vtfileblock grows the file as needed and then returns the block.
• vtfileread — reads at most n bytes at offset offset from f into memory at buf. It returns the number of bytes read.
• vtfilewrite — writes the n bytes in memory at buf into the file f at offset n. It returns the number of bytes written, or -1 on error. Writing fewer bytes than requested will only happen if an error is encountered. It writes to an in-memory copy of the data blocks (see venti-cache(3)) instead of writing directly to Venti.
• vtfileflush — writes all copied blocks associated with f to the Venti server.
• vtfileflushbefore — flushes only those blocks corresponding to data in the file before byte offset. If you’re looping with vtfilewrite, call vtfileflushbefore regularly so the block cache doesn’t fill up with unwritten blocks.

🌈 sizes, entries, scores

• vtfiletruncate — changes the file f to have zero length.
• vtfilegetsize — returns the length (in bytes) of file f.
• vtfilesetsize — sets the length (in bytes) of file f.
• vtfilegetdirsize — returns the length (in directory entries) of the directory f.
• vtfilesetdirsize — sets the length (in directory entries) of the directory f.
• vtfilegetentry — fills e with an entry that can be passed to vtfileopenroot to reopen f at a later time.
• vtfilesetentry — sets the entry associated with f to be e.
• vtfileblockscore — returns in score the score of the nth block in the file f.

👑 locking — read this part, bestie

Venti files are locked and unlocked via vtfilelock and vtfileunlock to moderate concurrent access. Only one thread at a time — the one that has the file locked — can read or modify the file. The functions that return files (vtfilecreateroot, vtfileopenroot, vtfilecreate, and vtfileopen) return them unlocked. When files are passed to any of the functions documented in this manual page, it is the caller’s responsibility to ensure that they are already locked.

Internally, a file is locked by locking the block that contains its directory entry. When two files in the same directory both need to be locked, vtfilelock2 must be used. It locks both its arguments, taking special care not to deadlock if their entries are stored in the same directory block.

🌟 SOURCE 🌟

/src/libventi/file.c

🫶 SEE ALSO 🫶

venti-cache(3), venti-conn(3), venti-client(3), venti(7)

mwah 💋 — that’s VENTI-FILE(3) from the Library Functions Manual. source: /src/libventi/file.c; footer: literally just VENTI-FILE(3) (no date on this one, bestie). periodt.