Man page - gdbm(3)

Packages contains this manual

Package:  libgdbm-dev
apt-get install libgdbm-dev

Manuals in package:
• gdbm(3)
Documentations in package:
• libgdbm-dev

Available languages:

en ja

Manual

GDBM

名 前
書 式
説 明
リ ン ク
バ グ
関 連 項 目
著 者

---

名 前

GDBM - GNUデ ー タ ベ ー ス ・ マ ネ ー ジ ャ 。 dbm お よ び ndbm 互 換 機 能 を 含 む 。 (Version 1.8.3.)

書 式

#include <gdbm.h>

extern gdbm_error
gdbm_errno

extern char
*gdbm_version

GDBM_FILE
gdbm_open (name, block_size, read_write, mode, fatal_func)
char * name;
int block_size, read_write, mode;
void (*fatal_func) ();

void
gdbm_close (dbf)
GDBM_FILE dbf;

int
gdbm_store (dbf, key, content, flag)
GDBM_FILE dbf;
datum key, content;
int flag;

datum
gdbm_fetch (dbf, key)
GDBM_FILE dbf;
datum key;

int
gdbm_delete (dbf, key)
GDBM_FILE dbf;
datum key;

datum
gdbm_firstkey (dbf)
GDBM_FILE dbf;

datum
gdbm_nextkey (dbf, key)
GDBM_FILE dbf;
datum key;

int
gdbm_reorganize (dbf)
GDBM_FILE dbf;

void
gdbm_sync (dbf)
GDBM_FILE dbf;

int
gdbm_exists (dbf, key)
GDBM_FILE dbf;
datum key;

char *
gdbm_strerror (errno)
gdbm_error errno;

int
gdbm_setopt (dbf, option, value, size)
GDBM_FILE dbf;
int option;
int *value;
int size;

int
gdbm_fdesc (dbf)
GDBM_FILE dbf;

DBM Compatability routines:

#include <dbm.h>

int
dbminit (name)
char *name;

int
store (key, content)
datum key, content;

datum
fetch (key)
datum key;

int
delete (key)
datum key;

datum
firstkey ()

datum
nextkey (key)
datum key;

int
dbmclose ()

NDBM Compatability routines:

#include <ndbm.h>

DBM
*dbm_open (name, flags, mode)
char *name;
int flags, mode;

void
dbm_close (file)
DBM *file;

datum
dbm_fetch (file, key)
DBM *file;
datum key;

int
dbm_store (file, key, content, flags)
DBM *file;
datum key, content;
int flags;

int
dbm_delete (file, key)
DBM *file;
datum key;

datum
dbm_firstkey (file)
DBM *file;

datum
dbm_nextkey (file)
DBM *file;

int
dbm_error (file)
DBM *file;

int
dbm_clearerr (file)
DBM *file;

int
dbm_pagfno (file)
DBM *file;

int
dbm_dirfno (file)
DBM *file;

int
dbm_rdonly (file)
DBM *file;

説 明

GNU dbm は 、 キ ー と デ ー タ の ペ ア を 含 ん だ デ ー タ フ ァ イ ル を 取 り 扱 う ル ー チ ン 群 の ラ イ ブ ラ リ で あ る 。 提 供 さ れ る ア ク セ ス と し て は 、 キ ー に よ る 格 納 、 キ ー に よ る 取 り 出 し 、 キ ー に よ る 削 除 の 他 、 す べ て の キ ー に 渡 る ソ ー ト さ れ て い な い 横 断 的 な ア ク セ ス が あ る 。 一 つ の プ ロ セ ス か ら は 複 数 の デ ー タ フ ァ イ ル を 同 時 に 利 用 す る こ と が で き る 。

gdbm フ ァ イ ル を オ ー プ ン す る プ ロ セ ス は 、 「 リ ー ダ 」 ま た は 「 ラ イ タ 」 と 呼 ば れ る 。 1 つ の gdbm フ ァ イ ル を オ ー プ ン で き る ラ イ タ は 1 つ だ け だ が 、 リ ー ダ は 複 数 が 1 つ の gdbm フ ァ イ ル を オ ー プ ン す る こ と が で き る 。 リ ー ダ と ラ イ タ は 同 時 に 同 じ フ ァ イ ル を オ ー プ ン す る こ と は で き な い 。 gdbm フ ァ イ ル を オ ー プ ン す る 手 続 き は 次 の 通 り で あ る 。

