- punctuation, macro, layout, wording improvements

- avoid first person
- document dbm_rdonly
- update some error return values in the mpool(3) routines
- sync header file excerpts

ok jmc

8 files changed, 120 insertions, 107 deletions

diff --git a/lib/libc/db/man/Makefile.inc b/lib/libc/db/man/Makefile.inc
index 6fad4927777..6a56912cac4 100644
--- a/lib/libc/db/man/Makefile.inc
+++ b/lib/libc/db/man/Makefile.inc
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile.inc,v 1.12 2004/06/24 04:43:33 millert Exp $
+#	$OpenBSD: Makefile.inc,v 1.13 2005/07/17 09:10:36 jaredy Exp $
 
 .PATH: ${LIBCSRCDIR}/db/man
 
@@ -12,4 +12,4 @@ MLINKS+= mpool.3 mpool_sync.3 mpool.3 mpool_close.3
 MLINKS+= ndbm.3 dbm_clearerr.3 ndbm.3 dbm_close.3 ndbm.3 dbm_delete.3
 MLINKS+= ndbm.3 dbm_dirfno.3 ndbm.3 dbm_error.3 ndbm.3 dbm_fetch.3
 MLINKS+= ndbm.3 dbm_firstkey.3 ndbm.3 dbm_nextkey.3 ndbm.3 dbm_open.3
-MLINKS+= ndbm.3 dbm_pagfno.3 ndbm.3 dbm_store.3
+MLINKS+= ndbm.3 dbm_pagfno.3 ndbm.3 dbm_rdonly.3 ndbm.3 dbm_store.3
diff --git a/lib/libc/db/man/btree.3 b/lib/libc/db/man/btree.3
index cb9edebc4f7..3b1ad9f2c08 100644
--- a/lib/libc/db/man/btree.3
+++ b/lib/libc/db/man/btree.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: btree.3,v 1.17 2003/07/07 14:43:18 jmc Exp $
+.\"	$OpenBSD: btree.3,v 1.18 2005/07/17 09:10:36 jaredy Exp $
 .\"	$NetBSD: btree.3,v 1.6 1996/05/03 21:26:48 cgd Exp $
 .\"
 .\" Copyright (c) 1997, Phillip F Knaack. All rights reserved.
@@ -60,11 +60,11 @@ is defined in the
 include file as follows:
 .Bd -literal -offset indent
 typedef struct {
-	u_long flags;
-	u_int cachesize;
+	unsigned long flags;
+	unsigned int cachesize;
 	int maxkeypage;
 	int minkeypage;
-	u_int psize;
+	unsigned int psize;
 	int (*compare)(const DBT *key1, const DBT *key2);
 	size_t (*prefix)(const DBT *key1, const DBT *key2);
 	int lorder;
@@ -159,7 +159,7 @@ argument which are necessary to determine that it is greater than the first
 key argument.
 If the keys are equal, the key length should be returned.
 Note, the usefulness of this routine is very data dependent, but in some
-data sets can produce significantly reduced tree sizes and search times.
+data sets it can produce significantly reduced tree sizes and search times.
 If
 .Fa prefix
 is
diff --git a/lib/libc/db/man/dbm.3 b/lib/libc/db/man/dbm.3
index c2df560ab5b..d1ae317cd88 100644
--- a/lib/libc/db/man/dbm.3
+++ b/lib/libc/db/man/dbm.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: dbm.3,v 1.9 2004/05/03 17:27:50 millert Exp $
+.\" $OpenBSD: dbm.3,v 1.10 2005/07/17 09:10:36 jaredy Exp $
 .\"
 .\" Copyright (c) 1999 Todd C. Miller <Todd.Miller@courtesan.com>
 .\"
@@ -55,7 +55,7 @@ data structure:
 typedef struct {
 	void *dptr;
 	size_t dsize;
-} datum
+} datum;
 .Ed
 .Pp
 The
@@ -103,8 +103,8 @@ function returns the first record of the database, and thereafter
 .Fn nextkey
 returns the following records.
 The following code traverses the entire database:
-.Bd -literal
-  for (key = firstkey(); key.dptr != NULL; key = nextkey(key))
+.Bd -literal -offset indent
+for (key = firstkey(); key.dptr != NULL; key = nextkey(key))
 .Ed
 .Pp
 The behaviour of
