DBOPEN(3)

名称
dbopen - データベースアクセス方式

書式
<sys/types.h> <limits.h> <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 つまたは複数のポインタを 取ることもあります。

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) への引数として安全に使用できます。 ファイル記述子は、必ずしもアクセス方式が使用している基本ファイルに 関連付けられている必要はありません。ファイル記述子は メモリデータベース内で利用できません。 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 構造体の要素は次のように定義されます。

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

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

関連項目
btree(3), hash(3), mpool(3), recno(3) LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.

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

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

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