buffercache(9) - NetBSD Manual Pages

BUFFERCACHE(9)         NetBSD Kernel Developer's Manual         BUFFERCACHE(9)


NAME

     buffercache, bread, breadn, bwrite, bawrite, bdwrite, getblk, geteblk,
     incore, allocbuf, brelse -- buffer cache interfaces


SYNOPSIS

     #include <sys/buf.h>

     int
     bread(struct vnode *vp, daddr_t blkno, int size, int flags, buf_t **bpp);

     int
     breadn(struct vnode *vp, daddr_t blkno, int size, daddr_t rablks[],
         int rasizes[], int nrablks, int flags, buf_t **bpp);

     int
     bwrite(buf_t *bp);

     void
     bawrite(buf_t *bp);

     void
     bdwrite(buf_t *bp);

     buf_t *
     getblk(struct vnode *vp, daddr_t blkno, int size, int slpflag,
         int slptimeo);

     buf_t *
     geteblk(int size);

     buf_t *
     incore(struct vnode *vp, daddr_t blkno);

     void
     allocbuf(buf_t *bp, int size, int preserve);

     void
     brelse(buf_t *bp, int set);


DESCRIPTION

     The buffercache interface is used by each filesystems to improve I/O per-
     formance using in-core caches of filesystem blocks.

     The kernel memory used to cache a block is called a buffer and described
     by a buf structure.  In addition to describing a cached block, a buf
     structure is also used to describe an I/O request as a part of the disk
     driver interface.


FUNCTIONS

     bread(vp, blkno, size, flags, bpp)
              Read a block corresponding to vp and blkno.  The buffer is
              returned via bpp.  The units of blkno are specifically the units
              used by the VOP_STRATEGY() routine for the vp vnode.  For device
              special files, blkno is in units of DEV_BSIZE and both blkno and
              size must be multiples of the underlying device's block size.
              For other files, blkno is in units chosen by the file system
              containing vp.

              If the buffer is not found (i.e. the block is not cached in mem-
              ory), bread() allocates a buffer with enough pages for size and
              reads the specified disk block into it.

              The buffer returned by bread() is marked as busy.  (The B_BUSY
              flag is set.)  After manipulation of the buffer returned from
              bread(), the caller should unbusy it so that another thread can
              get it.  If the buffer contents are modified and should be writ-
              ten back to disk, it should be unbusied using one of variants of
              bwrite().  Otherwise, it should be unbusied using brelse().

     breadn(vp, blkno, size, rablks, rasizes, nrablks, flags, bpp)
              Get a buffer as bread().  In addition, breadn() will start read-
              ahead of blocks specified by rablks, rasizes, nrablks.

     bwrite(bp)
              Write a block.  Start I/O for write using VOP_STRATEGY().  Then,
              unless the B_ASYNC flag is set in bp, bwrite() waits for the I/O
              to complete.

     bawrite(bp)
              Write a block asynchronously.  Set the B_ASYNC flag in bp and
              simply call VOP_BWRITE(), which results in bwrite() for most
              filesystems.

     bdwrite(bp)
              Delayed write.  Unlike bawrite(), bdwrite() won't start any I/O.
              It only marks the buffer as dirty (BO_DELWRI) and unbusy it.

     getblk(vp, blkno, size, slpflag, slptimeo)
              Get a block of requested size size that is associated with a
              given vnode and block offset, specified by vp and blkno.  If it
              is found in the block cache, make it busy and return it.  Other-
              wise, return an empty block of the correct size.  It is up to
              the caller to ensure that the cached blocks are of the correct
              size.

              If getblk() needs to sleep, slpflag and slptimeo are used as
              arguments for cv_timedwait().

     geteblk(size)
              Allocate an empty, disassociated block of a given size size.

     incore(vp, blkno)
              Determine if a block associated to a given vnode and block off-
              set is in the cache.  If it is there, return a pointer to it.
              Note that incore() doesn't busy the buffer unlike getblk().

     allocbuf(bp, size, preserve)
              Expand or contract the actual memory allocated to a buffer.  If
              preserve is zero, the entire data in the buffer will be lost.
              Otherwise, if the buffer shrinks, the truncated part of the data
              is lost, so it is up to the caller to have written it out first
              if needed; this routine will not start a write.  If the buffer
              grows, it is the callers responsibility to fill out the buffer's
              additional contents.

     brelse(bp, set)
              Unbusy a buffer and release it to the free lists.


CODE REFERENCES

     The buffer cache subsystem is implemented within the file
     sys/kern/vfs_bio.c.


SEE ALSO

     intro(9), vnode(9)

     Maurice J. Bach, The Design of the UNIX Operating System, Prentice Hall,
     1986.

     Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, and John S.
     Quarterman, The Design and Implementation of the 4.4BSD Operating System,
     Addison Wesley, 1996.

NetBSD 10.99                    April 11, 2017                    NetBSD 10.99