名称

dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr − データベースサブルーチン

形式

#include <ndbm.h>

typedef struct {
    char ∗dptr;
    int dsize;
} datum;

DBM ∗dbm_open(file, flags, mode)
    char ∗file;
    int flags, mode;

void dbm_close(db)
    DBM ∗db;

datum dbm_fetch(db, key)
    DBM ∗db;
    datum key;

int dbm_store(db, key, content, flags)
    DBM ∗db;
    datum key, content;
    int flags;

int dbm_delete(db, key)
    DBM ∗db;
    datum key;

datum dbm_firstkey(db)
    DBM ∗db;

datum dbm_nextkey(db)
    DBM ∗db;

int dbm_error(db)
    DBM ∗db;

int dbm_clearerr(db)
    DBM ∗db;

解説

これらの関数は、 データベースの(キーと内容)のペアを扱います。 また、 これらの関数は、 非常に大きな(10億ブロック)データベースを扱い、 1回、または 2回のファイルシステムのアクセスで、 キー項目をアクセスします。 このパッケージは、 初期の dbm(3X) ライブラリに代わるもので、 単一のデータベースのみを管理します。

key と content を、 型宣言 datum で記述します。 datum は、 dsize バイトの dptr で指し示される文字列を指定します。 任意のバイナリデータが、 普通のASCII文字列同様に扱えます。 データベースは、 2つのファイルに格納されます。 1つはビットマップを含むディレクトリで、 ファイル名の終わりに‘.dir’が付きます。 もう1つはすべてのデータを含み、 ファイル名の終わりに‘.pag’が付きます。

データベースをアクセスする前に、 dbm_open を使ってオープンしなければなりません。 この時、 引数 flags の値に応じて、 ファイル file.dir と file.pag をオープンまたは、 新規作成します (open(2) を参照して下さい)。

一度オープンすると、 キー値に従って格納されたデータは、 dbm_fetch によってアクセスされます。 また、 データは、 dbm_store によってキー値にしたがって格納されます。 flags フィールドは、 DBM_INSERT または DBM_REPLACE のいずれかになります。 DBM_INSERT は新しいエントリを入力するだけで、 同じキーを持つ既存エントリの変更はしません。 また、 DBM_REPLACE は、 同じキーを持つ既存のエントリがある場合、 それと置き換えます。 dbm_delete は、 キー(とそれに対応する内容)を削除します。 dbm_firstkey と dbm_nextkey を使用して、 (明らかに)ランダムな順に、 データベース内のすべてのキーを含むリニアパスを作ることができます。 dbm_firstkey は、 データベース内の 1番目のキーを 返します。 また、 dbm_nextkey は、 データベース内の次のキーを返します。 次のプログラムは、 データベースを先頭から最後まで、 順にアクセスしていくものです。

for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))

データベースの読み出しまたは書き込みの時にエラーが生じた場合、 dbm_error はゼロ以外の値を返します。 dbm_clearerr は、 指定したデータベースのエラー状態をリセットします。

診断

整数値 を返す関数は、 すべて、 負の値を返すことでエラーの発生を示します。 正常終了の場合は、 ゼロを返します。 datum を返すルーチンは、 dptr にナルポインタをセットすることでエラーの発生を示します。 引数 flags に値 DBM_INSERT をセットして呼び出した dbm_store が、 同じキーを持つ既存エントリを検出した場合、 1 を返します。

バグ

‘.pag’ファイルはすき間を含んでおり、 その見かけのサイズは実際の内容の約4倍もあります。 旧バージョンのUNIXシステムでは、 アクセスがあった時に、 これらのすき間に対して実質的なファイルブロックを生成する可能性があります。 このようなファイルは、 すき間を埋めないかぎり、 一般的な手段(cp,cat,tp,tar,ar)でコピーできません。

これらのサブルーチンで返す dptr ポインタは、 スタティックな領域を指し、 引き続く呼び出しで変更されます。

キーと内容の組みの合計サイズは、 内部ブロックサイズ(現在 4096 バイト)を超えてはいけません。 さらに、 ハッシュ結果が同じであるキーと内容の組みはすべて、 1つのブロックに対応させなければなりません。 分けることのできないデータで、 ディスクブロックがいっぱいになった場合、 dbm_store はエラーを返します。

たとえ、 ファイル空間を再利用可能な状態でも、 dbm_delete は、 その空間を物理的に再利用しません。

dbm_firstkey および dbm_nextkey によって与えられたキーの順序は、 ハッシュ関数にのみ依存します。

関連事項

dbm(3X)

NEWS-OSRelease 4.1C