BUFCACHE(9)

NAME
bufinit, bread, bwrite - Buffer Cache Functions

SYNOPSIS
#include <sys/param.h>
#include <sys/systm.h>
#include <sys/buf.h>
#include <sys/buf2.h>
int
bread(struct vnode *vp, off_t loffset, int size, struct buf **bpp);
int
bwrite(struct buf *bp);

DESCRIPTION
The buffer cache functions are at the heart of all storage file systems; they are used for reading from and writing to the underlying storage. The bread() and bwrite() functions observe most activity in the kernel from file systems, but other functions such as breadn() are also used.

At boot time, the bufinit() function is invoked to initialize various accounting code. It also initializes nbuf number of buffers and inserts them into the empty queue BQUEUE_EMPTY. The variable nbuf is a global variable in the kernel that is tunable at boot time using the loader(8).

FUNCTIONS

bread(*vp, loffset, size, **bpp)
    Retrieve a buffer with specified data. An internal function, getblk() is called to check whether the data is available in cache or if it should be read from the vp. If the data is available in cache, the B_CACHE flag will be set otherwise size bytes will be read starting at block number loffset from the block special device vnode vp.

    In case when the buffer is not in cache or not cacheable this function will put the calling process or thread to sleep, using bp as the wait channel and ‘biord’ as the wait message.

    On successful return, the b_data field of bp will point to valid data address and b_count will contain the number of bytes read.

bwrite(*bp)
    Write a buffer back to the device pointed to by b_dev field. Until the write operation is complete, the calling thread or process will be put to sleep by the kernel using bp as the wait channel and ‘biowr’ as the wait message.

    Before calling this function, the following fields are the least to be set:

    b_data
        This field should be set to a valid data buffer to be written by bwrite().

    b_bcount
        Size of buffer to be written, analogous to the size argument of bread().

    b_blkno
        Logical block number at which the buffer should be written.

    b_dev
        This can be set by using the vn_todev() function on the device vnode.

    b_vp
        This should be set to the vnode of the device to which the buffer will be written.

    This function will put the calling process or thread to sleep if the data cannot be written when operating synchronously, using bp as the wait channel and ‘biowr’ as the wait message. On successful return the b_resid field of bp will be set to the value zero, thus indicating a successful write.

CODE REFERENCES
The file system code, located under sys/vfs directory are the main source of reference.

SEE ALSO
buf(9), VFS(9)

AUTHORS
This manual page was written by Hiten Pandya <hmp@freebsd.org>.