VENTI-FILE(2)                                       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 off-
          set);

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

     VENTI-FILE(2)                                       VENTI-FILE(2)

          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 direc-
          tory 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 ref-
          erence to its parent in the file tree.  Vtfileincref incre-
          ments this reference count.  Vtfileclose decrements the ref-
          erence 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.

          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

     VENTI-FILE(2)                                       VENTI-FILE(2)

          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.

          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 regu-
          larly 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 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.

          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 mod-
          ify 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 con-
          tains 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.

     VENTI-FILE(2)                                       VENTI-FILE(2)

     SOURCE
          /sys/src/libventi/file.c

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