diff options
Diffstat (limited to 'static/netbsd/man3/mpool.3')
| -rw-r--r-- | static/netbsd/man3/mpool.3 | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/static/netbsd/man3/mpool.3 b/static/netbsd/man3/mpool.3 new file mode 100644 index 00000000..14814b9a --- /dev/null +++ b/static/netbsd/man3/mpool.3 @@ -0,0 +1,226 @@ +.\" $NetBSD: mpool.3,v 1.11 2019/03/08 08:35:58 msaitoh Exp $ +.\" +.\" 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. +.\" 3. 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 +.\" +.Dd December 16, 2010 +.Dt MPOOL 3 +.Os +.Sh NAME +.Nm mpool , +.Nm mpool_open , +.Nm mpool_filter , +.Nm mpool_new , +.Nm mpool_get , +.Nm mpool_put , +.Nm mpool_sync , +.Nm mpool_close +.Nd shared memory buffer pool +.Sh SYNOPSIS +.In db.h +.In mpool.h +.Ft MPOOL * +.Fn mpool_open "DBT *key" "int fd" "pgno_t pagesize" "pgno_t maxcache" +.Ft void +.Fn mpool_filter "MPOOL *mp" "void (*pgin)(void *, pgno_t, void *)" \ +"void (*pgout)(void *, pgno_t, void *)" "void *pgcookie" +.Ft void * +.Fn mpool_new "MPOOL *mp" "pgno_t *pgnoaddr" +.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 +.Nm +is the library interface intended to provide page oriented buffer +management of files. +The buffers may be shared between processes. +.Pp +The function +.Fn mpool_open +initializes a memory pool. +The +.Fa 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 +.Fa key +is +.Dv NULL , +the buffers are mapped into private memory. +The +.Fa fd +argument is a file descriptor for the underlying file, which must be +seekable. +If +.Fa key +is +.No non- Ns Dv NULL +and matches a file already being mapped, the +.Fa fd +argument is ignored. +.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 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 +.Fa pgnoaddr +address. +Otherwise, +.Dv NULL +is returned and errno is set. +.Pp +The function +.Fn mpool_get +takes a 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 errno is set. +The flags parameter is not currently used. +.Pp +The function +.Fn mpool_put +unpins the page referenced by +.Fa pgaddr . +.Fa pgaddr +must be an address previously returned by +.Fn mpool_get +or +.Fn mpool_new . +The flag value is specified by or'ing any of the following values: +.Bl -tag -width MPOOL_DIRTYX -offset indent +.It Dv MPOOL_DIRTY +The page has been modified and needs to be written to the backing +file. +.El +.Pp +.Fn mpool_put +returns 0 on success and \-1 if an error occurs. +.Pp +The function +.Fn mpool_sync +writes all modified pages associated with the MPOOL pointer to the +backing file. +.Fn mpool_sync +returns 0 on success and \-1 if an error occurs. +.Pp +The +.Fn mpool_close +function frees up any allocated memory associated with the memory pool +cookie. +Modified pages are +.Em not +written to the backing file. +.Fn mpool_close +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 -offset indent +.It Er EINVAL +The requested record doesn't 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 |