@@ -114,7 +114,7 @@ is undefined if the database is modified after a call to
 .Pp
 The database is closed with the
 .Fn dbmclose
-function (you must close a database before opening a new one).
+function (it must be closed before a new one can be opened).
 .Ss Implementation notes
 The underlying database is a
 .Xr hash 3
@@ -141,7 +141,7 @@ field to
 .Sh BUGS
 Because the
 .Nm dbm
-routines are implemented on top of the
+routines are implemented on top of
 .Xr db 3 ,
 only a single file,
 .Pa file.pag ,
diff --git a/lib/libc/db/man/dbopen.3 b/lib/libc/db/man/dbopen.3
index 3d956ffaf2e..ee4b878cdc5 100644
--- a/lib/libc/db/man/dbopen.3
+++ b/lib/libc/db/man/dbopen.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: dbopen.3,v 1.22 2004/05/05 20:19:48 millert Exp $
+.\"	$OpenBSD: dbopen.3,v 1.23 2005/07/17 09:10:36 jaredy Exp $
 .\"	$NetBSD: dbopen.3,v 1.6 1995/02/27 13:23:25 cgd Exp $
 .\"
 .\" Copyright (c) 1997, Phillip F Knaack. All rights reserved.
@@ -142,23 +142,27 @@ on error.
 The DB structure is defined in the
 .Aq Pa db.h
 include file, and contains at least the following fields:
-.Bd -literal
+.Bd -literal -offset indent
 typedef struct {
 	DBTYPE type;
 	int (*close)(const DB *db);
-	int (*del)(const DB *db, const DBT *key, u_int flags);
+	int (*del)(const DB *db, const DBT *key,
+	    unsigned int flags);
 	int (*fd)(const DB *db);
-	int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
-	int (*put)(const DB *db, DBT *key, const DBT *data, u_int flags);
+	int (*get)(const DB *db, DBT *key, DBT *data,
+	    unsigned int flags);
+	int (*put)(const DB *db, DBT *key, const DBT *data,
+	    unsigned int flags);
 	int (*sync)(const DB *db, u_int flags);
-	int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
+	int (*seq)(const DB *db, DBT *key, DBT *data,
+	    unsigned int flags);
 } DB;
 .Ed
 .Pp
 These elements describe a database type and a set of functions performing
 various actions.
 These functions take a pointer to a structure as returned by
-.Fn dbopen dbopen ,
+.Fn dbopen ,
 and sometimes one or more pointers to key/data structures and a flag value.
 .Bl -tag -width XXXXX -offset indent
 .It Fa type
@@ -180,15 +184,15 @@ and 0 on success.
 A pointer to a routine to remove key/data pairs from the database.
 .Pp
 The parameter
-.Fa flag
+.Fa flags
 may be set to the following value:
-.Bl -tag -width XXXXX
+.Bl -tag -width R_NOOVERWRITE
 .It Dv R_CURSOR
 Delete the record referenced by the cursor.
 The cursor must have previously been initialized.
 .El
 .Pp
-.Fa delete
+.Fa del
 routines return \-1 on error (setting
 .Va errno ) ,
 0 on success, and 1 if the specified
@@ -210,10 +214,10 @@ and
 locking functions.
 The file descriptor is not necessarily associated with any of the
 underlying files used by the access method.
-No file descriptor is available for in memory databases.
+No file descriptor is available for in-memory databases.
 .Fa fd
 routines return \-1 on error (setting
-.Va errno ) ,
+.Va errno )
 and the file descriptor on success.
 .It Fa get
 A pointer to a routine which is the interface for keyed retrieval from
@@ -232,9 +236,9 @@ was not in the file.
 A pointer to a routine to store key/data pairs in the database.
 .Pp
 The parameter
-.Fa flag
+.Fa flags
 may be set to one of the following values:
-.Bl -tag -width XXXXX
+.Bl -tag -width R_NOOVERWRITE
 .It Dv R_CURSOR
 Replace the key/data pair referenced by the cursor.
 The cursor must have previously been initialized.
@@ -298,8 +302,7 @@ routines return \-1 on error (setting
 .Va errno ) ,
 0 on success, and 1 if the
 .Dv R_NOOVERWRITE
-.Fa flag
-was set and the key already exists in the file.
+flag was set and the key already exists in the file.
 .It Fa seq
 A pointer to a routine which is the interface for sequential
 retrieval from the database.
