Convert to mdoc.
This commit is contained in:
wiz
parent
0a1b8c0e9c
commit
7e06307f35
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue