Man page - dbopen(3)

Packages contains this manual

Available languages:

en fr pt_BR es pl ja ru

Manual

DBOPEN

名 前
書 式
説 明
キ ー /デ ー タ 対
エ ラ ー
バ グ
関 連 項 目
こ の 文 書 に つ い て

名 前

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