share/man/man9/bufcache.9

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