Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
GDBM - GNUデータベース・マネージャ。dbm および ndbm 互換機能を含む。 (Version 1.8.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;
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
バグ
関連項目
dbm, ndbm
著者
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: phil@cs.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@downsj.com
10/15/2002 GDBM(3)