diff options
Diffstat (limited to 'lib/libc/db/man/mpool.3')
| -rw-r--r-- | lib/libc/db/man/mpool.3 | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/lib/libc/db/man/mpool.3 b/lib/libc/db/man/mpool.3 new file mode 100644 index 0000000..5af7d27 --- /dev/null +++ b/lib/libc/db/man/mpool.3 @@ -0,0 +1,254 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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. +.\" 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. +.\" +.\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 17, 2011 +.Dt MPOOL 3 +.Os +.Sh NAME +.Nm mpool +.Nd "shared memory buffer pool" +.Sh SYNOPSIS +.In db.h +.In mpool.h +.Ft MPOOL * +.Fn mpool_open "void *key" "int fd" "pgno_t pagesize" "pgno_t maxcache" +.Ft void +.Fo mpool_filter +.Fa "MPOOL *mp" +.Fa "void (*pgin)(void *, pgno_t, void *)" +.Fa "void (*pgout)(void *, pgno_t, void *)" +.Fa "void *pgcookie" +.Fc +.Ft void * +.Fn mpool_new "MPOOL *mp" "pgno_t *pgnoaddr" "u_int flags" +.Ft int +.Fn mpool_delete "MPOOL *mp" "void *page" +.Ft void * +.Fn mpool_get "MPOOL *mp" "pgno_t pgno" "u_int flags" +.Ft int +.Fn mpool_put "MPOOL *mp" "void *pgaddr" "u_int flags" +.Ft int +.Fn mpool_sync "MPOOL *mp" +.Ft int +.Fn mpool_close "MPOOL *mp" +.Sh DESCRIPTION +The +.Nm mpool +library interface is intended to provide page oriented buffer management +of files. +.Pp +The +.Fn mpool_open +function initializes a memory pool. +The +.Fa key +argument is currently ignored. +The +.Fa fd +argument is a file descriptor for the underlying file, which must be seekable. +.Pp +The +.Fa pagesize +argument is the size, in bytes, of the pages into which the file is broken up. +The +.Fa 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 +.Fn mpool_filter +function is intended to make transparent input and output processing of the +pages possible. +If the +.Fa pgin +function is specified, it is called each time a buffer is read into the memory +pool from the backing file. +If the +.Fa pgout +function is specified, it is called each time a buffer is written into the +backing file. +Both functions are called with the +.Fa pgcookie +pointer, the page number and a pointer to the page to being read or written. +.Pp +The function +.Fn mpool_new +takes an +.Dv 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 +.Fa pgnoaddr +address. +Otherwise, +.Dv NULL +is returned and +.Va errno +is set. +The flags value is formed by +.Tn OR Ns 'ing +the following values: +.Bl -tag -width Ds +.It Dv MPOOL_PAGE_REQUEST +Allocate a new page with a specific page number. +.It Dv MPOOL_PAGE_NEXT +Allocate a new page with the next page number. +.El +.Pp +The function +.Fn mpool_delete +deletes the specified page from a pool and frees the page. +It takes an +.Dv MPOOL +pointer and a page as arguments. +The page must have been generated by +.Fn mpool_new . +.Pp +The +.Fn mpool_get +function takes a +.Ft MPOOL +pointer and a page number as arguments. +If the page exists, a pointer to the page is returned. +Otherwise, +.Dv NULL +is returned and +.Va errno +is set. +The +.Fa flags +argument is specified by +.Em or Ns 'ing +any of the following values: +.Bl -tag -width indent +.It Dv MPOOL_IGNOREPIN +The page returned is not pinned; +page will otherwise be pinned on return. +.El +.Pp +The +.Fn mpool_put +function unpins the page referenced by +.Fa pgaddr . +The +.Fa pgaddr +argument +must be an address previously returned by +.Fn mpool_get +or +.Fn mpool_new . +The +.Fa flags +argument is specified by +.Em or Ns 'ing +any of the following values: +.Bl -tag -width indent +.It Dv MPOOL_DIRTY +The page has been modified and needs to be written to the backing file. +.El +.Pp +The +.Fn mpool_put +function +returns 0 on success and -1 if an error occurs. +.Pp +The +.Fn mpool_sync +function writes all modified pages associated with the +.Ft MPOOL +pointer to the +backing file. +The +.Fn mpool_sync +function +returns 0 on success and -1 if an error occurs. +.Pp +The +.Fn mpool_close +function free's up any allocated memory associated with the memory pool +cookie. +Modified pages are +.Em not +written to the backing file. +The +.Fn mpool_close +function +returns 0 on success and -1 if an error occurs. +.Sh ERRORS +The +.Fn mpool_open +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr malloc 3 . +.Pp +The +.Fn mpool_get +function may fail and set +.Va errno +for the following: +.Bl -tag -width Er +.It Bq Er EINVAL +The requested record does not exist. +.El +.Pp +The +.Fn mpool_new +and +.Fn mpool_get +functions may fail and set +.Va errno +for any of the errors specified for the library routines +.Xr read 2 , +.Xr write 2 , +and +.Xr malloc 3 . +.Pp +The +.Fn mpool_sync +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr write 2 . +.Pp +The +.Fn mpool_close +function may fail and set +.Va errno +for any of the errors specified for the library routine +.Xr free 3 . +.Sh SEE ALSO +.Xr btree 3 , +.Xr dbopen 3 , +.Xr hash 3 , +.Xr recno 3 |
