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