.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)hash.3	8.6 (Berkeley) 8/18/94
.\" %FreeBSD: src/lib/libc/db/man/hash.3,v 1.4.2.2 2001/12/14 18:33:49 ru Exp %
.\" $FreeBSD$
.\"
.Dd August 18, 1994
.Dt HASH 3
.Os
.Sh 名称
.Nm hash
.Nd "hash データベース アクセス方式"
.Sh 書式
.In sys/types.h
.In db.h
.Sh 解説
.Fn dbopen
ルーチンは、データベースファイルへのライブラリインタフェースです。
サポート対象のファイル形式の一つは
.Nm
ファイルです。本マニュアルの
.Xr dbopen 3
にあるデータベースアクセス方式の一般的な解説は
に書かれており、
.Nm
固有の情報だけを説明しています。
.Pp
.Nm
データ構造は拡張可能な動的ハッシュスキーマです。
.Pp
.Fn dbopen
に与えられるアクセス方式固有のデータ構造体は
インクルードファイル
.Aq Pa db.h
で以下のように定義されます。
.Bd -literal
typedef struct {
	u_int bsize;
	u_int ffactor;
	u_int nelem;
	u_int cachesize;
	u_int32_t (*hash)(const void *, size_t);
	int lorder;
} HASHINFO;
.Ed
.Pp
この構造体のフィールドは以下になります。
.Bl -tag -width indent
.It Va bsize
.Va bsize
は、
.Nm
表のバケットサイズを定義し、デフォルト値で 256 バイトです。
ディスク常駐テーブルと大型データ項目については、
ページサイズを拡大したほうが望ましいかもしれません。
.It Va ffactor
.Va ffactor
は
.Nm
表内の望ましい密度を表示します。
これは一つのバケット内に累積可能なキー数の概算であり、
いつ
.Nm
表の拡大や縮小を行なうべきかを決定します。
デフォルト値は 8 です。
.It Va nelem
.Va nelem
は
.Nm
表の最終サイズの推測値です。
未設定あるいは低い値に設定されると、わずかな性能劣化が見られる
かもしれませんが、ハッシュ表はキー入力に応じて円滑に拡張されます。
デフォルト値は 1 です。
.It Va cachesize
メモリキャッシュの推奨最大バイトサイズです。
この値は
.Em 単なる
提言であり、このアクセス方式は、
失敗するよりはメモリを余計に割り当てるでしょう。
.It Va hash
.Va hash
はユーザ定義の
.Nm
関数です。
可能なデータすべてに対して等しく性能の良い
.Nm
関数はないため、
ユーザは、組み込み
.Nm
関数が特定データセットに充分な性能が出ないことに
気がつくことがあるかもしれません。
ユーザ指定
.Nm
関数は 2 個の引数 (文字列へのポインタと長さ) を取り、
ハッシュ値として使われる 32 ビット量を返します。
.It Va lorder
保存されたデータベースメタデータ
内の整数のバイトオーダです。
数字は整数としての順序を表していなければなりません。
例えば、ビッグエンディアンの順序は 4,321 になります。
.Va lorder
が
0 (順序指定なし) の時は現行のホストのオーダが使われます。
ファイルがあらかじめ存在していれば、指定値が無視されて、
ツリーが構築された時に指定された値が使われます。
.El
.Pp
ファイルがあらかじめ存在し、(かつ
.Dv O_TRUNC
フラグが指定されてないと) 、
.Va bsize , ffactor , lorder , nelem
の各パラメータに指定された値は無視され、
ツリーの構築時に指定された値が使われます。
.Pp
.Nm
関数が指定されていると、
.Fn hash_open
は指定された
.Nm
関数がデータベース作成時と同じものであるかを判別し、
異なっていれば open に失敗します。
.Pp
旧
.Em dbm
および旧
.Em ndbm
ルーチンへの下位互換インタフェースが提供されていますが、
これらのインタフェースは従来のファイルフォーマットとは互換ではありません。
.Sh エラー
ライブラリルーチン
.Xr dbopen 3
で指定されている任意のエラーに対し、
.Nm
アクセス方式ルーチンが失敗すると、
.Va errno
をセットします。
.Sh 関連項目
.Xr btree 3 ,
.Xr dbopen 3 ,
.Xr mpool 3 ,
.Xr recno 3
.Rs
.%T "Dynamic Hash Tables"
.%A Per-Ake Larson
.%R "Communications of the ACM"
.%D April 1988
.Re
.Rs
.%T "A New Hash Package for UNIX"
.%A Margo Seltzer
.%R "USENIX Proceedings"
.%D Winter 1991
.Re
.Sh バグ
バイトオーダとして、ビッグエンディアンとリトルエンディアンだけが
サポートされています。