GDBM_FILE dbf;

dbf = gdbm_open ( name, block_size, read_write, mode, fatal_func )

name は フ ァ イ ル の 名 前 で あ る 。 (完 全 な 名 前 、 gdbm は こ の 名 前 に 文 字 列 を 付 け 加 え る よ う な こ と は し な い ) block_size は デ ィ ス ク か ら メ モ リ へ 1 回 に 転 送 さ れ る サ イ ズ で あ る 。 こ の パ ラ メ ー タ は 、 新 し い フ ァ イ ル の 場 合 以 外 は 無 視 さ れ る 。 最 小 サ イ ズ は 512 で あ る 。 512 よ り も 小 さ い 場 合 に は , gdbm は フ ァ イ ル シ ス テ ム に 対 す る stat の ブ ロ ッ ク サ イ ズ を 使 用 す る 。 read_write に は 以 下 の い ず れ か の 値 を 取 る 。
GDBM_READER リ ー ダ
GDBM_WRITER ラ イ タ
GDBM_WRCREAT ラ イ タ - デ ー タ ベ ー ス が 存 在 し な け れ ば 作 成 す る
GDBM_NEWDB ラ イ タ - す で に 存 在 し て も 新 し い デ ー タ ベ ー ス を 作 成 す る
最 後 の 3 つ に つ い て は (デ ー タ ベ ー ス の ラ イ タ ) read_write に 対 し て 以 下 を ビ ッ ト の OR に よ り 追 加 で き る : GDBM_SYNC は す べ て の デ ー タ ベ ー ス の 操 作 を デ ィ ス ク と 同 期 す る 、 ま た GDBM_NOLOCK は デ ー タ ベ ー ス フ ァ イ ル に 関 す る ラ イ ブ ラ リ か ら の ロ ッ ク 動 作 を 行 わ な い 。 オ プ シ ョ ン GDBM_FAST は gdbm の 既 定 動 作 が no-sync モ ー ド に な っ た た め に も う 使 わ れ な く な っ た 。
mode は フ ァ イ ル の モ ー ド で あ る ( chmod(2) お よ び open(2) を 参 照 )。 (*fatal_func) () は dbm が 致 命 的 エ ラ ー を 検 出 し た 場 合 に 呼 び 出 す 関 数 で あ る 。 こ の 関 数 へ の 唯 一 の パ ラ メ ー タ は 文 字 列 で あ る 。 値 0 が 指 定 さ れ る と 、 gdbm は デ フ ォ ル ト の 関 数 を 使 用 す る 。

返 り 値 dbf は 、 そ の gdbm フ ァ イ ル に ア ク セ ス す る 他 の す べ て の ル ー チ ン に 必 要 な ポ イ ン タ で あ る 。 NULL ポ イ ン タ が 返 っ た 場 合 、 gdbm_open は 成 功 し な か っ た こ と を 示 す 。 gdbm の エ ラ ー は gdbm_errno に 、 シ ス テ ム の エ ラ ー は errno に 格 納 さ れ る (エ ラ ー コ ー ド に つ い て は gdbmerrno.h を 参 照 )。

以 下 の す べ て の コ ー ル に お い て は 、 パ ラ メ ー タ dbf は gdbm_open か ら 返 っ て き た ポ イ ン タ で あ る 。

ど ん な フ ァ イ ル で も オ ー プ ン し た も の を ク ロ ー ズ す る こ と は 重 要 で あ る 。 ク ロ ー ズ は フ ァ イ ル に 対 す る リ ー ダ 数 ／ ラ イ タ 数 を 更 新 す る 。 こ れ は 以 下 の よ う に し て 行 う 。

gdbm_close (dbf);

デ ー タ ベ ー ス は 3 つ の 主 な ル ー チ ン に よ っ て 利 用 で き る 。 最 初 は デ ー タ を デ ー タ ベ ー ス に 格 納 す る も の で あ る 。

