BUFFERCACHE(9) | 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 performance 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 memory), `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 written 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. Otherwise, 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 offset 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.

April 11, 2017 | NetBSD 9.5