convert to mdoc, document changes from db 1.8.6

1 files changed, 121 insertions, 108 deletions

diff --git a/lib/libc/db/man/mpool.3 b/lib/libc/db/man/mpool.3
index 0ad0b6864b5..7797196b039 100644
--- a/lib/libc/db/man/mpool.3
+++ b/lib/libc/db/man/mpool.3
@@ -1,4 +1,4 @@
-.\"	$NetBSD: mpool.3,v 1.4 1995/02/27 13:23:35 cgd Exp $
+.\"	$OpenBSD: mpool.3,v 1.2 1999/02/26 01:20:41 millert Exp $
 .\"
 .\" Copyright (c) 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -33,189 +33,202 @@
 .\"
 .\"	@(#)mpool.3	8.1 (Berkeley) 6/4/93
 .\"
-.TH MPOOL 3 "June 4, 1993"
-.UC 7
-.SH NAME
-mpool \- shared memory buffer pool
-.SH SYNOPSIS
-.nf
-.ft B
-#include <db.h>
-#include <mpool.h>
-
-MPOOL *
-mpool_open (DBT *key, int fd, pgno_t pagesize, pgno_t maxcache);
-
-void
-mpool_filter (MPOOL *mp, void (*pgin)(void *, pgno_t, void *),
-.ti +5
-void (*pgout)(void *, pgno_t, void *), void *pgcookie);
-
-void *
-mpool_new (MPOOL *mp, pgno_t *pgnoaddr);
-
-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);
-.ft R
-.fi
-.SH DESCRIPTION
-.IR Mpool
+.Dd February 25, 1999
+.Os
+.Dt MPOOL 3
+.Sh NAME
+.Nm mpool
+.Nd shared memory buffer pool
+.Sh SYNOPSIS
+.Fd #include <db.h>
+.Fd #include <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" "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
+.Nm
 is the library interface intended to provide page oriented buffer management
 of files.
 The buffers may be shared between processes.
-.PP
+.Pp
 The function
-.I mpool_open
+.Fn mpool_open
 initializes a memory pool.
 The
-.I key
+.Ar 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
+.Ar key
 is NULL, the buffers are mapped into private memory.
 The
-.I fd
+.Ar fd
 argument is a file descriptor for the underlying file, which must be seekable.
 If
-.I key
+.Ar key
 is non-NULL and matches a file already being mapped, the
-.I fd
+.Ar fd
 argument is ignored.
-.PP
+.Pp
 The
-.I pagesize
+.Ar pagesize
 argument is the size, in bytes, of the pages into which the file is broken up.
 The
-.I maxcache
+.Ar 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
+.Pp
 The
-.I mpool_filter
+.Fn mpool_filter
 function is intended to make transparent input and output processing of the
 pages possible.
 If the
-.I pgin
+.Ar 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
+.Ar pgout
 function is specified, it is called each time a buffer is written into the
 backing file.
 Both functions are are called with the
-.I pgcookie
+.Ar pgcookie
 pointer, the page number and a pointer to the page to being read or written.
-.PP
+.Pp
 The function
-.I mpool_new
-takes an MPOOL pointer and an address as arguments.
+.Fn 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
-.I pgnoaddr
+.Ar pgnoaddr
 address.
 Otherwise, NULL is returned and errno is set.
-.PP
+The flags value is formed by
+.Em or Ns 'ing
+the following values:
+.Bl -tag -width Ds
+.It MPOOL_PAGE_REQUEST
+Allocate a new page with a specific page number.
+.It MPOOL_PAGE_NEXT
+Allocate a new page with the next page number.
+.El
+.Pp
 The function
-.I mpool_get
-takes a MPOOL pointer and a page number as arguments.
+.Fn 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
+.Fn mpool_new .
+.Pp
+The function
+.Fn mpool_get
+takes an 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 parameter is not currently used.
-.PP
+.Pp
 The function
-.I mpool_put
+.Fn mpool_put
 unpins the page referenced by
-.IR pgaddr .
-.I Pgaddr
+.Ar pgaddr .
+.Ar Pgaddr
 must be an address previously returned by
-.I mpool_get
+.Fn mpool_get
 or
-.IR mpool_new .
-The flag value is specified by
-.IR or 'ing
-any of the following values:
-.TP
-MPOOL_DIRTY
+.Fn mpool_new .
+The flags value is formed by
+.Em or Ns 'ing
+the following values:
+.Bl -tag -width Ds
+.It MPOOL_DIRTY
 The page has been modified and needs to be written to the backing file.
-.PP
-.I Mpool_put
+.El
+.Pp
+.Fn Mpool_put
 returns 0 on success and -1 if an error occurs.
-.PP
+.Pp
 The function
-.I mpool_sync
+.Fn mpool_sync
 writes all modified pages associated with the MPOOL pointer to the
 backing file.
-.I Mpool_sync
+.Fn Mpool_sync
 returns 0 on success and -1 if an error occurs.
-.PP
+.Pp
 The
-.I mpool_close
+.Fn mpool_close
 function free's up any allocated memory associated with the memory pool
 cookie.
 Modified pages are
-.B not
+.Em not
 written to the backing file.
-.I Mpool_close
+.Fn Mpool_close
 returns 0 on success and -1 if an error occurs.
-.SH ERRORS
+.Sh ERRORS
 The
-.I mpool_open
+.Fn mpool_open
 function may fail and set
-.I errno
+.Li errno
 for any of the errors specified for the library routine
-.IR malloc (3).
-.PP
+.Xr malloc 3 .
+.Pp
 The
-.I mpool_get
+.Fn mpool_get
 function may fail and set
-.I errno
+.Li errno
 for the following:
-.TP 15
-[EINVAL]
+.Bl -tag -width Er
+.It Bq Er EINVAL
 The requested record doesn't exist.
-.PP
+.El
+.Pp
 The
-.I mpool_new
+.Fn mpool_new
 and
-.I mpool_get
+.Fn mpool_get
 functions may fail and set
-.I errno
+.Li errno
 for any of the errors specified for the library routines
-.IR read (2) ,
-.IR write (2) ,
+.Xr read 2 ,
+.Xr write 2 ,
 and
-.IR malloc (3).
-.PP
+.Xr malloc 3 .
+.Pp
 The
-.I mpool_sync
+.Fn mpool_sync
 function may fail and set
-.I errno
+.Li errno
 for any of the errors specified for the library routine
-.IR write (2).
-.PP
+.Xr write 2 .
+.Pp
 The
-.I mpool_close
+.Fn mpool_close
 function may fail and set
-.I errno
+.Li errno
 for any of the errors specified for the library routine
-.IR free (3).
-.SH "SEE ALSO"
-.IR dbopen (3),
-.IR btree (3),
-.IR hash (3),
-.IR recno (3)
+.Xr free 3 .
+.Pp
+The
+.Fn mpool_delete
+always acts as if it succeeded.
+.Sh SEE ALSO
+.Xr dbopen 3 ,
+.Xr btree 3 ,
+.Xr hash 3 ,
+.Xr recno 3