@@ -325,10 +328,12 @@ Modifications to the database during a sequential scan will be reflected
 in the scan, i.e., records inserted behind the cursor will not be returned
 while records inserted in front of the cursor will be returned.
 .Pp
-The flag value
+The
+.Fa flags
+value
 .Sy must
 be set to one of the following values:
-.Bl -tag -width XXXXX
+.Bl -tag -width R_NOOVERWRITE
 .It Dv R_CURSOR
 The data associated with the specified key is returned.
 This differs from the
@@ -382,7 +387,7 @@ order which does not change.
 .Fa seq
 routines return \-1 on error (setting
 .Va errno ) ,
-0 on success and 1 if there are no key/data pairs less than or greater
+0 on success, and 1 if there are no key/data pairs less than or greater
 than the specified or current key.
 If the
 .Dv DB_RECNO
@@ -397,13 +402,16 @@ If the database is in memory only, the
 .Fa sync
 routine has no effect and will always succeed.
 .Pp
-The flag value may be set to the following value:
-.Bl -tag -width XXXXX
+The
+.Fa flags
+value may be set to the following value:
+.Bl -tag -width R_NOOVERWRITE
 .It Dv R_RECNOSYNC
 If the
 .Dv DB_RECNO
-access method is being used, this flag causes
-the sync routine to apply to the btree file which underlies the
+access method is being used, this flag causes the
+.Fa sync
+routine to apply to the btree file which underlies the
 recno file, not the recno file itself.
 (See the
 .Fa bfname
@@ -420,23 +428,15 @@ and 0 on success.
 .Sh KEY/DATA PAIRS
 Access to all file types is based on key/data pairs.
 Both keys and data are represented by the following data structure:
-.Pp
-.Bl -item -compact
-.It
+.Bd -literal -offset indent
 typedef struct {
-.It
-.Bl -item -compact -offset indent
-.It
-void *data;
-.It
-size_t size;
-.El
-.It
+	void *data;
+	size_t size;
 } DBT;
-.El
+.Ed
 .Pp
 The elements of the DBT structure are defined as follows:
-.Bl -tag -width XXXXX
+.Bl -tag -width Ds -offset indent
 .It Fa data
 A pointer to a byte string.
 .It Fa size
@@ -466,7 +466,7 @@ A parameter has been specified (hash function, pad byte etc.) that is
 incompatible with the current file specification or which is not
 meaningful for the function (for example, use of the cursor without
 prior initialization) or there is a mismatch between the version
-number of file and the software.
+number of the file and the software.
 .El
 .Pp
 The
@@ -502,7 +502,7 @@ routines will fail and set
 .Va errno
 to
 .Er ENOENT
-for in memory databases.
+for in-memory databases.
 .Pp
 The
 .Fa sync
diff --git a/lib/libc/db/man/hash.3 b/lib/libc/db/man/hash.3
index 70087b50741..04adcd6107e 100644
--- a/lib/libc/db/man/hash.3
+++ b/lib/libc/db/man/hash.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: hash.3,v 1.13 2003/07/07 14:43:18 jmc Exp $
+.\"	$OpenBSD: hash.3,v 1.14 2005/07/17 09:10:36 jaredy Exp $
 .\"	$NetBSD: hash.3,v 1.6 1996/05/03 21:26:50 cgd Exp $
 .\"
 .\" Copyright (c) 1997, Phillip F Knaack. All rights reserved.
@@ -59,10 +59,10 @@ is defined in the
 include file as follows:
 .Bd -literal -offset indent
 typedef struct {
-	u_int bsize;
-	u_int ffactor;
-	u_int nelem;
-	u_int cachesize;
+	unsigned int bsize;
+	unsigned int ffactor;
+	unsigned int nelem;
+	unsigned int cachesize;
 	u_int32_t (*hash)(const void *, size_t);
 	int lorder;
 } HASHINFO;
@@ -118,16 +118,19 @@ value specified when the tree was created is used.
 If the file already exists (and the
 .Dv O_TRUNC
 flag is not specified), the
-values specified for the parameters bsize, ffactor, lorder and nelem are
-ignored and the values specified when the tree was created are used.
+values specified for the parameters
+.Fa bsize , ffactor , lorder
+and
+.Fa nelem
+are ignored and the values specified when the tree was created are used.
 .Pp
 If a hash function is specified,
-.Fa hash_open
+.Fn hash_open
 will attempt to determine if the hash function specified is the same as
 the one with which the database was created, and will fail if it is not.
 .Pp
 Backward compatible interfaces to the routines described in
-.Xr dbm 3 ,
+.Xr dbm 3
 and
 .Xr ndbm 3
 are provided, although these interfaces are not compatible with
diff --git a/lib/libc/db/man/mpool.3 b/lib/libc/db/man/mpool.3
index b5760f72f4e..040cf224c63 100644
--- a/lib/libc/db/man/mpool.3
+++ b/lib/libc/db/man/mpool.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mpool.3,v 1.13 2003/06/02 20:18:34 millert Exp $
+.\"	$OpenBSD: mpool.3,v 1.14 2005/07/17 09:10:36 jaredy Exp $
 .\"
 .\" Copyright (c) 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -46,24 +46,25 @@
 .Fd #include <db.h>
 .Fd #include <mpool.h>
 .Ft MPOOL *
-.Fn mpool_open "DBT *key" "int fd" "pgno_t pagesize" "pgno_t maxcache"
+.Fn mpool_open "void *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"
+.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"
+.Fn mpool_new "MPOOL *mp" "pgno_t *pgnoaddr" "unsigned int flags"
 .Ft int
 .Fn mpool_delete "MPOOL *mp" "void *page"
 .Ft void *
-.Fn mpool_get "MPOOL *mp" "pgno_t pgno" "u_int flags"
+.Fn mpool_get "MPOOL *mp" "pgno_t pgno" "unsigned int flags"
 .Ft int
-.Fn mpool_put "MPOOL *mp" "void *pgaddr" "u_int flags"
+.Fn mpool_put "MPOOL *mp" "void *pgaddr" "unsigned int flags"
 .Ft int
 .Fn mpool_sync "MPOOL *mp"
 .Ft int
 .Fn mpool_close "MPOOL *mp"
 .Sh DESCRIPTION
 .Nm mpool
-is the library interface intended to provide page oriented buffer management
+is the library interface intended to provide page-oriented buffer management
 of files.
 The buffers may be shared between processes.
 .Pp
@@ -115,7 +116,7 @@ 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.
+pointer, the page number, and a pointer to the page being read or written.
 .Pp
 The function
 .Fn mpool_new
@@ -193,7 +194,7 @@ 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
+function frees up any allocated memory associated with the memory pool
 cookie.
 Modified pages are
 .Em not
@@ -205,8 +206,15 @@ The
 .Fn mpool_open
 function may fail and set
 .Va errno
-for any of the errors specified for the library routine
-.Xr malloc 3 .
+for any of the errors specified for the library routines
+.Xr fstat 2
+and
+.Xr malloc 3 ,
+or the following:
+.Bl -tag -width Er
+.It Bq Er ESPIPE
+The given file descriptor is a pipe.
+.El
 .Pp
 The
 .Fn mpool_get
@@ -225,8 +233,8 @@ and
 functions may fail and set
 .Va errno
 for any of the errors specified for the library routines
-.Xr read 2 ,
-.Xr write 2 ,
+.Xr pread 2 ,
+.Xr pwrite 2 ,
 and
 .Xr malloc 3 .
 .Pp
@@ -235,7 +243,7 @@ The
 function may fail and set
 .Va errno
 for any of the errors specified for the library routine
-.Xr write 2 .
+.Xr pwrite 2 .
 .Pp
 The
 .Fn mpool_close
diff --git a/lib/libc/db/man/ndbm.3 b/lib/libc/db/man/ndbm.3
index 5eb62fb810a..45b0e8e64e6 100644
--- a/lib/libc/db/man/ndbm.3
+++ b/lib/libc/db/man/ndbm.3
@@ -1,5 +1,5 @@
 .\" David Leonard, 1998. Placed in the public domain.
-.\" $OpenBSD: ndbm.3,v 1.14 2004/05/03 17:27:50 millert Exp $
+.\" $OpenBSD: ndbm.3,v 1.15 2005/07/17 09:10:36 jaredy Exp $
 .Dd May 13, 1998
 .Dt NDBM 3
 .Os
@@ -14,6 +14,7 @@
 .Nm dbm_nextkey ,
 .Nm dbm_open ,
 .Nm dbm_pagfno ,
+.Nm dbm_rdonly ,
 .Nm dbm_store
 .Nd database access methods
 .Sh SYNOPSIS
@@ -39,6 +40,8 @@
 .Ft int
 .Fn dbm_pagfno "DBM *db"
 .Ft int
+.Fn dbm_rdonly "DBM *db"
+.Ft int
 .Fn dbm_store "DBM *db" "datum key" "datum content" "int store_mode"
 .Sh DESCRIPTION
 These functions provide a ndbm-compatible interface to the
@@ -53,7 +56,7 @@ data structure:
 typedef struct {
 	void *dptr;
 	size_t dsize;
-} datum
+} datum;
 .Ed
 .Pp
 The
