plan9fox/sys/man/2/venti-file

.TH VENTI-FILE 2
.SH NAME
VtFile,
vtfileblock,
vtfileblockscore,
vtfileclose,
vtfilecreate,
vtfilecreateroot,
vtfileflush,
vtfileflushbefore,
vtfilegetdirsize,
vtfilegetentry,
vtfilegetsize,
vtfileincref,
vtfilelock,
vtfilelock2,
vtfileopen,
vtfileopenroot,
vtfileread, 
vtfileremove,
vtfilesetdirsize,
vtfilesetentry,
vtfilesetsize,
vtfiletruncate,
vtfileunlock,
vtfilewrite \- Venti files
.SH SYNOPSIS
.ta +\w'\fLVtBlock* 'u
.PP
.B
VtFile*	vtfilecreateroot(VtCache *c, int psize, int dsize, int type);
.PP
.B
VtFile*	vtfileopenroot(VtCache *c, VtEntry *e);
.PP
.B
VtFile*	vtfileopen(VtFile *f, u32int n, int mode);
.PP
.B
VtFile*	vtfilecreate(VtFile *f, int psize, int dsize, int type);
.PP
.B
void	vtfileincref(VtFile *f);
.PP
.B
void	vtfileclose(VtFile *f);
.PP
.B
int	vtfileremove(VtFile *f);
.PP
.B
VtBlock*	vtfileblock(VtFile *f, u32int n, int mode);
.PP
.B
long	vtfileread(VtFile *f, void *buf, long n, vlong offset);
.PP
.B
long	vtfilewrite(VtFile *f, void *buf, long n, vlong offset);
.PP
.B
int	vtfileflush(VtFile *f);
.PP
.B
int	vtfileflushbefore(VtFile *f, vlong offset);
.PP
.B
int	vtfiletruncate(VtFile *f);
.PP
.B
uvlong	vtfilegetsize(VtFile *f);
.PP
.B
int	vtfilesetsize(VtFile *f, vlong size);
.PP
.B
u32int	vtfilegetdirsize(VtFile *f);
.PP
.B
int	vtfilesetdirsize(VtFile *f, u32int size);
.PP
.B
int	vtfilegetentry(VtFile *f, VtEntry *e);
.PP
.B
int	vtfilesetentry(VtFile *f, VtEntry *e);
.PP
.B
int	vtfileblockscore(VtFile *f, u32int n, 
	    uchar score[VtScoreSize]);
.PP
.B
int	vtfilelock(VtFile *f, int mode);
.PP
.B
int	vtfilelock2(VtFile *f, VtFile *f, int mode);
.PP
.B
void	vtfileunlock(VtFile *f);
.SH DESCRIPTION
These routines provide a simple interface to create and
manipulate Venti file trees (see
.IR venti (6)).
.PP
.I Vtfilecreateroot
creates a new Venti file.
.I Type
must be either
.B VtDataType
or
.BR VtDirType ,
specifying a data or directory file.
.I Dsize
is the block size to use for leaf (data or directory) blocks in the hash tree;
.I psize
is the block size to use for internal (pointer) blocks.
.PP
.I Vtfileopenroot
opens an existing Venti file described by
.IR e .
.PP
.I Vtfileopen
opens the Venti file described by the
.IR n th
entry in the directory
.IR f .
.I Mode
should be one of
.BR VtOREAD ,
.BR VtOWRITE ,
or
.BR VtORDWR ,
indicating how the returned file is to be used.
The
.BR VtOWRITE
and
.BR VtORDWR
modes can only be used if
.IR f
is open with mode
.BR VtORDWR .
.PP
.I Vtfilecreate
creates a new file in the directory
.I f
with block type
.I type
and block sizes
.I dsize
and
.I psize
(see
.I vtfilecreateroot
above).
.PP
Each file has an associated reference count
and holds a reference to its parent in the file tree.
.I Vtfileincref
increments this reference count.
.I Vtfileclose
decrements the reference count.
If there are no other references,
.I vtfileclose
releases the reference to
.IR f 's
parent and then frees the in-memory structure
.IR f .
The data stored in 
.I f
is still accessible by reopening it.
.PP
.I Vtfileremove
removes the file
.I f
from its parent directory.
It also acts as 
.IR vtfileclose ,
releasing the reference to
.I f
and potentially freeing the structure.
.PP
.I Vtfileblock
returns the
.IR n th
block in the file
.IR f .
If there are not 
.I n
blocks in the file and
.I mode
is 
.BR VtOREAD ,
.I vtfileblock
returns nil.
If the mode is
.B VtOWRITE
or
.BR VtORDWR ,
.I vtfileblock
grows the file as needed and then returns the block.
.PP
.I Vtfileread
reads at most
.I n
bytes at offset
.I offset
from
.I f
into memory at
.IR buf .
It returns the number of bytes read.
.PP
.I Vtfilewrite
writes the 
.I n
bytes in memory at
.I buf
into the file
.I f
at offset 
.IR 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.
.PP
.I Vtfilewrite
writes to an in-memory copy of the data blocks
(see
.IR venti-cache (2))
instead of writing directly to Venti.
.I Vtfileflush
writes all copied blocks associated with 
.I f
to the Venti server.
.I Vtfileflushbefore
flushes only those blocks corresponding to data in the file before
byte
.IR offset .
Loops that
.I vtfilewrite
should call
.I vtfileflushbefore
regularly to avoid filling the block cache with unwritten blocks.
.PP
.I Vtfiletruncate
changes the file
.I f
to have zero length.
.PP
.I Vtfilegetsize
returns the length (in bytes) of file
.IR f .
.PP
.I Vtfilesetsize
sets the length (in bytes) of file
.IR f .
.PP
.I Vtfilegetdirsize
returns the length (in directory entries)
of the directory
.IR f .
.PP
.I Vtfilesetdirsize
sets the length (in directory entries)
of the directory
.IR f .
.PP
.I Vtfilegetentry
fills
.I e
with an entry that can be passed to
.IR vtfileopenroot
to reopen
.I f
at a later time.
.PP
.I Vtfilesetentry
sets the entry associated with
.I f
to be
.IR e .
.PP
.I Vtfileblockscore
returns in
.I score
the score of the
.IR n th
block in the file
.IR f .
.PP
Venti files are locked and unlocked
via
.I vtfilelock
and
.I vtfileunlock
to moderate concurrent access.
Only one thread at a time\(emthe one that has the file locked\(emcan
read or modify the file.
The functions that return files
.RI ( vtfilecreateroot ,
.IR vtfileopenroot ,
.IR vtfilecreate ,
and
.IR 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.
.PP
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,
.I 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.
.SH SOURCE
.B /sys/src/libventi/file.c
.SH SEE ALSO
.IR venti-cache (2),
.IR venti-conn (2),
.IR venti-client (2),
.IR venti (6)