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.\" 30.Dd June 17, 2011 31.Dt MPOOL 3 32.Os 33.Sh NAME 34.Nm mpool 35.Nd "shared memory buffer pool" 36.Sh SYNOPSIS 37.In db.h 38.In mpool.h 39.Ft MPOOL * 40.Fn mpool_open "void *key" "int fd" "pgno_t pagesize" "pgno_t maxcache" 41.Ft void 42.Fo mpool_filter 43.Fa "MPOOL *mp" 44.Fa "void (*pgin)(void *, pgno_t, void *)" 45.Fa "void (*pgout)(void *, pgno_t, void *)" 46.Fa "void *pgcookie" 47.Fc 48.Ft void * 49.Fn mpool_new "MPOOL *mp" "pgno_t *pgnoaddr" "u_int flags" 50.Ft int 51.Fn mpool_delete "MPOOL *mp" "void *page" 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. 65.Pp 66The 67.Fn mpool_open 68function initializes a memory pool. 69The 70.Fa key 71argument is currently ignored. 72The 73.Fa fd 74argument is a file descriptor for the underlying file, which must be seekable. 75.Pp 76The 77.Fa pagesize 78argument is the size, in bytes, of the pages into which the file is broken up. 79The 80.Fa maxcache 81argument is the maximum number of pages from the underlying file to cache 82at any one time. 83This value is not relative to the number of processes which share a file's 84buffers, but will be the largest value specified by any of the processes 85sharing the file. 86.Pp 87The 88.Fn mpool_filter 89function is intended to make transparent input and output processing of the 90pages possible. 91If the 92.Fa pgin 93function is specified, it is called each time a buffer is read into the memory 94pool from the backing file. 95If the 96.Fa pgout 97function is specified, it is called each time a buffer is written into the 98backing file. 99Both functions are called with the 100.Fa pgcookie 101pointer, the page number and a pointer to the page to being read or written. 102.Pp 103The function 104.Fn mpool_new 105takes an 106.Dv MPOOL 107pointer, an address, and a set of flags as arguments. 108If a new page can be allocated, a pointer to the page is returned and 109the page number is stored into the 110.Fa pgnoaddr 111address. 112Otherwise, 113.Dv NULL 114is returned and 115.Va errno 116is set. 117The flags value is formed by 118.Tn OR Ns 'ing 119the following values: 120.Bl -tag -width Ds 121.It Dv MPOOL_PAGE_REQUEST 122Allocate a new page with a specific page number. 123.It Dv MPOOL_PAGE_NEXT 124Allocate a new page with the next page number. 125.El 126.Pp 127The function 128.Fn mpool_delete 129deletes the specified page from a pool and frees the page. 130It takes an 131.Dv MPOOL 132pointer and a page as arguments. 133The page must have been generated by 134.Fn mpool_new . 135.Pp 136The 137.Fn mpool_get 138function takes 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 specified by 150.Em or Ns 'ing 151any of the following values: 152.Bl -tag -width indent 153.It Dv MPOOL_IGNOREPIN 154The page returned is not pinned; 155page will otherwise be pinned on return. 156.El 157.Pp 158The 159.Fn mpool_put 160function unpins the page referenced by 161.Fa pgaddr . 162The 163.Fa pgaddr 164argument 165must be an address previously returned by 166.Fn mpool_get 167or 168.Fn mpool_new . 169The 170.Fa flags 171argument is specified by 172.Em or Ns 'ing 173any of the following values: 174.Bl -tag -width indent 175.It Dv MPOOL_DIRTY 176The page has been modified and needs to be written to the backing file. 177.El 178.Pp 179The 180.Fn mpool_put 181function 182returns 0 on success and -1 if an error occurs. 183.Pp 184The 185.Fn mpool_sync 186function writes all modified pages associated with the 187.Ft MPOOL 188pointer to the 189backing file. 190The 191.Fn mpool_sync 192function 193returns 0 on success and -1 if an error occurs. 194.Pp 195The 196.Fn mpool_close 197function free's up any allocated memory associated with the memory pool 198cookie. 199Modified pages are 200.Em not 201written to the backing file. 202The 203.Fn mpool_close 204function 205returns 0 on success and -1 if an error occurs. 206.Sh ERRORS 207The 208.Fn mpool_open 209function may fail and set 210.Va errno 211for any of the errors specified for the library routine 212.Xr malloc 3 . 213.Pp 214The 215.Fn mpool_get 216function may fail and set 217.Va errno 218for the following: 219.Bl -tag -width Er 220.It Bq Er EINVAL 221The requested record does not exist. 222.El 223.Pp 224The 225.Fn mpool_new 226and 227.Fn mpool_get 228functions may fail and set 229.Va errno 230for any of the errors specified for the library routines 231.Xr read 2 , 232.Xr write 2 , 233and 234.Xr malloc 3 . 235.Pp 236The 237.Fn mpool_sync 238function may fail and set 239.Va errno 240for any of the errors specified for the library routine 241.Xr write 2 . 242.Pp 243The 244.Fn mpool_close 245function may fail and set 246.Va errno 247for any of the errors specified for the library routine 248.Xr free 3 . 249.Sh SEE ALSO 250.Xr btree 3 , 251.Xr dbopen 3 , 252.Xr hash 3 , 253.Xr recno 3 254