other versions
GDBM(3) | Library Functions Manual | GDBM(3) |
名前¶
GDBM - GNUデータベース・マネージャ。 dbm および ndbm 互換機能を含む。 (Version 1.8.3.)書式¶
#include <gdbm.h> extern gdbm_error説明¶
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_close (dbf); データベースは 3 つの主なルーチンによって利用できる。最初はデータを データベースに格納するものである。
ret = gdbm_store ( dbf, key, content, flag ) dbf は gdbm_open から返ってきたポインタである。 key はキーデータで、content は key に関連付けられた データである。 flag は以下のいずれかの値を持つことができる。
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 を外部変数とする定義を持つ)。
リンク¶
このライブラリはコンパイル行の最後のパラメータとして -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
e-mail: downsj@downsj.com
10/15/2002 |