ret = gdbm_store ( dbf, key, content, flag )

dbf は gdbm_open か ら 返 っ て き た ポ イ ン タ で あ る 。 key は キ ー デ ー タ で 、 content は key に 関 連 付 け ら れ た デ ー タ で あ る 。 flag は 以 下 の い ず れ か の 値 を 持 つ こ と が で き る 。
GDBM_INSERT 挿 入 の み 。 キ ー が 存 在 す れ ば エ ラ ー と な る 。
GDBM_REPLACE キ ー が 存 在 す れ ば 内 容 を 更 新 す る 。

リ ー ダ が gdbm_store を コ ー ル し た 場 合 、 返 り 値 は -1 と な る 。 GDBM_INSERT が 指 定 さ れ た 時 に デ ー タ ベ ー ス に key が 存 在 す る と 、 返 り 値 は 1 で あ る 。 そ う で な け れ ば 返 り 値 は 0 で あ る 。

注 意 : 既 に デ ー タ ベ ー ス に 存 在 す る キ ー を 指 定 し て 格 納 す る 場 合 、 GDBM_REPLACE で 呼 び 出 し て い る な ら ば 、 gdbm は 古 い デ ー タ を 新 し い デ ー タ で 置 き 換 え る 。 同 じ キ ー で 2 つ の デ ー タ ・ ア イ テ ム を 得 る こ と は で き な い し 、 ま た gdbm_store が エ ラ ー を 返 す こ と も な い 。

注 意 : gdbm の サ イ ズ は 、 dbm や ndbm と 異 な り 制 限 さ れ な い 。 デ ー タ は 必 要 な だ け 大 き く す る こ と が で き る 。

デ ー タ を 検 索 す る に は 、 以 下 の よ う に す る :

content = gdbm_fetch ( dbf, key )

dbf は gdbm_open か ら 返 っ て き た ポ イ ン タ で あ る 。 key は キ ー デ ー タ で あ る 。

返 り 値 の dptr が NULL の 場 合 、 デ ー タ は 見 つ か ら な か っ た 。 見 つ か っ た 場 合 は デ ー タ へ の ポ イ ン タ が 返 る 。 dptr の 記 憶 空 間 は malloc(3C) に よ り 確 保 さ れ る 。 gdbm は 自 動 的 に こ の デ ー タ を 解 放 す る こ と は し な い 。 必 要 の 無 く な っ た 領 域 を 解 放 す る の は プ ロ グ ラ マ の 責 任 で あ る 。

デ ー タ を 参 照 せ ず に 、 検 索 だ け す る 場 合 に は ：

ret = gdbm_exists ( dbf, key )

dbf は gdbm_open か ら 返 っ て き た ポ イ ン タ で あ る 。 key は 検 索 し た い キ ー デ ー タ で あ る 。

デ ー タ ベ ー ス 内 に key が 見 つ か れ ば 、 返 り 値 ret は true で あ る 。 何 も 対 応 す る も の が 見 つ か ら な け れ ば ret は false で あ る 。 gdbm_fetch で は メ モ リ 確 保 が 行 わ れ る が 、 こ の ル ー チ ン は そ れ を し な い の で 、 レ コ ー ド の 存 在 を チ ェ ッ ク を す る 時 に 役 に 立 つ 。

デ ー タ ベ ー ス か ら あ る デ ー タ を 削 除 す る 場 合 は 、 以 下 の よ う に す る :

ret = gdbm_delete ( dbf, key )

dbf は gdbm_open か ら 返 っ て き た ポ イ ン タ で あ る 。 key は キ ー デ ー タ で あ る 。

ア イ テ ム が 存 在 し な か っ た り 、 要 求 し た の が リ ー ダ だ っ た 場 合 、 返 り 値 は -1 で あ る 。 削 除 に 成 功 す れ ば 返 り 値 は 0 で あ る 。

次 の 2 つ の ル ー チ ン は 、 デ ー タ ベ ー ス 中 の す べ て の ア イ テ ム に ア ク セ ス で き る 。 ア ク セ ス は キ ー 順 で は な い が 、 デ ー タ ベ ー ス 内 で す べ て の キ ー に 各 1 回 ア ク セ ス す る こ と は 保 証 さ れ て い る 。 (ア ク セ ス 順 序 は ハ ッ シ ュ 値 の 順 に な る 。 )