@@ -71,6 +74,10 @@ parameter (see
 .Xr open 2 ) .
 Read-only access may be indicated by specifying
 .Dv DBM_RDONLY .
+The
+.Fn dbm_rdonly
+function may be used to determine if a database is opened for read-only
+access.
 .Pp
 Once the database is open,
 .Fn dbm_fetch
@@ -112,8 +119,9 @@ function returns the first record of the database, and thereafter
 .Fn dbm_nextkey
 returns the following records.
 The following code traverses the entire database:
-.Bd -literal
-  for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))
+.Bd -literal -offset indent
+for (key = dbm_firstkey(db); key.dptr != NULL;
+    key = dbm_nextkey(db))
 .Ed
 .Pp
 The behaviour of
diff --git a/lib/libc/db/man/recno.3 b/lib/libc/db/man/recno.3
index 165709344e4..e2d02009a65 100644
--- a/lib/libc/db/man/recno.3
+++ b/lib/libc/db/man/recno.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: recno.3,v 1.14 2003/06/02 20:18:34 millert Exp $
+.\"	$OpenBSD: recno.3,v 1.15 2005/07/17 09:10:36 jaredy Exp $
 .\"	$NetBSD: recno.3,v 1.6 1996/05/03 21:26:51 cgd Exp $
 .\"
 .\" Copyright (c) 1997, Phillip F Knaack. All rights reserved.
