Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 205 insertions, 0 deletions

diff --git a/man3/mpool.3 b/man3/mpool.3
new file mode 100644
index 0000000..20dd313
--- /dev/null
+++ b/man3/mpool.3
@@ -0,0 +1,205 @@
+.\" Copyright (c) 1990, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\"	@(#)mpool.3	8.1 (Berkeley) 6/4/93
+.\"
+.TH mpool 3 2023-03-30 "Linux man-pages 6.05.01"
+.UC 7
+.SH NAME
+mpool \- shared memory buffer pool
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.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 up until glibc 2.1.
+Since glibc 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 STANDARDS
+BSD.
+.SH SEE ALSO
+.BR btree (3),
+.BR dbopen (3),
+.BR hash (3),
+.BR recno (3)