key = gdbm_firstkey ( dbf )

nextkey = gdbm_nextkey ( dbf, key )

dbf は gdbm_open か ら 返 っ て き た ポ イ ン タ で あ る 。 key は キ ー デ ー タ で あ る 。

返 り 値 は ど ち ら も datum 型 で あ る 。 返 り 値 の dptr 要 素 が NULL の 場 合 、 最 初 の キ ー ま た は 次 の キ ー が な か っ た こ と を 示 す 。 返 り 値 の dptr 要 素 が 指 し て い る の は malloc(3C) に よ り 確 保 さ れ た デ ー タ で あ り 、 gdbm は free し て は く れ な い こ と に も う 一 度 注 意 す る こ と 。

こ れ ら の 関 数 は デ ー タ ベ ー ス を リ ー ド オ ン リ ー で 参 照 す る こ と を 意 図 し て い た 。 た と え ば 、 デ ー タ ベ ー ス の 正 当 性 を 確 認 し た り す る よ う な 目 的 で 。

フ ァ イ ル へ の 「 参 照 」 は 「 ハ ッ シ ュ ・ テ ー ブ ル 」 に 基 づ い て い る 。 gdbm_delete は ハ ッ シ ュ ・ テ ー ブ ル を 再 構 成 し て 、 「 見 つ け ら れ る こ と の な い 」 ア イ テ ム が テ ー ブ ル の 中 で 放 置 さ れ な い よ う に 、 す べ て の 競 合 を 確 認 す る 。 す べ て の デ ー タ の 実 体 に 変 更 を 加 え な か っ た と し て も 、 オ リ ジ ナ ル の キ ー の 順 序 は 保 証 さ れ な い 。 以 下 の ル ー プ が 実 行 さ れ た 場 合 、 い く つ か の キ ー が 見 つ け ら れ な い こ と が 起 こ り 得 る 。

key = gdbm_firstkey ( dbf );
while ( key.dptr ) {
nextkey = gdbm_nextkey ( dbf, key );
if ( some condition ) {
gdbm_delete ( dbf, key );
free ( key.dptr );
}
key = nextkey;
}

以 下 の ル ー チ ン は 繰 り 返 し 使 わ れ る べ き で は な い 。

ret = gdbm_reorganize ( dbf )

も し あ な た が た く さ ん の 削 除 を 行 い 、 gdbm フ ァ イ ル が 使 っ て い る ス ペ ー ス を 小 さ く し た い と 思 う な ら ば 、 こ の ル ー チ ン は デ ー タ ベ ー ス の 再 構 成 を 行 う 。 gdbm は こ の 再 構 成 以 外 で gdbm が 使 っ て い る フ ァ イ ル の 大 き さ を 小 さ く す る こ と は 無 い 。 (削 除 さ れ た ス ペ ー ス は 再 利 用 さ れ る )

デ ー タ ベ ー ス が GDBM_SYNC フ ラ グ 付 き で open さ れ な い 限 り 、 gdbm は 次 の 動 作 を 継 続 す る 前 に 、 write が デ ィ ス ク に フ ラ ッ シ ュ す る の を 待 つ よ う な こ と は し な い 。 次 の ル ー チ ン は デ ー タ ベ ー ス を 物 理 的 に デ ィ ス ク に 書 き 出 す こ と を 保 証 す る 。

gdbm_sync ( dbf )

こ れ は メ イ ン メ モ リ の 状 態 を デ ィ ス ク の 状 態 と 同 期 さ せ る ま で は 戻 っ て 来 な い 。

gdbm の エ ラ ー コ ー ド を 英 文 の テ キ ス ト に 変 換 す る に は 、 次 の ル ー チ ン を 利 用 す る 。

ret = gdbm_strerror ( errno )

こ こ で errno は gdbm_error 型 で あ り 、 通 常 は グ ロ ー バ ル 変 数 の gdbm_errno で あ る 。 対 応 す る フ レ ー ズ が 返 っ て く る 。

