説明
GNU dbm は、キーとデータのペアを含んだデータファイルを取り扱うルーチン群のライブラリである。提供されるアクセスとしては、キーによる格納、キーによる取り出し、キーによる削除の他、すべてのキーに渡るソートされていない横断的なアクセスがある。一つのプロセスからは複数のデータファイルを同時に利用することができる。
gdbm ファイルをオープンするプロセスは、「リーダ」または「ライタ」と呼ばれる。 1 つの gdbm ファイルをオープンできるライタは 1 つだけだが、リーダは複数が 1 つの gdbm ファイルをオープンすることができる。リーダとライタは同時に同じファイルをオープンすることはできない。 gdbm ファイルをオープンする手続きは次の通りである。
GDBM_FILE dbf;
dbf = gdbm_open ( name, block_size, read_write, mode, fatal_func )
name はファイルの名前である。(完全な名前、gdbm はこの名前に文字列を付け加えるようなことはしない)
block_size はディスクからメモリへ 1 回に転送されるサイズである。このパラメータは、新しいファイルの場合以外は無視される。最小サイズは 512 である。 512 よりも小さい場合には, gdbm はファイルシステムに対する stat のブロックサイズを使用する。
read_write には以下のいずれかの値を取る。
GDBM_READER リーダ
GDBM_WRITER ライタ
GDBM_WRCREAT ライタ-データベースが存在しなければ作成する
GDBM_NEWDB ライタ-すでに存在しても新しいデータベースを作成する
最後の 3 つについては (データベースのライタ)
read_write に対して以下をビットの OR により追加できる:
GDBM_SYNC はすべてのデータベースの操作をディスクと同期する、また
GDBM_NOLOCK はデータベースファイルに関するライブラリからのロック動作を行わない。オプション
GDBM_FAST は gdbm の既定動作が no-sync モードになったためにもう使われなくなった。
mode はファイルのモードである (
chmod(2) および
open(2) を参照)。
(*fatal_func) () は dbm が致命的エラーを検出した場合に呼び出す関数である。この関数への唯一のパラメータは文字列である。値 0 が指定されると、gdbm はデフォルトの関数を使用する。
返り値
dbf は、その gdbm ファイルにアクセスする他のすべてのルーチンに必要なポインタである。 NULL ポインタが返った場合、
gdbm_open は成功しなかったことを示す。 gdbm のエラーは
gdbm_errno に、システムのエラーは
errno に格納される (エラーコードについては gdbmerrno.h を参照)。
以下のすべてのコールにおいては、パラメータ
dbf は
gdbm_open から返ってきたポインタである。
どんなファイルでもオープンしたものをクローズすることは重要である。クローズはファイルに対するリーダ数／ライタ数を更新する。これは以下のようにして行う。
gdbm_close (dbf);
データベースは 3 つの主なルーチンによって利用できる。最初はデータをデータベースに格納するものである。
ret = gdbm_store ( dbf, key, content, flag )
dbf は
gdbm_open から返ってきたポインタである。
key はキーデータで、
content は
key に関連付けられたデータである。
flag は以下のいずれかの値を持つことができる。
GDBM_INSERT 挿入のみ。キーが存在すればエラーとなる。
GDBM_REPLACE キーが存在すれば内容を更新する。
リーダが
gdbm_store をコールした場合、返り値は-1 となる。 GDBM_INSERT が指定された時にデータベースに
key が存在すると、返り値は 1 である。そうでなければ返り値は 0 である。
注意: 既にデータベースに存在するキーを指定して格納する場合、 GDBM_REPLACE で呼び出しているならば、gdbm は古いデータを
新しいデータで置き換える。同じキーで 2 つのデータ・アイテムを得ることはできないし、また gdbm_store がエラーを返すこともない。
注意: gdbm のサイズは、dbm や ndbm と異なり制限されない。データは必要なだけ大きくすることができる。
データを検索するには、以下のようにする:
content = gdbm_fetch ( dbf, key )
dbf は
gdbm_open から返ってきたポインタである。
key はキーデータである。
返り値の
dptr が NULL の場合、データは見つからなかった。見つかった場合はデータへのポインタが返る。
dptr の記憶空間は
malloc(3C) により確保される。
gdbm
は自動的にこのデータを解放することはしない。
必要の無くなった領域を解放するのはプログラマの責任である。
データを参照せずに、検索だけする場合には：
ret = gdbm_exists ( dbf, key )
dbf は
gdbm_open から返ってきたポインタである。
key は検索したいキーデータである。
データベース内に
key が見つかれば、返り値
ret は true である。何も対応するものが見つからなければ
ret は false である。
gdbm_fetch ではメモリ確保が行われるが、このルーチンはそれをしないので、レコードの存在をチェックをする時に役に立つ。
データベースからあるデータを削除する場合は、以下のようにする:
ret = gdbm_delete ( dbf, key )
dbf は
gdbm_open から返ってきたポインタである。
key はキーデータである。
アイテムが存在しなかったり、要求したのがリーダだった場合、返り値は-1 である。削除に成功すれば返り値は 0 である。
次の 2 つのルーチンは、データベース中のすべてのアイテムにアクセスできる。アクセスはキー順ではないが、データベース内ですべてのキーに各 1 回アクセスすることは保証されている。(アクセス順序はハッシュ値の順になる。)
key = gdbm_firstkey ( dbf )
nextkey = gdbm_nextkey ( dbf, key )
dbf は
gdbm_open から返ってきたポインタである。
key はキーデータである。
返り値はどちらも
datum 型である。返り値の
dptr 要素が NULL の場合、最初のキーまたは次のキーがなかったことを示す。返り値の
dptr 要素が指しているのは
malloc(3C) により確保されたデータであり、
gdbm は free してはくれないことにもう一度注意すること。
これらの関数はデータベースをリードオンリーで参照することを意図していた。たとえば、データベースの正当性を確認したりするような目的で。
ファイルへの「参照」は「ハッシュ・テーブル」に基づいている。
gdbm_delete はハッシュ・テーブルを再構成して、「見つけられることのない」アイテムがテーブルの中で放置されないように、すべての競合を確認する。すべてのデータの実体に変更を加えなかったとしても、オリジナルのキーの順序は保証されない。以下のループが実行された場合、いくつかのキーが見つけられないことが起こり得る。
key = gdbm_firstkey ( dbf );
while ( key.dptr ) {
nextkey = gdbm_nextkey ( dbf, key );
if ( some condition ) {
gdbm_delete ( dbf, key );
free ( key.dptr );
}
key = nextkey;
}
以下のルーチンは繰り返し使われるべきではない。
ret = gdbm_reorganize ( dbf )
もしあなたがたくさんの削除を行い、
gdbm ファイルが使っているスペースを小さくしたいと思うならば、このルーチンはデータベースの再構成を行う。
gdbm はこの再構成以外で
gdbm が使っているファイルの大きさを小さくすることは無い。(削除されたスペースは再利用される)
データベースが GDBM_SYNC フラグ付きで open されない限り、gdbm は次の動作を継続する前に、write がディスクにフラッシュするのを待つようなことはしない。次のルーチンはデータベースを物理的にディスクに書き出すことを保証する。
gdbm_sync ( dbf )
これはメインメモリの状態をディスクの状態と同期させるまでは戻って来ない。
gdbm のエラーコードを英文のテキストに変換するには、次のルーチンを利用する。
ret = gdbm_strerror ( errno )
ここで
errno は
gdbm_error 型であり、通常はグローバル変数の
gdbm_errno である。対応するフレーズが返ってくる。
gdbm は既に open されているファイルに対するオプションを設定できる機能をサポートしている。
ret = gdbm_setopt ( dbf, option, value, size )
ここで、
dbf は直前の
gdbm_open の返り値であり、
option は設定したいオプションを指定する。現在の正しいオプションは：
GDBM_CACHESIZE -内部の bucket キャッシュのサイズを指定する。このオプションは
GDBM_FILE のディスクリプタに一度だけ設定でき、データベースの最初のアクセス時に自動的に 100 が設定される。
GDBM_FASTMODE -
fast mode の on, off を指定する。
fast mode はすでにオープンされていて、アクティブなデータベースに対してトグル (on, off) できる。
value (以下参照) は TRUE か FALSE が設定できる。
このオプションはもう使われない。
GDBM_SYNCMODE -ファイルシステムの同期処理を on, off する。この設定のデフォルトは off である。
value (以下参照) は TRUE か FALSE を指定する。
GDBM_CENTFREE -
central フリーブロックプール を on, off する。デフォルトは off であり、これは以前のバージョンの
gdbm のフリーブロックの取り扱いと同じである。もし、設定されると、このオプションはその後はフリーブロックはグローバルプールにおかれ、(理論的には) より多くのファイルスペースがより早く再利用されるようになる。
value (以下参照) は TRUE か FALSE を設定すべきである。
注意：この機能はまだ検討中である。
GDBM_COALESCEBLKS -
フリーブロックマージングの on, off を設定する。デフォルトは off で前のバージョンの
gdbm のフリーブロックの扱いと同じである。もし、設定されるとこのオプションは、付近にあるフリーブロックをマージする。これは特に
GDBM_CENTFREE と一緒に使われたとしても時間と CPU のかかる処理になる。
value (以下参照) は TRUE か FALSE を設定するべきである。
注意：この機能はまだ検討中である。
value は
option に設定する値であり、integer へのポインタである。
size は
value によってポイントされるデータのサイズである。返り値は失敗した場合-1 になり、成功したら 0 になる。失敗の場合、グローバル変数の
gdbm_errno には値が設定される。
例えば、
gdbm_open でオープンしたデータベースをアクセスする前に、キャッシュとして 10 を使うように設定する場合、以下のコードが利用できる：
int value = 10;
ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));
もしデータベースが
GDBM_NOLOCK フラグ付きでオープンされた場合、ユーザはデータベースに対して、例えば複数のライタ操作を同一のファイルに対して行うような、自分の独自のファイルロッキングを使うことができる、
これをサポートするため、
gdbm_fdesc ルーチンが提供される。
ret = gdbm_fdesc ( dbf )
ここで
dbf は以前の
gdbm_open の返り値である。返り値はデータベースのファイルディスクリプタである。
以下の 2 つの外部変数は役に立つことだろう。
gdbm_errno は gdbm のエラーに関するより詳しい情報を持つ (gdbm.h はエラー値の定義と gdbm_errno を外部変数とする定義を持つ)。
gdbm_version はバージョン情報の文字列を持つ。
もう少し興味深いことが幾つかある。まず
gdbm は「隙間のある」ファイルでは無いということである。あなたはこのファイルを UNIX の
cp(1) コマンドによってコピーすることが可能で、そのコピー処理の間にファイルサイズが拡張されるようなことはない。さらに、UNIX ですでに使われている
dbm のコンパチブルモードが存在する。このコンパチブルモードでは、gdbm のファイルポインタはプログラマに取って必要ではなく、一度には 1 つのファイルだけがオープンされる。コンパチブルモード全ての利用者はライタと見なされる。もし、
gdbm ファイルがリードオンリーならば、ライタとしては失敗し、リーダとしてオープンし直しを試みる。datum 構造体のすべてのポインタは、
gdbm が解放するであろうデータを指す。これらは (標準的な UNIX の
dbm がするように) 静的ポインタとして扱う必要がある。