dbopen - ライブラリコールの説明 - Linux コマンド集 一覧表

dbopen - データベースアクセスメソッド

#include <sys/types.h>
#include <limits.h>
#include <db.h>

DB *
dbopen(const char *file, int flags, int mode, DBTYPE type,
const void *openinfo);

dbopen ()はデータベースファイルに対するライブラリインターフェースである。 サポートされているファイルフォーマットは btree, hash, UNIX ファイルに指向したフォーマット, の 3 つである。 btree フォーマットは、ソートされたバランスツリー構造である。 hashed フォーマットは、拡張可能な動的 hash スキームである。 フラットファイル (flat-file) フォーマットは、 固定長/可変長のレコードからなるバイトストリームファイルである。 それぞれのフォーマットと、ファイルフォーマットに特有の情報は それぞれ対応するマニュアルページ   btree (3),   hash (3),   recno (3) に詳細に記述されている。

dbopen ()は file を読み込み (読み書き) するためにオープンする。 file パラメータを NULL にすれば、 ディスク上に保存したくないファイルを作ることもできる。

flags と mode 引数は   open (2) ルーチンで指定するのと同様である。ただし O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK と O_TRUNC フラグだけが意味を持つ。 (注意: O_WRONLY でデータベースファイルを開く事は出来ない)

type 引数は DBTYPE 型である (インクルードファイル <db.h> で定義されている)。 DB_BTREE, DB_HASH, DB_RECNO のいずれかをセットできる。

openinfo 引数はアクセスメソッドに固有な構造体へのポインタである。 それぞれの構造体に関しては各アクセスメソッドの マニュアルページに記述されている。 openinfo が NULL の場合、それぞれのアクセスメソッドとシステムとに適合した デフォルトが用いられる。

dbopen ()は、成功した場合 DB 構造体へのポインタを、エラーの場合 NULL を返す。 DB 構造体は <db.h> インクルードファイルの中で定義されており、 少なくとも以下のようなフィールドを持っている。

typedef struct {

DBTYPE type;
int (*close)(const DB *db);
int (*del)(const DB *db, const DBT *key, u_int flags);
int (*fd)(const DB *db);
int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
int (*put)(const DB *db, DBT *key, const DBT *data,
u_int flags);
int (*sync)(const DB *db, u_int flags);
int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);

} DB;

各要素には、データベースのタイプと、 様々な動作をする関数のセットが記述されている。 これらの関数は dbopen ()によって返される構造体へのポインタを引数にとる。 キー/データ構造体へのポインタやフラグ値を取るものもある。

type

用いられているアクセスメソッド (とファイルフォーマット) の型。

close

キャッシュされた情報をディスクに掃きだすためのルーチンへのポインタ。 割り当てられたリソースを解放し、利用したファイル(群)をクローズする。 キー/データ対がメモリにキャッシュされている場合、 close や sync 関数での同期に失敗すると、情報に矛盾が生じるか情報を失う可能性がある。 close ルーチンはエラーの場合 -1 を返し ( errno をセットする)、成功すると 0 を返す。

del

データベースからキー/データ対を削除するルーチンへのポインタ。
flag 引数は次の値がセットできる。

R_CURSOR

カーソル (cursor) が参照しているレコードを削除する。 カーソルは前もって初期化されていなくてはならない。

delete ルーチンはエラーの場合 -1 を返し ( errno をセットする)、成功すると 0 を返す。また指定の key がファイル中に無い場合 1 を返す。

fd

用いているデータベースのファイルデスクリプタを返すルーチン へのポインタ。 同じファイル名 file で dbopen ()を呼び出した全てのプロセスに対して、 そのファイルを示す単一のファイルデスクリプタが返される。 このファイルデスクリプタはロック関数   fcntl (2) と   flock (2) への引数として安全に使用できる。 このファイルデスクリプタは、必ずしもアクセスメソッドで 用いられているファイルのいずれかに関連づけられていなくても良い。 メモリ内のデータベースにはファイルデスクリプタは無い。 fd ルーチンはエラーの場合 -1 を返し ( errno をセットする)、成功するとファイルデスクリプタを返す。

get

データベースからキーを用いてデータを取り出すための ルーチンへのポインタ。 指定した key に関連づけられたデータのアドレスと長さが data が参照する構造体に返される。 get ルーチンはエラーの場合 -1 を返し ( errno をセットする)、成功すると 0 を返す。また key がファイル中に無い場合 1 を返す。

put

キー/データ対をデータベースに納めるルーチンへのポインタ。
flag 引数には次の値のうちのどれか一つがセットできる。

R_CURSOR

カーソルが参照しているキー/データ対を置き換える。 カーソルは前もって初期化されている必要がある。

R_IAFTER

key で参照されるデータの直後に、 新しいキー/データ対を作ってデータを追加する。 追加されたキー/データ対のレコード番号は key 構造体に返される。 (DB_RECNO アクセス方法でのみ使える。)

R_IBEFORE

key で参照されるデータの直前に、 新しいキー/データ対を作ってデータを挿入する。 追加されたキー/データ対のレコード番号は key 構造体に返される。 (DB_RECNO アクセスメソッドでのみ使える。)

R_NOOVERWRITE

キーがあらかじめ存在しない場合に限り、新しいキー/データ対をいれる。

R_SETCURSOR

キー/データ対を納め、それを指すようにカーソル位置をセットあるいは初期 化する。(DB_BTREE と DB_RECNO アクセスメソッドでのみ使える。)

