Provided by: manpages-ja-dev_0.5.0.0.20131015+dfsg-2_all 
名前
dbopen - データベースアクセスメソッド
書式
#include <sys/types.h>
#include <limits.h>
#include <db.h>
#include <fcntl.h>
DB *dbopen(const char *file, int flags, int mode, DBTYPE type,
const void *openinfo);
説明
大事な注意: このページは、バージョン 2.1 までの glibc が提供するインターフェースに ついて説明してい
る。バージョン 2.2 以降の glibc では、もはやこれらの インターフェースは提供されていない。おそらく、この
ページではなく、 libdb ライブラリが提供する API をお探しなのだろう。
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, unsigned int flags);
int (*fd)(const DB *db);
int (*get)(const DB *db, DBT *key, DBT *data,
unsigned int flags);
int (*put)(const DB *db, DBT *key, const DBT *data,
unsigned int flags);
int (*sync)(const DB *db, unsigned int flags);
int (*seq)(const DB *db, DBT *key, DBT *data,
unsigned 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 を返す。また flag に
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 をセットする。
バグ
typedef DBT は “data base thang”の略語であるが、これが使われているのは、 まだ使われていない妥当な名前が思
い付かなかったためである。
ファイルデスクリプタを使ったやりとりはひどい代物であり、 将来のバージョンでは削除されるだろう。
どのアクセスメソッドも、同時アクセス、ロック、トランザクション の仕組みは備えていない。
関連項目
btree(3), hash(3), mpool(3), recno(3)
LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael Olson, USENIX proceedings, Winter
1992.
この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.54 の一部 である。プロジェクトの説明とバグ報告
に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。
4.4 Berkeley Distribution 2012-05-04 DBOPEN(3)