gdbm は 既 に open さ れ て い る フ ァ イ ル に 対 す る オ プ シ ョ ン を 設 定 で き る 機 能 を サ ポ ー ト し て い る 。

ret = gdbm_setopt ( dbf, option, value, size )

こ こ で 、 dbf は 直 前 の gdbm_open の 返 り 値 で あ り 、 option は 設 定 し た い オ プ シ ョ ン を 指 定 す る 。 現 在 の 正 し い オ プ シ ョ ン は ：

GDBM_CACHESIZE - 内 部 の bucket キ ャ ッ シ ュ の サ イ ズ を 指 定 す る 。 こ の オ プ シ ョ ン は GDBM_FILE の デ ィ ス ク リ プ タ に 一 度 だ け 設 定 で き 、 デ ー タ ベ ー ス の 最 初 の ア ク セ ス 時 に 自 動 的 に 100 が 設 定 さ れ る 。

GDBM_FASTMODE - fast mode の on, off を 指 定 す る 。 fast mode は す で に オ ー プ ン さ れ て い て 、 ア ク テ ィ ブ な デ ー タ ベ ー ス に 対 し て ト グ ル (on, off) で き る 。 value (以 下 参 照 ) は TRUE か FALSE が 設 定 で き る 。 こ の オ プ シ ョ ン は も う 使 わ れ な い 。

GDBM_SYNCMODE - フ ァ イ ル シ ス テ ム の 同 期 処 理 を on, off す る 。 こ の 設 定 の デ フ ォ ル ト は off で あ る 。 value (以 下 参 照 ) は TRUE か FALSE を 指 定 す る 。

GDBM_CENTFREE - central フ リ ー ブ ロ ッ ク プ ー ル を on, off す る 。 デ フ ォ ル ト は off で あ り 、 こ れ は 以 前 の バ ー ジ ョ ン の gdbm の フ リ ー ブ ロ ッ ク の 取 り 扱 い と 同 じ で あ る 。 も し 、 設 定 さ れ る と 、 こ の オ プ シ ョ ン は そ の 後 は フ リ ー ブ ロ ッ ク は グ ロ ー バ ル プ ー ル に お か れ 、 (理 論 的 に は ) よ り 多 く の フ ァ イ ル ス ペ ー ス が よ り 早 く 再 利 用 さ れ る よ う に な る 。 value (以 下 参 照 ) は TRUE か FALSE を 設 定 す べ き で あ る 。 注 意 ： こ の 機 能 は ま だ 検 討 中 で あ る 。

GDBM_COALESCEBLKS - フ リ ー ブ ロ ッ ク マ ー ジ ン グ の on, off を 設 定 す る 。 デ フ ォ ル ト は off で 前 の バ ー ジ ョ ン の gdbm の フ リ ー ブ ロ ッ ク の 扱 い と 同 じ で あ る 。 も し 、 設 定 さ れ る と こ の オ プ シ ョ ン は 、 付 近 に あ る フ リ ー ブ ロ ッ ク を マ ー ジ す る 。 こ れ は 特 に GDBM_CENTFREE と 一 緒 に 使 わ れ た と し て も 時 間 と CPU の か か る 処 理 に な る 。 value (以 下 参 照 ) は TRUE か FALSE を 設 定 す る べ き で あ る 。 注 意 ： こ の 機 能 は ま だ 検 討 中 で あ る 。

value は option に 設 定 す る 値 で あ り 、 integer へ の ポ イ ン タ で あ る 。 size は value に よ っ て ポ イ ン ト さ れ る デ ー タ の サ イ ズ で あ る 。 返 り 値 は 失 敗 し た 場 合 -1 に な り 、 成 功 し た ら 0 に な る 。 失 敗 の 場 合 、 グ ロ ー バ ル 変 数 の gdbm_errno に は 値 が 設 定 さ れ る 。

例 え ば 、 gdbm_open で オ ー プ ン し た デ ー タ ベ ー ス を ア ク セ ス す る 前 に 、 キ ャ ッ シ ュ と し て 10 を 使 う よ う に 設 定 す る 場 合 、 以 下 の コ ー ド が 利 用 で き る ：

int value = 10;

ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));

