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.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.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 149argument is not currently used. 150.Pp 151The function 152.Fn mpool_put 153unpins the page referenced by 154.Fa pgaddr . 155The 156.Fa pgaddr 157argument 158must be an address previously returned by 159.Fn mpool_get 160or 161.Fn mpool_new . 162The 163.Fa flags 164argument is specified by 165.Em or Ns 'ing 166any of the following values: 167.Bl -tag -width indent 168.It Dv MPOOL_DIRTY 169The page has been modified and needs to be written to the backing file. 170.El 171.Pp 172The 173.Fn mpool_put 174function 175returns 0 on success and -1 if an error occurs. 176.Pp 177The function 178.Fn mpool_sync 179writes all modified pages associated with the 180.Ft MPOOL 181pointer to the 182backing file. 183The 184.Fn mpool_sync 185function 186returns 0 on success and -1 if an error occurs. 187.Pp 188The 189.Fn mpool_close 190function free's up any allocated memory associated with the memory pool 191cookie. 192Modified pages are 193.Em not 194written to the backing file. 195The 196.Fn mpool_close 197function 198returns 0 on success and -1 if an error occurs. 199.Sh ERRORS 200The 201.Fn mpool_open 202function may fail and set 203.Va errno 204for any of the errors specified for the library routine 205.Xr malloc 3 . 206.Pp 207The 208.Fn mpool_get 209function may fail and set 210.Va errno 211for the following: 212.Bl -tag -width Er 213.It Bq Er EINVAL 214The requested record doesn't exist. 215.El 216.Pp 217The 218.Fn mpool_new 219and 220.Fn mpool_get 221functions may fail and set 222.Va errno 223for any of the errors specified for the library routines 224.Xr read 2 , 225.Xr write 2 , 226and 227.Xr malloc 3 . 228.Pp 229The 230.Fn mpool_sync 231function may fail and set 232.Va errno 233for any of the errors specified for the library routine 234.Xr write 2 . 235.Pp 236The 237.Fn mpool_close 238function may fail and set 239.Va errno 240for any of the errors specified for the library routine 241.Xr free 3 . 242.Sh SEE ALSO 243.Xr btree 3 , 244.Xr dbopen 3 , 245.Xr hash 3 , 246.Xr recno 3 247