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$ 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.Fd "#include <db.h>" 43.Fd "#include <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.Nm Mpool 65is the library interface intended to provide page oriented buffer management 66of files. 67The buffers may be shared between processes. 68.Pp 69The function 70.Fn mpool_open 71initializes a memory pool. 72The 73.Fa key 74argument is the byte string used to negotiate between multiple 75processes wishing to share buffers. 76If the file buffers are mapped in shared memory, all processes using 77the same key will share the buffers. 78If 79.Fa key 80is 81.Dv NULL , 82the buffers are mapped into private memory. 83The 84.Fa fd 85argument is a file descriptor for the underlying file, which must be seekable. 86If 87.Fa key 88is 89.No non\- Ns Dv NULL 90and matches a file already being mapped, the 91.Fa fd 92argument is ignored. 93.Pp 94The 95.Fa pagesize 96argument is the size, in bytes, of the pages into which the file is broken up. 97The 98.Fa maxcache 99argument is the maximum number of pages from the underlying file to cache 100at any one time. 101This value is not relative to the number of processes which share a file's 102buffers, but will be the largest value specified by any of the processes 103sharing the file. 104.Pp 105The 106.Fn mpool_filter 107function is intended to make transparent input and output processing of the 108pages possible. 109If the 110.Fa pgin 111function is specified, it is called each time a buffer is read into the memory 112pool from the backing file. 113If the 114.Fa pgout 115function is specified, it is called each time a buffer is written into the 116backing file. 117Both functions are called with the 118.Fa pgcookie 119pointer, the page number and a pointer to the page to being read or written. 120.Pp 121The function 122.Fn mpool_new 123takes an 124.Ft MPOOL 125pointer and an address as arguments. 126If a new page can be allocated, a pointer to the page is returned and 127the page number is stored into the 128.Fa pgnoaddr 129address. 130Otherwise, 131.Dv NULL 132is returned and 133.Va errno 134is set. 135.Pp 136The function 137.Fn mpool_get 138takes a 139.Ft MPOOL 140pointer and a page number as arguments. 141If the page exists, a pointer to the page is returned. 142Otherwise, 143.Dv NULL 144is returned and 145.Va errno 146is set. 147The 148.Fa flags 149parameter is not currently used. 150.Pp 151The function 152.Fn mpool_put 153unpins the page referenced by 154.Fa pgaddr . 155.Fa Pgaddr 156must be an address previously returned by 157.Fn mpool_get 158or 159.Fn mpool_new . 160The 161.Fa flags 162value is specified by 163.Em or Ns 'ing 164any of the following values: 165.Bl -tag -width indent 166.It Dv MPOOL_DIRTY 167The page has been modified and needs to be written to the backing file. 168.El 169.Pp 170.Fn Mpool_put 171returns 0 on success and -1 if an error occurs. 172.Pp 173The function 174.Fn mpool_sync 175writes all modified pages associated with the 176.Ft MPOOL 177pointer to the 178backing file. 179.Fn Mpool_sync 180returns 0 on success and -1 if an error occurs. 181.Pp 182The 183.Fn mpool_close 184function free's up any allocated memory associated with the memory pool 185cookie. 186Modified pages are 187.Em not 188written to the backing file. 189.Fn Mpool_close 190returns 0 on success and -1 if an error occurs. 191.Sh ERRORS 192The 193.Fn mpool_open 194function may fail and set 195.Va errno 196for any of the errors specified for the library routine 197.Xr malloc 3 . 198.Pp 199The 200.Fn mpool_get 201function may fail and set 202.Va errno 203for the following: 204.Bl -tag -width Er 205.It Bq Er EINVAL 206The requested record doesn't exist. 207.El 208.Pp 209The 210.Fn mpool_new 211and 212.Fn mpool_get 213functions may fail and set 214.Va errno 215for any of the errors specified for the library routines 216.Xr read 2 , 217.Xr write 2 , 218and 219.Xr malloc 3 . 220.Pp 221The 222.Fn mpool_sync 223function may fail and set 224.Va errno 225for any of the errors specified for the library routine 226.Xr write 2 . 227.Pp 228The 229.Fn mpool_close 230function may fail and set 231.Va errno 232for any of the errors specified for the library routine 233.Xr free 3 . 234.Sh SEE ALSO 235.Xr btree 3 , 236.Xr dbopen 3 , 237.Xr hash 3 , 238.Xr recno 3 239