--- name: "mpool" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/mpool" --- # mpool(3) shared memory buffer pool ## NAME **mpool** – shared memory buffer pool ## SYNOPSIS **#include \** **#include \** *MPOOL* *\**\ **mpool\_open**(*void \*key*, *int fd*, *pgno\_t pagesize*, *pgno\_t maxcache*); *void*\ **mpool\_filter**(*MPOOL \*mp*, *void (\*pgin)(void \*, pgno\_t, void \*)*, *void (\*pgout)(void \*, pgno\_t, void \*)*, *void \*pgcookie*); *void* *\**\ **mpool\_new**(*MPOOL \*mp*, *pgno\_t \*pgnoaddr*, *u\_int flags*); *int*\ **mpool\_delete**(*MPOOL \*mp*, *void \*page*); *void* *\**\ **mpool\_get**(*MPOOL \*mp*, *pgno\_t pgno*, *u\_int flags*); *int*\ **mpool\_put**(*MPOOL \*mp*, *void \*pgaddr*, *u\_int flags*); *int*\ **mpool\_sync**(*MPOOL \*mp*); *int*\ **mpool\_close**(*MPOOL \*mp*); ## DESCRIPTION The **mpool** library interface is intended to provide page oriented buffer management of files. The **mpool\_open**() function initializes a memory pool. The *key* argument is currently ignored. The *fd* argument is a file descriptor for the underlying file, which must be seekable. The *pagesize* argument is the size, in bytes, of the pages into which the file is broken up. The *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. The **mpool\_filter**() function is intended to make transparent input and output processing of the pages possible. If the *pgin* function is specified, it is called each time a buffer is read into the memory pool from the backing file. If the *pgout* function is specified, it is called each time a buffer is written into the backing file. Both functions are called with the *pgcookie* pointer, the page number and a pointer to the page to being read or written. The function **mpool\_new**() takes an MPOOL pointer, an address, and a set of flags as arguments. If a new page can be allocated, a pointer to the page is returned and the page number is stored into the *pgnoaddr* address. Otherwise, NULL is returned and *errno* is set. The flags value is formed by OR'ing the following values: - MPOOL\_PAGE\_REQUEST Allocate a new page with a specific page number. - MPOOL\_PAGE\_NEXT Allocate a new page with the next page number. The function **mpool\_delete**() deletes the specified page from a pool and frees the page. It takes an MPOOL pointer and a page as arguments. The page must have been generated by **mpool\_new**(). The **mpool\_get**() function takes a *MPOOL* pointer and a page number as arguments. If the page exists, a pointer to the page is returned. Otherwise, NULL is returned and *errno* is set. The *flags* argument is specified by *or*'ing any of the following values: - MPOOL\_IGNOREPIN The page returned is not pinned; page will otherwise be pinned on return. The **mpool\_put**() function unpins the page referenced by *pgaddr*. The *pgaddr* argument must be an address previously returned by **mpool\_get**() or **mpool\_new**(). The *flags* argument is specified by *or*'ing any of the following values: - MPOOL\_DIRTY The page has been modified and needs to be written to the backing file. The **mpool\_put**() function returns 0 on success and -1 if an error occurs. The **mpool\_sync**() function writes all modified pages associated with the *MPOOL* pointer to the backing file. The **mpool\_sync**() function returns 0 on success and -1 if an error occurs. The **mpool\_close**() function free's up any allocated memory associated with the memory pool cookie. Modified pages are *not* written to the backing file. The **mpool\_close**() function returns 0 on success and -1 if an error occurs. ## ERRORS The **mpool\_open**() function may fail and set *errno* for any of the errors specified for the library routine [malloc(3)](/malloc/3.md). The **mpool\_get**() function may fail and set *errno* for the following: - \[EINVAL\] The requested record does not exist. The **mpool\_new**() and **mpool\_get**() functions may fail and set *errno* for any of the errors specified for the library routines [read(2)](/read/2.md), [write(2)](/write/2.md), and [malloc(3)](/malloc/3.md). The **mpool\_sync**() function may fail and set *errno* for any of the errors specified for the library routine [write(2)](/write/2.md). The **mpool\_close**() function may fail and set *errno* for any of the errors specified for the library routine [free(3)](/free/3.md). ## SEE ALSO [btree(3)](/btree/3.md), [dbopen(3)](/dbopen/3.md), [hash(3)](/hash/3.md), [recno(3)](/recno/3.md)