lib/libc/db/man/mpool.3

   1 .\"     $NetBSD: mpool.3,v 1.10 2010/12/16 11:49:35 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   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 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)mpool.3     8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd December 16, 2010
  33 .Dt MPOOL 3
  34 .Os
  35 .Sh NAME
  36 .Nm mpool ,
  37 .Nm mpool_open ,
  38 .Nm mpool_filter ,
  39 .Nm mpool_new ,
  40 .Nm mpool_get ,
  41 .Nm mpool_put ,
  42 .Nm mpool_sync ,
  43 .Nm mpool_close
  44 .Nd shared memory buffer pool
  45 .Sh SYNOPSIS
  46 .In db.h
  47 .In mpool.h
  48 .Ft MPOOL *
  49 .Fn mpool_open "DBT *key" "int fd" "pgno_t pagesize" "pgno_t maxcache"
  50 .Ft void
  51 .Fn mpool_filter "MPOOL *mp" "void (*pgin)(void *, pgno_t, void *)" \
  52 "void (*pgout)(void *, pgno_t, void *)" "void *pgcookie"
  53 .Ft void *
  54 .Fn mpool_new "MPOOL *mp" "pgno_t *pgnoaddr"
  55 .Ft void *
  56 .Fn mpool_get "MPOOL *mp" "pgno_t pgno" "u_int flags"
  57 .Ft int
  58 .Fn mpool_put "MPOOL *mp" "void *pgaddr" "u_int flags"
  59 .Ft int
  60 .Fn mpool_sync "MPOOL *mp"
  61 .Ft int
  62 .Fn mpool_close "MPOOL *mp"
  63 .Sh DESCRIPTION
  64 .Nm
  65 is the library interface intended to provide page oriented buffer
  66 management of files.
  67 The buffers may be shared between processes.
  68 .Pp
  69 The function
  70 .Fn mpool_open
  71 initializes a memory pool.
  72 The
  73 .Fa key
  74 argument is the byte string used to negotiate between multiple
  75 processes wishing to share buffers.
  76 If the file buffers are mapped in shared memory, all processes using
  77 the same key will share the buffers.
  78 If
  79 .Fa key
  80 is
  81 .Dv NULL ,
  82 the buffers are mapped into private memory.
  83 The
  84 .Fa fd
  85 argument is a file descriptor for the underlying file, which must be
  86 seekable.
  87 If
  88 .Fa key
  89 is
  90 .No non- Ns Dv NULL
  91 and matches a file already being mapped, the
  92 .Fa fd
  93 argument is ignored.
  94 .Pp
  95 The
  96 .Fa pagesize
  97 argument is the size, in bytes, of the pages into which the file is
  98 broken up.
  99 The
 100 .Fa maxcache
 101 argument is the maximum number of pages from the underlying file to
 102 cache at any one time.
 103 This value is not relative to the number of processes which share a
 104 file's buffers, but will be the largest value specified by any of the
 105 processes sharing the file.
 106 .Pp
 107 The
 108 .Fn mpool_filter
 109 function is intended to make transparent input and output processing
 110 of the pages possible.
 111 If the
 112 .Fa pgin
 113 function is specified, it is called each time a buffer is read into
 114 the memory pool from the backing file.
 115 If the
 116 .Fa pgout
 117 function is specified, it is called each time a buffer is written into
 118 the backing file.
 119 Both functions are are called with the
 120 .Fa pgcookie
 121 pointer, the page number and a pointer to the page to being read or
 122 written.
 123 .Pp
 124 The function
 125 .Fn mpool_new
 126 takes an MPOOL pointer and an address as arguments.
 127 If a new page can be allocated, a pointer to the page is returned and
 128 the page number is stored into the
 129 .Fa pgnoaddr
 130 address.
 131 Otherwise,
 132 .Dv NULL
 133 is returned and errno is set.
 134 .Pp
 135 The function
 136 .Fn mpool_get
 137 takes a MPOOL pointer and a page number as arguments.
 138 If the page exists, a pointer to the page is returned.
 139 Otherwise,
 140 .Dv NULL
 141 is returned and errno is set.
 142 The flags parameter is not currently used.
 143 .Pp
 144 The function
 145 .Fn mpool_put
 146 unpins the page referenced by
 147 .Fa pgaddr .
 148 .Fa pgaddr
 149 must be an address previously returned by
 150 .Fn mpool_get
 151 or
 152 .Fn mpool_new .
 153 The flag value is specified by or'ing any of the following values:
 154 .Bl -tag -width MPOOL_DIRTYX -offset indent
 155 .It Dv MPOOL_DIRTY
 156 The page has been modified and needs to be written to the backing
 157 file.
 158 .El
 159 .Pp
 160 .Fn mpool_put
 161 returns 0 on success and \-1 if an error occurs.
 162 .Pp
 163 The function
 164 .Fn mpool_sync
 165 writes all modified pages associated with the MPOOL pointer to the
 166 backing file.
 167 .Fn mpool_sync
 168 returns 0 on success and \-1 if an error occurs.
 169 .Pp
 170 The
 171 .Fn mpool_close
 172 function frees up any allocated memory associated with the memory pool
 173 cookie.
 174 Modified pages are
 175 .Em not
 176 written to the backing file.
 177 .Fn mpool_close
 178 returns 0 on success and \-1 if an error occurs.
 179 .Sh ERRORS
 180 The
 181 .Fn mpool_open
 182 function may fail and set
 183 .Va errno
 184 for any of the errors specified for the library routine
 185 .Xr malloc 3 .
 186 .Pp
 187 The
 188 .Fn mpool_get
 189 function may fail and set
 190 .Va errno
 191 for the following:
 192 .Bl -tag -width Er -offset indent
 193 .It Er EINVAL
 194 The requested record doesn't exist.
 195 .El
 196 .Pp
 197 The
 198 .Fn mpool_new
 199 and
 200 .Fn mpool_get
 201 functions may fail and set
 202 .Va errno
 203 for any of the errors specified for the library routines
 204 .Xr read 2 ,
 205 .Xr write 2 ,
 206 and
 207 .Xr malloc 3 .
 208 .Pp
 209 The
 210 .Fn mpool_sync
 211 function may fail and set
 212 .Va errno
 213 for any of the errors specified for the library routine
 214 .Xr write 2 .
 215 .Pp
 216 The
 217 .Fn mpool_close
 218 function may fail and set
 219 .Va errno
 220 for any of the errors specified for the library routine
 221 .Xr free 3 .
 222 .Sh SEE ALSO
 223 .Xr btree 3 ,
 224 .Xr dbopen 3 ,
 225 .Xr hash 3 ,
 226 .Xr recno 3