書式
#include <gdbm.h>
extern gdbm_error
gdbm_errno
extern char
*gdbm_version
GDBM_FILE
gdbm_open (name, block_size, read_write, mode, fatal_func)
char * name;
int block_size, read_write, mode;
void (*fatal_func) ();
void
gdbm_close (dbf)
GDBM_FILE dbf;
int
gdbm_store (dbf, key, content, flag)
GDBM_FILE dbf;
datum key, content;
int flag;
datum
gdbm_fetch (dbf, key)
GDBM_FILE dbf;
datum key;
int
gdbm_delete (dbf, key)
GDBM_FILE dbf;
datum key;
datum
gdbm_firstkey (dbf)
GDBM_FILE dbf;
datum
gdbm_nextkey (dbf, key)
GDBM_FILE dbf;
datum key;
int
gdbm_reorganize (dbf)
GDBM_FILE dbf;
void
gdbm_sync (dbf)
GDBM_FILE dbf;
int
gdbm_exists (dbf, key)
GDBM_FILE dbf;
datum key;
char *
gdbm_strerror (errno)
gdbm_error errno;
int
gdbm_setopt (dbf, option, value, size)
GDBM_FILE dbf;
int option;
int *value;
int size;
int
gdbm_fdesc (dbf)
GDBM_FILE dbf;
DBM Compatability routines:
#include <dbm.h>
int
dbminit (name)
char *name;
int
store (key, content)
datum key, content;
datum
fetch (key)
datum key;
int
delete (key)
datum key;
datum
firstkey ()
datum
nextkey (key)
datum key;
int
dbmclose ()
NDBM Compatability routines:
#include <ndbm.h>
DBM
*dbm_open (name, flags, mode)
char *name;
int flags, mode;
void
dbm_close (file)
DBM *file;
datum
dbm_fetch (file, key)
DBM *file;
datum key;
int
dbm_store (file, key, content, flags)
DBM *file;
datum key, content;
int flags;
int
dbm_delete (file, key)
DBM *file;
datum key;
datum
dbm_firstkey (file)
DBM *file;
datum
dbm_nextkey (file)
DBM *file;
int
dbm_error (file)
DBM *file;
int
dbm_clearerr (file)
DBM *file;
int
dbm_pagfno (file)
DBM *file;
int
dbm_dirfno (file)
DBM *file;
int
dbm_rdonly (file)
DBM *file;
説明
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 がするように) 静的ポインタとして扱う必要がある。
リンク
このライブラリはコンパイル行の最後のパラメータとして -lgdbm を 指定することで利用される。
gcc -o prog prog.c -lgdbm
dbm や ndbm との互換性ルーチンを使いたい場合は、 gdbm_compat ライブラリもリンクしなければならない。 例えば、以下のようにする。
gcc -o prog proc.c -lgdbm -lgdbm_compat
バグ
著者
Philip A. Nelson と Jason Downs. Copyright (C) 1990 - 1999 Free Software Foundation, Inc.GDBM is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version.
GDBM is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with GDBM; see the file COPYING. If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
You may contact the original author by:
e-mail: [email protected]
us-mail: Philip A. Nelson
Computer Science Department
Western Washington University
Bellingham, WA 98226
You may contact the current maintainer by:
e-mail: [email protected]