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

# NAME

`buffercache`, `bread`, `bread_cluster`, `breadn`, `bwrite`, `bawrite`, `bdwrite`, `getblk`, `geteblk`, `incore`, `brelse`, `biodone`, `biowait` — buffer cache interfaces

# SYNOPSIS

`#include <sys/buf.h>`

int
`bread`(struct vnode *vp, daddr_t blkno, int size, struct buf **bpp);

int
`bread_cluster`(struct vnode *vp, daddr_t blkno, int size, struct buf **bpp);

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

int
`bwrite`(struct buf *bp);

void
`bawrite`(struct buf *bp);

void
`bdwrite`(struct buf *bp);

struct buf *
`getblk`(struct vnode *vp, daddr_t blkno, int size, int slpflag, uint64_t slptimeo);

struct buf *
`geteblk`(size_t size);

struct buf *
`incore`(struct vnode *vp, daddr_t blkno);

void
`brelse`(struct buf *bp);

void
`biodone`(struct buf *bp);

int
`biowait`(struct buf *bp);

# DESCRIPTION

The `buffercache` interface is used by each filesystem 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.

The block size used for logical block numbers depends on the type of the given vnode. For file vnodes, this is f_iosize of the underlying filesystem. For block device vnodes, this will usually be DEV_BSIZE.

# FUNCTIONS

`bread`(vp, blkno, size, bpp)
  Read a block corresponding to vp and blkno. The buffer is returned via bpp.

  If the buffer is not found (i.e. the block is not cached in memory), `bread`() calls `getblk`() to allocate a buffer with enough pages for size and reads the specified disk block into it.

  `bread`() always returns a buffer, even if it returns an error due to an I/O error.

  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 the variants of `bwrite`(). Otherwise, it should be unbusied using `brelse`().

`breadn`(vp, blkno, size, rablks, rasizes, nrablks, bpp);
  Get a buffer as `bread`(). In addition, `breadn`() will start read-ahead of blocks specified by rablks, rasizes, and nrablks. The read-ahead blocks aren't returned, but are available in cache for future accesses.
`bread_cluster`(vp, blkno, size, bpp);
  Read a block of size size corresponding to vp and blkno, with readahead. If neither the first block nor a part of the next MAXBSIZE bytes is already in the buffer cache, `bread_cluster`() will perform a read-ahead of MAXBSIZE bytes in a single I/O operation. This is currently more efficient than `breadn`(). The read-ahead data isn't returned, but is available in cache for future access.
`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 (`B_DELWRI`) and unbusies it. This routine should be used when the buffer is expected to be modified again soon, typically a small write that partially fills a buffer.
`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, mark it as having been found, 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 tsleep_nsec(9).

`geteblk`(size)
  Allocate an empty, disassociated block of a given size size.
`incore`(vp, blkno)
  Determine if a block associated with a given vnode and block offset is in the cache. If it is there, return a pointer to it. Note that `incore`() doesn't mark the buffer as busy unlike `getblk`().
`brelse`(bp)
  Unlock a buffer by clearing the `B_AGE`, `B_ASYNC`, `B_BUSY`, `B_NOCACHE`, and `B_DEFERRED` flags and release it to the free lists.
`biodone`(bp)
  Mark I/O complete on a buffer. If a callback has been requested by `B_CALL`, do so. Otherwise, wake up the waiting processes.
`biowait`(bp)
  Wait for operations on the buffer to complete. When they do, extract and return the I/O's error value. If the operation on the buffer is being done via a direct call to a `strategy`() type function, then the buffer must be previously initialized with the `B_RAW` flag.

# CODE REFERENCES

This section describes places within the OpenBSD source tree where actual code implementing the buffer cache subsystem can be found. All pathnames are relative to /usr/src.

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

# SEE ALSO

intro(9), vnode(9), VOP_STRATEGY(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.

Leffler, et. al., The Design and Implementation of the 4.3 BSD Unix Operating System, Addison Wesley, 1989.

July 19, 2019 | Debian