glenda.party
term% ls -F
term% cat index.txt
VENTI-FILE(2)                 System Calls Manual                VENTI-FILE(2)



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

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  provide  a  simple  interface to create and manipulate
       Venti file trees (see venti(6)).

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

       Each  file  has  an associated reference count and holds a reference to
       its parent in the file tree.  Vtfileincref  increments  this  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 free‐
       ing the structure.

       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 off‐
       set  n.  It returns the number of bytes written, or -1 on error.  Writ‐
       ing fewer bytes than requested will only happen if an error is  encoun‐
       tered.

       Vtfilewrite  writes to an in-memory copy of the data blocks (see venti-
       cache(2)) 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.  Loops that vtfilewrite should call vtfileflushbefore regularly
       to avoid filling the block cache with unwritten blocks.

       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 direc‐
       tory f.

       Vtfilegetentry fills e with an entry that can be passed to  vtfileopen‐
       root 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.

       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
       /sys/src/libventi/file.c

SEE ALSO
       venti-cache(2), venti-conn(2), venti-client(2), venti(6)



                                                                 VENTI-FILE(2)