dbのヘルプ・マニュアル
日本語 英語
db --help
man db
DBOPEN(3) Linux Programmer’s Manual DBOPEN(3)
名前
dbopen - データベースアクセスメソッド
書式
#include
#include
#include
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_BTREE, DB_HASH, DB_RECNO のいずれかをセットできる。
openinfo 引き数はアクセスメソッドに固有な構造体へのポインタである。それ
ぞ れの構造体に関しては各アクセスメソッドのマニュアルページに記述されて
いる。 openinfo が NULL の場合、それぞれのアクセスメソッドとシステム と
に適合したデフォルトが用いられる。
dbopen() は、成功した場合 DB 構造体へのポインタを、エラーの場合 NULL を
返す。 DB 構造体は インクルードファイルの中で定義されており、 少
なくとも以下のようなフィールドを持っている。
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.
4.4 Berkeley Distribution 1994-01-02 DBOPEN(3)