@@ -47,8 +47,8 @@ The
 routine is the library interface to database files.
 One of the supported file formats is record number files.
 The general description of the database access methods is in
-.Xr dbopen 3 ,
-this manual page describes only the recno specific information.
+.Xr dbopen 3 .
+This manual page describes only the recno specific information.
 .Pp
 The record number data structure is either variable or fixed-length
 records stored in a flat-file format, accessed by the logical record
@@ -66,30 +66,17 @@ access method specific data structure provided to
 is defined in the
 .Aq Pa db.h
 include file as follows:
-.Pp
-.Bl -item -compact
-.It
+.Bd -literal -offset indent
 typedef struct {
-.It
-.Bl -item -compact -offset indent
-.It
-u_long flags;
-.It
-u_int cachesize;
-.It
-u_int psize;
-.It
-int lorder;
-.It
-size_t reclen;
-.It
-u_char bval;
-.It
-char *bfname;
-.El
-.It
+	unsigned long	flags;
+	unsigned int	cachesize;
+	unsigned int	psize;
+	int		lorder;
+	size_t		reclen;
+	unsigned char	bval;
+	char		*bfname;
 } RECNOINFO;
-.El
+.Ed
 .Pp
 The elements of this structure are defined as follows:
 .Bl -tag -width XXXXXX
@@ -97,7 +84,7 @@ The elements of this structure are defined as follows:
 The flag value is specified by
 .Tn OR Ns 'ing
 any of the following values:
-.Bl -tag -width XXXXXX
+.Bl -tag -width R_FIXEDLEN
 .It Dv R_FIXEDLEN
 The records are fixed-length, not byte delimited.
 The structure element
@@ -164,8 +151,15 @@ spaces.
 .It Fa bfname
 The recno access method stores the in-memory copies of its records
 in a btree.
-If bfname is non-NULL, it specifies the name of the btree file,
-as if specified as the file name for a dbopen of a btree file.
+If
+.Fa bfname
+is non-NULL, it specifies the name of the
+.Xr btree 3
+file, as if specified as the file name for a
+.Xr dbopen 3
+of a
+.Xr btree 3
+file.
 .Pp
 The data part of the key/data pair used by the recno access method
 is the same as other access methods.
@@ -173,7 +167,7 @@ The key is different.
 The
 .Fa data
 field of the key should be a pointer to a memory location of type
-.Ft recno_t ,
+.Vt recno_t ,
 as defined in the
 .Aq Pa db.h
 include file.