1.\" Copyright (c) 2005 The DragonFly Project. All rights reserved. 2.\" 3.\" This code is derived from software contributed to The DragonFly Project 4.\" by Hiten Pandya <hmp@dragonflybsd.org>. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 3. Neither the name of The DragonFly Project nor the names of its 17.\" contributors may be used to endorse or promote products derived 18.\" from this software without specific, prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" $DragonFly: src/share/man/man9/bufcache.9,v 1.5 2007/11/23 23:03:57 swildner Exp $ 34.\" 35.Dd July 29, 2005 36.Os 37.Dt BUFCACHE 9 38.Sh NAME 39.Nm bufinit , 40.Nm bread , 41.Nm bwrite 42.Nd Buffer Cache Functions 43.Sh SYNOPSIS 44.In sys/param.h 45.In sys/systm.h 46.In sys/buf.h 47.In sys/buf2.h 48.Ft int 49.Fo bread 50.Fa "struct vnode *vp" 51.Fa "daddr_t blkno" 52.Fa "int size" 53.Fa "struct buf **bpp" 54.Fc 55.Ft int 56.Fo bwrite 57.Fa "struct buf *bp" 58.Fc 59.Sh DESCRIPTION 60The buffer cache functions are at the heart of all storage file systems; 61they are used for reading from and writing to the underlying storage. 62The 63.Fn bread 64and 65.Fn bwrite 66functions observe most activity in the kernel from file systems, but other 67functions such as 68.Fn breadn 69are also used. 70.Pp 71At boot time, the 72.Fn bufinit 73function is invoked to initialize various accounting code. 74It also initializes 75.Va nbuf 76number of buffers and inserts them into the empty queue 77.Dv BQUEUE_EMPTY . 78The variable 79.Va nbuf 80is a global variable in the kernel that is tunable at boot time using 81the 82.Xr loader 8 . 83.Sh FUNCTIONS 84.Bl -tag -width compact 85.It Fn bread "*vp" "blkno" "size" "**bpp" 86Retrieve a buffer with specified data. 87An internal function, 88.Fn getblk 89is called to check whether the data is available in cache or if it 90should be read from the 91.Fa vp . 92If the data is available in cache, the 93.Dv B_CACHE 94flag will be set otherwise 95.Fa size 96bytes will be read starting at block number 97.Fa blkno 98from the block special device vnode 99.Fa vp . 100.Pp 101In case when the buffer is not in cache or not cacheable this 102function will put the calling process or thread to sleep, using 103.Fa bp 104as the wait channel and 105.Ql "biord" 106as the wait message. 107.Pp 108On successful return, the 109.Va b_data 110field of 111.Fa bp 112will point to valid data address and 113.Va b_count 114will contain the number of bytes read. 115.It Fn bwrite "*bp" 116Write a buffer back to the device pointed to by 117.Va b_dev 118field. 119Until the write operation is complete, the calling thread or 120process will be put to sleep by the kernel using 121.Fa bp 122as the wait channel and 123.Ql "biowr" 124as the wait message. 125.Pp 126Before calling this function, the following fields are the least 127to be set: 128.Bl -tag -width compact 129.It Va b_data 130This field should be set to a valid data buffer to be written by 131.Fn bwrite . 132.It Va b_bcount 133Size of buffer to be written, analogous to the 134.Fa size 135argument of 136.Fn bread . 137.It Va b_blkno 138Logical block number at which the buffer should be written. 139.It Va b_dev 140This can be set by using the 141.Fn vn_todev 142function on the device vnode. 143.It Va b_vp 144This should be set to the vnode of the device to which the buffer 145will be written. 146.El 147.Pp 148This function will put the calling process or thread to sleep if the 149data cannot be written when operating synchronously, using 150.Fa bp 151as the wait channel and 152.Ql "biowr" 153as the wait message. 154On successful return the 155.Va b_resid 156field of 157.Fa bp 158will be set to the value zero, thus indicating a successful write. 159.El 160.Sh CODE REFERENCES 161The file system code, located under 162.Pa sys/vfs 163directory are the main source of reference. 164.Sh SEE ALSO 165.Xr buf 9 , 166.Xr namei 9 , 167.Xr VFS 9 168.Sh AUTHORS 169This manual page was written by 170.An Hiten Pandya Aq hmp@freebsd.org . 171