も し デ ー タ ベ ー ス が GDBM_NOLOCK フ ラ グ 付 き で オ ー プ ン さ れ た 場 合 、 ユ ー ザ は デ ー タ ベ ー ス に 対 し て 、 例 え ば 複 数 の ラ イ タ 操 作 を 同 一 の フ ァ イ ル に 対 し て 行 う よ う な 、 自 分 の 独 自 の フ ァ イ ル ロ ッ キ ン グ を 使 う こ と が で き る 、

こ れ を サ ポ ー ト す る た め 、 gdbm_fdesc ル ー チ ン が 提 供 さ れ る 。

ret = gdbm_fdesc ( dbf )

こ こ で dbf は 以 前 の gdbm_open の 返 り 値 で あ る 。 返 り 値 は デ ー タ ベ ー ス の フ ァ イ ル デ ィ ス ク リ プ タ で あ る 。

以 下 の 2 つ の 外 部 変 数 は 役 に 立 つ こ と だ ろ う 。

gdbm_errno は gdbm の エ ラ ー に 関 す る よ り 詳 し い 情 報 を 持 つ (gdbm.h は エ ラ ー 値 の 定 義 と gdbm_errno を 外 部 変 数 と す る 定 義 を 持 つ )。
gdbm_version は バ ー ジ ョ ン 情 報 の 文 字 列 を 持 つ 。

も う 少 し 興 味 深 い こ と が 幾 つ か あ る 。 ま ず gdbm は 「 隙 間 の あ る 」 フ ァ イ ル で は 無 い と い う こ と で あ る 。 あ な た は こ の フ ァ イ ル を UNIX の cp(1) コ マ ン ド に よ っ て コ ピ ー す る こ と が 可 能 で 、 そ の コ ピ ー 処 理 の 間 に フ ァ イ ル サ イ ズ が 拡 張 さ れ る よ う な こ と は な い 。 さ ら に 、 UNIX で す で に 使 わ れ て い る dbm の コ ン パ チ ブ ル モ ー ド が 存 在 す る 。 こ の コ ン パ チ ブ ル モ ー ド で は 、 gdbm の フ ァ イ ル ポ イ ン タ は プ ロ グ ラ マ に 取 っ て 必 要 で は な く 、 一 度 に は 1 つ の フ ァ イ ル だ け が オ ー プ ン さ れ る 。 コ ン パ チ ブ ル モ ー ド 全 て の 利 用 者 は ラ イ タ と 見 な さ れ る 。 も し 、 gdbm フ ァ イ ル が リ ー ド オ ン リ ー な ら ば 、 ラ イ タ と し て は 失 敗 し 、 リ ー ダ と し て オ ー プ ン し 直 し を 試 み る 。 datum 構 造 体 の す べ て の ポ イ ン タ は 、 gdbm が 解 放 す る で あ ろ う デ ー タ を 指 す 。 こ れ ら は (標 準 的 な UNIX　 の dbm が す る よ う に ) 静 的 ポ イ ン タ と し て 扱 う 必 要 が あ る 。

リ ン ク

こ の ラ イ ブ ラ リ は コ ン パ イ ル 行 の 最 後 の パ ラ メ ー タ と し て -lgdbm を 指 定 す る こ と で 利 用 さ れ る 。

gcc -o prog prog.c -lgdbm

dbm や ndbm と の 互 換 性 ル ー チ ン を 使 い た い 場 合 は 、 gdbm_compat ラ イ ブ ラ リ も リ ン ク し な け れ ば な ら な い 。 例 え ば 、 以 下 の よ う に す る 。

gcc -o prog proc.c -lgdbm -lgdbm_compat

バ グ

関 連 項 目

dbm, ndbm

著 者

Philip A. Nelson と Jason Downs. Copyright (C) 1990 - 1999 Free Software Foundation, Inc.

GDBM is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version.

GDBM is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with GDBM; see the file COPYING. If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

You may contact the original author by:
e-mail: phil@cs.wwu.edu
us-mail: Philip A. Nelson
Computer Science Department
Western Washington University
Bellingham, WA 98226

You may contact the current maintainer by:
e-mail: downsj@downsj.com

---