R_SETCURSOR は DB_BTREE と DB_RECNO アクセスメソッドでしか利用できない。 なぜなら R_SETCURSOR を用いるには、変更される事の無い固有の順序をキー が持っていなければならないからである。
R_IAFTER と R_IBEFORE は DB_RECNO アクセスメソッドでしか利用できない。 これらを実現するには、アクセスメソッドが 新しいキーを作れなければならないからである。 これが成立するのは、例えば、順序づけらた独立なレコード番号が キーになっているような場合だけである。
put ルーチンのデフォルトの動作は、新しいキー/データ対を 既に存在するキーを置き換える事て格納する動作である。
put ルーチンはエラーの場合 -1 を返し ( errno をセットする)、成功すると 0 を返す。また R_NOOVERWRITE フラグ がセットされていてキーが既に存在する場合 1 を返す。

seq

データベースからシーケンシャルにデータを取り出すための ルーチンへのポインタ。 キーのアドレスと長さが key が参照する構造体に返される。データのアドレスと長さが data が参照する構造体に返される。
シーケンシャルなキー/データ対の取得はいつでも行える。また 「カーソル」の位置は del , get , put , sync ルーチンの呼び出しには影響されない。 シーケンシャルなスキャンの途中に行われたデータベースへの変更は スキャンに反映される。すなわち、カーソルの後ろに挿入されたレコードは 返されないが、カーソルの前に挿入されたレコードは返される。
フラグ値には必ず 以下に示すうちの どれか一つをセットしなければならない。

R_CURSOR

指定したキーに関連づけられたデータが返される。 get ルーチンとの違いは、カーソルがキーの位置にセットあるいは 初期化される点である。 (注意: DB_BTREE アクセス方法では、返されたキーが 必ずしも指定したキーに正しくマッチしないかもしれない。 返されたキーは、指定されたキーに等しいかより大きいもののうち 最小のものになる (部分キーマッチか範囲検索が許可されている場合)。)

R_FIRST

データベースの最初のキー/データ対が返される。 カーソルはそれを参照するようにセットまたは初期化される。

R_LAST

データベースの最後のキー/データ対が返される。カーソルはそれを参照する ようにセットまたは初期化される。 (DB_BTREE と DB_RECNO アクセスメソッドだけで使える。)

R_NEXT

カーソル直後のキー/データ対を取得する。 カーソルがセットされていない場合は R_FIRST フラグと同じ。

R_PREV

カーソル直前のキー/データ対を取得する。 カーソルがセットされていない場合は R_LAST フラグと同じ。 (DB_BTREE と DB_RECNO アクセスメソッドだけで使える。)

R_LAST と R_PREV は、DB_BTREE と DB_RECNO アクセス方法でしか使えない。 なぜなら R_SETCURSOR を用いるには、変更される事の無い固有の順序をキー が持っていなければならないからである。
seq ルーチンはエラーの場合 -1 を返し ( errno をセットする)、 成功の場合 0 を返す。 指定したキーやカレントキーよりも大きい/小さいキー/データ対がない場合は 1 を返す。 DB_RECNO アクセスメソッドを使っていて、 かつデータベースファイルが文字型のスペシャルファイルで、 完成しているキー/データ対が無い場合には、 seq ルーチンは 2 を返す。

sync

キャッシュされた情報をディスクに掃き出すルーチンへのポインタ。 データベースがメモリの中だけにある場合、 sync ルーチンは何の効果もなく常に成功する。
flag には以下の値がセットできる。

R_RECNOSYNC

DB_RECNO アクセスメソッドを使っている場合に このフラグをセットすると、 recno ファイルそのものにではなく、 そのベースになっている btree ファイルに sync が行われる。 (詳細は   recno (3) マニュアルページで bfname フィールドを説明している部分を参照のこと。)

sync ルーチンはエラーの場合 -1 を返し ( errno をセットする)、成功すると 0 を返す。

全てのファイルタイプにおいて、 キー/データ対をベースにしてアクセスが行われる。 キーとデータのいずれも、次のデータ構造で記述される。

typedef struct {
void *data;
size_t size;
} DBT;

DBT 構造体の各要素は次のように定義されている。

data

バイト文字列へのポインタ。

size

バイト文字列の長さ。

キーとデータのバイト文字列は、 基本的には無制限の長さの文字列を参照できるが、 しかしいずれも使用可能なメモリに収まっていなくてはならない。 アクセスメソッドはバイト文字列のアラインメントについては 何も保証していない事に注意すること。

dbopen ()ルーチンは失敗するとライブラリルーチン   open (2) と   malloc (3) で指定されているエラーに応じた errno をセットする。あるいは以下をセットする。

[EFTYPE]

ファイルが正しくフォーマットされていない。

[EINVAL]

指定したパラメータ(ハッシュ関数、バイト埋めなど)が現在のファイル仕様に 合っていない、パラメータが関数にとって無意味 (例えばあらかじめ初期化しないでカーソルを使うとか)、 ファイルとソフトウェアのバージョンが合っていない。

close ルーチンは失敗するとライブラリルーチン   close (2),   read (2),   write (2),   free (3),   fsync (2) で指定されているエラーに応じた errno をセットする。

del , get , put と seq ルーチンは失敗するとライブラリルーチン   read (2),   write (2),   free (3),   malloc (3) で指定されているエラーに応じた errno をセットする。

fd ルーチンはメモリ内データベースに対し失敗すると errno に ENOENT をセットする。

sync ルーチンは失敗するとライブラリルーチン   fsync (2) で指定されているエラーに応じた errno をセットする。

  btree (3),   hash (3),   mpool (3),   recno (3) 
LIBTP: Portable, Modular Transactions for UNIX ,Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.

typedef DBT は ``data base thang''の略語であるが、 これが使われているのは、 まだ使われていない妥当な名前が思い付かなかったためである。

ファイルデスクリプタを使ったやりとりはひどい代物であり、 将来のバージョンでは削除されるだろう。

どのアクセスメソッドも、同時アクセス、ロック、トランザクション の仕組みは備えていない。