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