dbopen(3)

dbopen − データベースアクセス方式

#include <sys/types.h>
#include <limits.h>
#include <db.h>

DB *

dbopen(const char *file, int flags, int mode, DBTYPE type, const void *openinfo);

解説

dbopen() は、データベースファイルへのライブラリインタフェースです。サポー トされているファイルフォーマットは、 btree 形式、ハッシュ形式、UNIX ファ イル指向形式です。 btree フォーマットは、ソート済みのバランスのとれたツ リー構造の表現です。ハッシュフォーマットは、拡張可能で動的なハッシュス キーマです。フラットファイルフォーマットは、固定長または可変長レコードか らなるバイトストリームファイルです。フォーマットおよびファイルフォーマッ トに固有の情報については、それぞれのマニュアルページに詳しく述べられてい ます。 btree(3), hash(3), recno(3) です。

dbopen() は、読み込みまたは書き込み用に 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 構造体を指すポインタを返し、エラーの場合 にはヌルを返します。 DB 構造体は、インクルードファイル ⟨db.h⟩ 内に定義さ れており、少なくとも次のフィールドが含まれています。

typedef struct {

DBTYPE type;

int (*close)(const DB *db);

int (*del)(const DB *db, const DBT *key, u_int flags);

int (*fd)(const DB *db);

int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);

int (*put)(const DB *db, DBT *key, const DBT *data,

u_int flags);

int (*sync)(const DB *db, u_int flags);

int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);

} DB;

これらの要素は、データベースタイプと各種のアクションを実行する関数のセッ トを記述しています。これらの関数は、 dbopen() によって返された構造体への ポインタを引数に取り、時々キー / データ構造とフラグ値を指す 1 つまたは複 数のポインタを取ることもあります。

基本アクセス方式 (およびファイルフォーマット) のタイプ。

close
キャッシュされた情報をディスクにフラッシュし、割り振られたリソー スを解放し、基になっているファイル (1 つまたは複数) を閉じるルー チンを指すポインタ。キー / データの組はメモリにキャッシュされるの で、ファイルを close 関数または sync 関数でファイルを同期するのに 失敗すると、情報に矛盾や欠落が生じるかもしれません。 close ルーチ ンは、エラー終了時には -1 を返し ( errno を設定)、正常終了時には 0 を返します。

del
キー / データの組をデータベースから削除するルーチンを指すポイン タ。

パラメータ flags は次の値に設定できます。

R_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
キー / データの組をデータベース内に保存するルーチンを指すポイン タ。

パラメータ flags には次の値の 1 つを設定できます。

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_IAFTER と R_IBEFORE は DB_RECNO アクセス方式にだけ利用できま す。どれも、アクセス方式が新しいキーを作成できることを意味してい るからです。これは、キーが順序付けられており独立な場合にだけ真と なります。たとえば、レコード番号です。

put ルーチンのデフォルトの動作は、新しいキー/データの組を入力し、 それ以前に存在していたキーを置き換えることです。

put ルーチンはエラー終了時には -1 を返し ( errno を設定)、正常終 了時には 0 を返し、 R_NOOVERWRITE フラグが設定されていて、しかも キーがファイル内に既に存在する場合は 1 を返します。

seq
データベースからのシーケンシャルな取り出し用インタフェースである ルーチンを指すポインタ。キーのアドレスと長さは key が参照する構造 体内に返され、データのアドレスと長さは data が参照する構造体内に 返されます。

シーケンシャルなキー / データの組の取り出しは、いつでも開始するこ とができ、 ‘‘カーソル’’ の位置は del, get, put, sync の各ルーチン による呼び出しによって影響を受けません。シーケンシャルな走査の間 のデータベースの修正は走査に反映されます。すなわち、カーソルの前 に挿入されたレコードが返されるまでの間、カーソルの後ろに挿入され たレコードは返されません。

flags 値は次の値の 1 つにセットしなければ なりません。

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 の各アク セス方式についてだけです。これらはそれぞれキーに変化しない固有の 順序があることを意味しているからです。

seq ルーチンはエラー終了時には -1 を返し ( errno を設定)、正常終 了時には 0 を返し、指定のキーまたは現在のキーより小さいかまたは大 きいキー / データの組が存在しない場合は 1 を返します。 DB_RECNO アクセス方式が使用されていて、しかもデータベースファイルがキャラ クタ特殊ファイルであり、完全なキー / データの組がその時点で存在し ない場合、 seq ルーチンは 2 を返します。

sync
キャッシュされた情報をディスクにフラッシュするルーチンを指すポイ ンタ。データベースがメモリ内にだけ存在する場合、 sync ルーチンに は何の効果もなく、処理は常に正常終了します。

flags 値は次の値にセットできます。

R_RECNOSYNC
DB_RECNO アクセス方式が使用される場合、このフラグは sync ルーチンが、 recno ファイル自身ではなく、 recno ファイル の基となる btree ファイルに適用されるようにします (詳細に ついては recno(3) マニュアルページの bfname フィールドを 参照してください)。

sync ルーチンはエラー終了時には -1 を返し ( errno を設定)、正常終 了時には 0 を返します。

キー / データの組

すべてのファイルタイプへのアクセスはキー / データの組を基にしています。 キーとデータの両方が次のデータ構造で表されます。

typedef struct {

void *data;

size_t size;

} DBT;

DBT 構造体の要素は次のように定義されます。

バイトストリングを指すポインタ。

size
バイトストリングの長さ。

キーとデータバイトストリングは、同時に利用できるメモリにフィットする必要 はありますが、参照できる文字列の長さには本質的には制限がありません。アク セス方式は、バイトストリングのバイトアラインについては何の保証もしていな いことに注意すべきです。

エラー

dbopen() ルーチンがエラー終了すると、ライブラリルーチン open(2) や malloc(3) で書かれているエラー、または下記のエラーに対する errno をセット します。

ファイルのフォーマットが間違っています。

[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 ルーチンは、メモリ内のデータベースでエラー終了すると、 ENOENT に errno をセットします。

sync ルーチンがエラー終了すると、ライブラリルーチン fsync(2) に書かれてい るエラーについての errno をセットします。

関連項目

btree(3), hash(3), mpool(3), recno(3)

typedef DBTs は、 ‘‘data base thang’’ の略称で、まだ使用されていない合理 的な名前を誰も思いつかなかったために使われることになりました。

ファイル記述子インタフェースは構成が調和しておらず、インタフェースの今後 のバージョンでは削除される予定です。

どのアクセス方式も、並行アクセス、ロック、またはトランザクションは、どの ような形式でも提供しません。

FreeBSD 10.0 January 2, 1994 FreeBSD 10.0