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.Dd December 27, 2018 34.Dt BUFCACHE 9 35.Os 36.Sh NAME 37.Nm bufinit , 38.Nm bread , 39.Nm bwrite 40.Nd Buffer Cache Functions 41.Sh SYNOPSIS 42.In sys/param.h 43.In sys/systm.h 44.In sys/buf.h 45.In sys/buf2.h 46.Ft int 47.Fo bread 48.Fa "struct vnode *vp" 49.Fa "off_t loffset" 50.Fa "int size" 51.Fa "struct buf **bpp" 52.Fc 53.Ft int 54.Fo bwrite 55.Fa "struct buf *bp" 56.Fc 57.Sh DESCRIPTION 58The buffer cache functions are at the heart of all storage file systems; 59they are used for reading from and writing to the underlying storage. 60The 61.Fn bread 62and 63.Fn bwrite 64functions observe most activity in the kernel from file systems, but other 65functions such as 66.Fn breadn 67are also used. 68.Pp 69At boot time, the 70.Fn bufinit 71function is invoked to initialize various accounting code. 72It also initializes 73.Va nbuf 74number of buffers and inserts them into the empty queue 75.Dv BQUEUE_EMPTY . 76The variable 77.Va nbuf 78is a global variable in the kernel that is tunable at boot time using 79the 80.Xr loader 8 . 81.Sh FUNCTIONS 82.Bl -tag -width compact 83.It Fn bread "*vp" "loffset" "size" "**bpp" 84Retrieve a buffer with specified data. 85An internal function, 86.Fn getblk 87is called to check whether the data is available in cache or if it 88should be read from the 89.Fa vp . 90If the data is available in cache, the 91.Dv B_CACHE 92flag will be set otherwise 93.Fa size 94bytes will be read starting at block number 95.Fa loffset 96from the block special device vnode 97.Fa vp . 98.Pp 99In case when the buffer is not in cache or not cacheable this 100function will put the calling process or thread to sleep, using 101.Fa bp 102as the wait channel and 103.Ql "biord" 104as the wait message. 105.Pp 106On successful return, the 107.Va b_data 108field of 109.Fa bp 110will point to valid data address and 111.Va b_count 112will contain the number of bytes read. 113.It Fn bwrite "*bp" 114Write a buffer back to the device pointed to by 115.Va b_dev 116field. 117Until the write operation is complete, the calling thread or 118process will be put to sleep by the kernel using 119.Fa bp 120as the wait channel and 121.Ql "biowr" 122as the wait message. 123.Pp 124Before calling this function, the following fields are the least 125to be set: 126.Bl -tag -width compact 127.It Va b_data 128This field should be set to a valid data buffer to be written by 129.Fn bwrite . 130.It Va b_bcount 131Size of buffer to be written, analogous to the 132.Fa size 133argument of 134.Fn bread . 135.It Va b_blkno 136Logical block number at which the buffer should be written. 137.It Va b_dev 138This can be set by using the 139.Fn vn_todev 140function on the device vnode. 141.It Va b_vp 142This should be set to the vnode of the device to which the buffer 143will be written. 144.El 145.Pp 146This function will put the calling process or thread to sleep if the 147data cannot be written when operating synchronously, using 148.Fa bp 149as the wait channel and 150.Ql "biowr" 151as the wait message. 152On successful return the 153.Va b_resid 154field of 155.Fa bp 156will be set to the value zero, thus indicating a successful write. 157.El 158.Sh CODE REFERENCES 159The file system code, located under 160.Pa sys/vfs 161directory are the main source of reference. 162.Sh SEE ALSO 163.Xr buf 9 , 164.Xr VFS 9 165.Sh AUTHORS 166This manual page was written by 167.An Hiten Pandya Aq Mt hmp@freebsd.org . 168