Provided by: manpages-ja-dev_0.5.0.0.20140515+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.65 の一部 である。プロジェクトの説明とバグ報告
に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。
4.4 Berkeley Distribution 2012-05-04 DBOPEN(3)