GDBM - GNUデータベース・マネージャ。dbm および ndbm互換機能を含 む。(Version 1.7.3.)
#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;
dbm 互換ルーチン
#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互換ルーチン
#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つのファイルは、ただ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 には以下のいずれかの値を使用する。
下から3つ（データベースへのライタ）に関しては、読み書きの際に GDBM_FAST という特別な値をビットORにより追加することができる。これを 指定すると、gdbmは書き込む際にディスクファイルとの同期を取らない。これ により書き込みが早くなるが、ライタ・プロセスの予期せぬ異常終了によりデ ータベースが不整合を起こすことがあるかもしれない。
modeはファイルを生成する際のモードである（chmod(2)およびopen(2) を参照）。(*Fatal_func) ()はdbm が致命的エラーを検出した場合のハンドラ 関数である。この関数へは1つの文字列を渡すことができる。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 はキーに関連付けられたデータである。flagは以下のいずれかの値を 持つことができる。
リーダがgdbm_storeをコールした場合、返り値は -1 となる。 GDBM_INSERT がコールされた時にデータベースにキーが存在すると、返り値は 1 である。そうでなければ返り値は 0 である。
あるデータを検索するには、以下のようにする。
content = gdbm_fetch ( dbf, key )
dbf はgdbm_open から返ってきたポインタである。key はキーデータ である。
返り値のdptr要素がNULLの場合、データは存在しない。見つかった場 合はデータでのポインタが返る。dptrの記憶空間はmalloc(3) により確保され る。gdbmは自動的にこのデータをfreeしない。このデータを使い終わったらそ の領域をfreeするのはプログラマの責任である。
あるデータを検索するだけで取り出さない場合は、以下のようにする。
ret = gdbm_exists ( dbf, key )
dbf はgdbm_open から返ってきたポインタである。key は検索したい キーデータである。データベース内にキーが見つかれば、返り値はtrueである。 見つからなければ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(3) により確保されたデータであり、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_open コールにおいてGDBM_FAST 値を使った場合、以下のルーチ ンにより、データベースがディスクファイルに物理的に書き込まれることが保 証される。
gdbm_sync ( dbf )
ディスクファイルの状態とデータベースのメモリの状態との同期が取 れるまで、この関数は戻って来ない。
gdbmのエラーコードを英語のテキストに変換するには、以下のルーチ ンを使う。
ret = gdbm_strerror ( errno )
errno はgdbm_errorタイプで、通常gdbm_errnoグローバル変数である。 対応する文が返される。
gdbmでは、すでにオープンされているデータベースに対する特定のオ プションを設定するために、以下の関数がサポートされている。
ret = gdbm_setopt ( dbf, option, value, size )
dbf は前回のgdbm_open の返り値である。optionはセットしたいオプ ションである。有効なオプションは、現在のところ以下の通りである。
value は整数へのポインタで、オプションに対する値を指定する。 sizeはvalue が指しているデータのサイズである。コールに失敗すると -1 が 返され、成功した場合は 0 が返される。その場合グローバル変数gdbm_errno がセットされる。
たとえば、すでにgdbm_open でオープン済みのデータベースに対して、 アクセスするのに先だってキャッシュサイズ 10 を指定したい場合、以下のよ うなコードになる。
int value = 10;
ret = gdbm_setopt(dbf, GDBM_CACHESIZE, &value, sizeof(int));
以下の2つの外部変数を使うと便利である。
gdbm_errnoはgdbmエラーに関する詳細情報がセットされる。エラーの 値と外部変数としてのgdbm_errnoの定義はgdbm.hにある。
gdbm_versionはバージョン情報を保持する文字列である。
もうすこし興味をそそられる情報がある。まず、gdbmファイルは「隙 間のある」ファイルではないということである。UNIXのcp(1) コマンドでコピ ーしても、コピー中にサイズが大きくなるようなことはない。また、すでに UNIXのdbm を使っているプログラムに対する互換モードというのがある。この 互換モードでは、プログラマはgdbmファイルのポインタを必要とせず、また同 時に1つのファイルだけをオープンできる。互換モードにおいては、すべての ユーザはライタであるとみなされる。gdbmファイルがリードオンリーである場 合、ライタとしてはオープンに失敗するが、リーダとして再試行される。 datum 構造体中の返されたすべてのポインタは、gdbmがfreeしてくれるデータ を指している。それらは（標準のUNIXのdbm がそうであるように）、「静的な」 ポインタであるように取り扱う必要がある。
このライブラリは、コンパイル行の最後のパラメータに -lgdbm を指 定することによりアクセスされる。
gcc -o prog prog.c -lgdbm
by Philip A. Nelson. Copyright (C) 1990 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 author by:
e-mail: phil@wwu.edu
us-mail: Philip A. Nelson
Computer Science Department
Western Washington University
Bellingham, WA 98226
You may contact the current maintainer by:
e-mail: downsj@CSOS.ORST.EDU