[src/trunk]: src/lib/libc/db/man Convert to mdoc.

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/05e8ead5853f
branches:  trunk
changeset: 545912:05e8ead5853f
user:      wiz <wiz%NetBSD.org@localhost>
date:      Thu Apr 17 19:18:01 2003 +0000

description:
Convert to mdoc.

diffstat:

 lib/libc/db/man/hash.3 |  194 +++++++++++++++++++++++++-----------------------
 1 files changed, 100 insertions(+), 94 deletions(-)

diffs (238 lines):

diff -r 1765b1730b6f -r 05e8ead5853f lib/libc/db/man/hash.3
--- a/lib/libc/db/man/hash.3    Thu Apr 17 19:17:48 2003 +0000
+++ b/lib/libc/db/man/hash.3    Thu Apr 17 19:18:01 2003 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: hash.3,v 1.8 2002/02/07 07:00:10 ross Exp $
+.\"    $NetBSD: hash.3,v 1.9 2003/04/17 19:18:01 wiz Exp $
 .\"
 .\" Copyright (c) 1990, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -33,129 +33,135 @@
 .\"
 .\"    @(#)hash.3      8.6 (Berkeley) 8/18/94
 .\"
-.TH HASH 3 "August 18, 1994"
-.UC 7
-.SH NAME
-hash \- hash database access method
-.SH SYNOPSIS
-.nf
-.ft B
-#include \*[Lt]sys/types.h\*[Gt]
-#include \*[Lt]db.h\*[Gt]
-.ft R
-.fi
-.SH DESCRIPTION
+.Dd April 17, 2003
+.Dt HASH 3
+.Os
+.Sh NAME
+.Nm hash
+.Nd hash database access method
+.Sh SYNOPSIS
+.In sys/types.h
+.In db.h
+.Sh DESCRIPTION
 The routine
-.IR dbopen
+.Fn dbopen
 is the library interface to database files.
 One of the supported file formats is hash files.
 The general description of the database access methods is in
-.IR dbopen (3),
+.Xr dbopen 3 ,
 this manual page describes only the hash specific information.
-.PP
+.Pp
 The hash data structure is an extensible, dynamic hashing scheme.
-.PP
+.Pp
 The access method specific data structure provided to
-.I dbopen
-is defined in the \*[Lt]db.h\*[Gt] include file as follows:
-.sp
+.Fn dbopen
+is defined in the
+.Aq Pa db.h
+include file as follows:
+.Bd -literal
 typedef struct {
-.RS
-u_int bsize;
-.br
-u_int ffactor;
-.br
-u_int nelem;
-.br
-u_int cachesize;
-.br
-u_int32_t (*hash)(const void *, size_t);
-.br
-int lorder;
-.RE
+       u_int bsize;
+       u_int ffactor;
+       u_int nelem;
+       u_int cachesize;
+       u_int32_t (*hash)(const void *, size_t);
+       int lorder;
 } HASHINFO;
-.PP
+.Ed
+.Pp
 The elements of this structure are as follows:
-.TP
-bsize
-.I Bsize
+.Bl -tag -width cachesizex
+.It Fa bsize
+.Fa bsize
 defines the hash table bucket size, and is, by default, 256 bytes.
-It may be preferable to increase the page size for disk-resident tables
-and tables with large data items.
-.TP
-ffactor
-.I Ffactor
+It may be preferable to increase the page size for disk-resident
+tables and tables with large data items.
+.It Fa ffactor
+.Fa ffactor
 indicates a desired density within the hash table.
-It is an approximation of the number of keys allowed to accumulate in any
-one bucket, determining when the hash table grows or shrinks.
+It is an approximation of the number of keys allowed to accumulate in
+any one bucket, determining when the hash table grows or shrinks.
 The default value is 8.
-.TP
-nelem
-.I Nelem
+.It Fa nelem
+.Fa nelem
 is an estimate of the final size of the hash table.
 If not set or set too low, hash tables will expand gracefully as keys
-are entered, although a slight performance degradation may be noticed.
+are entered, although a slight performance degradation may be
+noticed.
 The default value is 1.
-.TP
-cachesize
+.It Fa cachesize
 A suggested maximum size, in bytes, of the memory cache.
 This value is
-.B only
+.Em only
 advisory, and the access method will allocate more memory rather
 than fail.
-.TP
-hash
-.I Hash
+.It Fa hash
+.Fa hash
 is a user defined hash function.
 Since no hash function performs equally well on all possible data, the
-user may find that the built-in hash function does poorly on a particular
-data set.
-User specified hash functions must take two arguments (a pointer to a byte
-string and a length) and return a 32-bit quantity to be used as the hash
-value.
-.TP
-lorder
+user may find that the built-in hash function does poorly on a
+particular data set.
+User specified hash functions must take two arguments (a pointer to a
+byte string and a length) and return a 32-bit quantity to be used as
+the hash value.
+.It Fa lorder
 The byte order for integers in the stored database metadata.
 The number should represent the order as an integer; for example,
 big endian order would be the number 4,321.
 If
-.I lorder
+.Fa lorder
 is 0 (no order is specified) the current host order is used.
-If the  file already exists, the specified value is ignored and the
+If the file already exists, the specified value is ignored and the
 value specified when the tree was created is used.
-.PP
-If the file already exists (and the 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.
-.PP
-If a hash function is specified,
-.I 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
-.IR dbm (3),
+.El
+.Pp
+If the file already exists (and the
+.Dv O_TRUNC
+flag is not specified), the values specified for the parameters
+.Fa bsize ,
+.Fa ffactor ,
+.Fa lorder ,
 and
-.IR ndbm (3)
-are provided, however these interfaces are not compatible with
-previous file formats.
-.SH ERRORS
+.Fa nelem
+are ignored and the values specified when the tree was created are
+used.
+.Pp
+If a hash function is specified,
+.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 ,
+.\"and
+.\".Xr ndbm 3
+.\"are provided, however these interfaces are not compatible with
+.\"previous file formats.
+.Sh ERRORS
 The
-.I hash
+.Nm
 access method routines may fail and set
-.I errno
+.Va errno
 for any of the errors specified for the library routine
-.IR dbopen (3).
-.SH "SEE ALSO"
-.IR btree (3),
-.IR dbopen (3),
-.IR mpool (3),
-.IR recno (3)
-.sp
-.IR "Dynamic Hash Tables" ,
-Per-Ake Larson, Communications of the ACM, April 1988.
-.sp
-.IR "A New Hash Package for UNIX" ,
-Margo Seltzer, USENIX Proceedings, Winter 1991.
-.SH BUGS
+.Xr dbopen 3 .
+.Sh SEE ALSO
+.Xr btree 3 ,
+.Xr dbopen 3 ,
+.Xr mpool 3 ,
+.Xr recno 3
+.Pp
+.Rs
+.%T "Dynamic Hash Tables"
+.%A Per-Ake Larson
+.%J Communications of the ACM
+.%D April 1988
+.Re
+.Rs
+.%T "A New Hash Package for UNIX"
+.%A Margo Seltzer
+.%J USENIX Proceedings
+.%D Winter 1991
+.Re
+.Sh BUGS
 Only big and little endian byte order is supported.