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