manページ  — DBOPEN

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 つまたは複数のポインタを 取ることもあります。

type
	基本アクセス方式 (およびファイルフォーマット) のタイプ。
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) への引数として安全に使用できます。 ファイル記述子は、必ずしもアクセス方式が使用している基本ファイルに 関連付けられている必要はありません。ファイル記述子は メモリデータベース内で利用できません。 amp;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 を返します。

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 をセットします。

Margo Seltzer, Michael Olson, USENIX proceedings, LIBTP: Portable, Modular Transactions for UNIX, Winter 1992.