| .\" Copyright (c) 1990, 1993 |
| .\" The Regents of the University of California. All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 |
| .\" |
| .TH MPOOL 3 2021-03-22 "" "Linux Programmer's Manual" |
| .UC 7 |
| .SH NAME |
| mpool \- shared memory buffer pool |
| .SH SYNOPSIS |
| .nf |
| .B #include <db.h> |
| .B #include <mpool.h> |
| .PP |
| .BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \ |
| ", pgno_t " maxcache ); |
| .PP |
| .BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *)," |
| .BI " void (*" pgout ")(void *, pgno_t, void *)," |
| .BI " void *" pgcookie ); |
| .PP |
| .BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr ); |
| .BI "void *mpool_get(MPOOL *" mp ", pgno_t " pgno ", unsigned int " flags ); |
| .BI "int mpool_put(MPOOL *" mp ", void *" pgaddr ", unsigned int " flags ); |
| .PP |
| .BI "int mpool_sync(MPOOL *" mp ); |
| .BI "int mpool_close(MPOOL *" mp ); |
| .fi |
| .SH DESCRIPTION |
| .IR "Note well" : |
| This page documents interfaces provided in glibc up until version 2.1. |
| Since version 2.2, glibc no longer provides these interfaces. |
| Probably, you are looking for the APIs provided by the |
| .I libdb |
| library instead. |
| .PP |
| .I Mpool |
| is the library interface intended to provide page oriented buffer management |
| of files. |
| The buffers may be shared between processes. |
| .PP |
| The function |
| .BR mpool_open () |
| initializes a memory pool. |
| The |
| .I key |
| argument is the byte string used to negotiate between multiple |
| processes wishing to share buffers. |
| If the file buffers are mapped in shared memory, all processes using |
| the same key will share the buffers. |
| If |
| .I key |
| is NULL, the buffers are mapped into private memory. |
| The |
| .I fd |
| argument is a file descriptor for the underlying file, which must be seekable. |
| If |
| .I key |
| is non-NULL and matches a file already being mapped, the |
| .I fd |
| argument is ignored. |
| .PP |
| The |
| .I pagesize |
| argument is the size, in bytes, of the pages into which the file is broken up. |
| The |
| .I maxcache |
| argument is the maximum number of pages from the underlying file to cache |
| at any one time. |
| This value is not relative to the number of processes which share a file's |
| buffers, but will be the largest value specified by any of the processes |
| sharing the file. |
| .PP |
| The |
| .BR mpool_filter () |
| function is intended to make transparent input and output processing of the |
| pages possible. |
| If the |
| .I pgin |
| function is specified, it is called each time a buffer is read into the memory |
| pool from the backing file. |
| If the |
| .I pgout |
| function is specified, it is called each time a buffer is written into the |
| backing file. |
| Both functions are called with the |
| .I pgcookie |
| pointer, the page number and a pointer to the page to being read or written. |
| .PP |
| The function |
| .BR mpool_new () |
| takes an |
| .I MPOOL |
| pointer and an address as arguments. |
| If a new page can be allocated, a pointer to the page is returned and |
| the page number is stored into the |
| .I pgnoaddr |
| address. |
| Otherwise, NULL is returned and |
| .I errno |
| is set. |
| .PP |
| The function |
| .BR mpool_get () |
| takes an |
| .I MPOOL |
| pointer and a page number as arguments. |
| If the page exists, a pointer to the page is returned. |
| Otherwise, NULL is returned and |
| .I errno |
| is set. |
| The |
| .I flags |
| argument is not currently used. |
| .PP |
| The function |
| .BR mpool_put () |
| unpins the page referenced by |
| .IR pgaddr . |
| .I pgaddr |
| must be an address previously returned by |
| .BR mpool_get () |
| or |
| .BR mpool_new (). |
| The flag value is specified by ORing |
| any of the following values: |
| .TP |
| .B MPOOL_DIRTY |
| The page has been modified and needs to be written to the backing file. |
| .PP |
| .BR mpool_put () |
| returns 0 on success and \-1 if an error occurs. |
| .PP |
| The function |
| .BR mpool_sync () |
| writes all modified pages associated with the |
| .I MPOOL |
| pointer to the |
| backing file. |
| .BR mpool_sync () |
| returns 0 on success and \-1 if an error occurs. |
| .PP |
| The |
| .BR mpool_close () |
| function free's up any allocated memory associated with the memory pool |
| cookie. |
| Modified pages are |
| .B not |
| written to the backing file. |
| .BR mpool_close () |
| returns 0 on success and \-1 if an error occurs. |
| .SH ERRORS |
| The |
| .BR mpool_open () |
| function may fail and set |
| .I errno |
| for any of the errors specified for the library routine |
| .BR malloc (3). |
| .PP |
| The |
| .BR mpool_get () |
| function may fail and set |
| .I errno |
| for the following: |
| .TP 15 |
| .B EINVAL |
| The requested record doesn't exist. |
| .PP |
| The |
| .BR mpool_new () |
| and |
| .BR mpool_get () |
| functions may fail and set |
| .I errno |
| for any of the errors specified for the library routines |
| .BR read (2), |
| .BR write (2), |
| and |
| .BR malloc (3). |
| .PP |
| The |
| .BR mpool_sync () |
| function may fail and set |
| .I errno |
| for any of the errors specified for the library routine |
| .BR write (2). |
| .PP |
| The |
| .BR mpool_close () |
| function may fail and set |
| .I errno |
| for any of the errors specified for the library routine |
| .BR free (3). |
| .SH CONFORMING TO |
| Not in POSIX.1. |
| Present on the BSDs. |
| .SH SEE ALSO |
| .BR btree (3), |
| .BR dbopen (3), |
| .BR hash (3), |
| .BR recno (3) |