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)