名 前
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.79 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は http://www.kernel.org/doc/man−pages/ に 書 か れ て い る 。