ndbm(3X)

構文

#include <ndbm.h>

DBM *dbm_open(const char *file, int flags, mode_t mode);

void dbm_close(DBM *db);

datum dbm_fetch(DBM *db, datum key);

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

int dbm_delete(DBM *db, datum key);

datum dbm_firstkey(DBM *db);

datum dbm_nextkey(DBM *db);

int dbm_error(DBM *db);

int dbm_clearerr(DBM *db);

説明

データベースの key/content の組を管理する関数です。これらの関数は非常に大きな (10 億ブロック (ブロック = 1024 バイト) ) データベースを扱います。1〜2 個のファイルシステムアクセスにおいては、key で識別して要素にアクセスできます。

パラメータ key と content は datum 型で記述します。 datum は dptr の指す長さ dsize バイトの文字列を表します。 通常の ASCII 文字列ばかりでなく、任意のバイナリデータも使用できます。 データベースは ２ つのファイルに分けられます。 １ つは key のビットマップのあるディレクトリのファイルで、拡張子 .dir が付けられます。 ２ つ目はすべてのデータを含んだファイルで、拡張子 .pag が付けられます。

データベースにアクセスする前に、まず dbm_open でデータベースをオープンする必要があります。 この関数はファイル file.dir と file.pag を作成し、パラメータ flags によっては、それをオープンします open(2) を参照)。

いったんデータベースをオープンすると、key のもとで貯えられているデータは dbm_fetch でアクセスできます。また dbm_store でデータを key のもとで貯えられます。 flags フィールドには DBM_INSERT か DBM_REPLACE を指定します。 DBM_INSERT は新しい登録データのみをデータベースに追加挿入し、同じ key ですでに登録されているデータはそのままにします。 DBM_REPLACE は、同じ key のデータがすでに存在していたとき、古いデータを新しいもので置き換えます。 key (とその content) は dbm_delete で削除します。 dbm_firstkey と dbm_nextkey で (見かけ上は) 無秩序に、データベースのすべての key を一次元的に移動できます。 dbm_firstkey はデータベースの最初の key を返します。 dbm_nextkey はデータベースの次の key を返します。 次の文はデータベースのすべての key を順番に指します。

dbm_error は、データベースの読み書き時になんらかのエラーがあると、０ 以外の数を返します。 dbm_clearerr は、指定したデータベースのエラー状態をリセットします。

診断

一般に int を返す関数について、負の戻り値はエラーを、戻り値 ０ は正常終了を表しています。 datum を返す関数は null dptr でエラーを表します。 flags に DBM_INSERT を指定して dbm_store を呼び出し、同じ key のデータが存在した場合、値 1 が返されます。 dbm_store の呼び出しによって内部ブロックのオーバーフローが発生した場合、値 -2 が返されます。

警告

このライブラリが提供する ndbm を、 他の汎用データベース管理システムと混同してはいけません。 これらの関数は、１ つのデータに複数の key を許して いません し、マルチユーザーアクセスを考慮して いません (つまりレコードやファイルをロックしない) し、より高度に構成された一般のデータベース管理システムのように、便利な関数を多数提供するわけでも ありません。 ハッシュを整理しながらデータコピーが行われるため、これらの関数を使ってデータベースを構築し、更新するのは比較的時間がかかります。 key が単一の比較的静的な情報を高速に参照するアプリケーションには、これらの関数は 有益 です。

これらの関数が返すデータのポインターは整列されていません。 そのため、特定の境界整列の必要なデータがブロックにあると、 問題が発生することがあります。 整列の必要なデータがブロックにある場合は、そのブロックを適切な整列領域に コピーする必要があります。

.pag ファイルは空白を含むので、見かけ上の大きさは、実質的な大きさの ４ 倍程度になります。 古い UNIX システムには、こういった空白にアクセスすると、実際にファイルブロックを作るものがあります。 これらのファイルは、拡張なしには cp(1), cat(1), tar(1), ar(1) のような) 通常の方法ではコピーできません。

これらのサブルーチンの返すポインター dptr は、続く呼び出しで変更される静的な記憶領域を指します。

key/content の大きさの合計は、内部的なブロックサイズ (現在は 1024 バイト) を超えることができません。 さらに、ハッシュ時にひとまとめに扱われる key/content の組は １ つのブロックに入らなくてはなりません。 データが分割できず、複数のディスクブロックにまたがってしまうイベントの場合、 dbm_store はエラーを返します。

dbm_delete は物理的にファイルスペースを改善するわけではありませんが、ファイルスペースを再利用可能にします。

dbm_firstkey と dbm_nextkey により返される key の順序は、純粋にハッシュ関数のみに依存しており、他には特にあらわに依存する要素はありません。

dbm_firstkey や dbm_nextkey で一次元的にデータベース上を移動しているときに dbm_store や dbm_delete を行うと、予想外の結果を招く可能性があります。

著者

ndbm(3X) はカリフォルニア大学バークレイ校で開発されました。

参照

dbm(3X), thread_safety(5)