DBOPEN

Section: C Library Functions (3)
索引 jman

BSD mandoc

名称

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

書式

In sys/types.h In limits.h In db.h Ft DB * Fn dbopen const char *file int flags int mode DBTYPE type const void *openinfo

索引

解説

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

Fn dbopen は、読み込みまたは書き込み用に Fa file をオープンします。ディスク上に保持する必要のないファイルは、ファイルパラメータを NULL に設定することで作成できます。

引数 Fa flags と引数 Fa mode は、 open(2) で指定されものと同じです。しかし、 O_CREAT , O_EXCL , O_EXLOCK , O_NONBLOCK O_RDONLY , O_RDWR , O_SHLOCK O_TRUNC の各フラグだけに意味があります (データベースファイルは O_WRONLY ではオープンできないことに注意してください)。

引数 Fa type は、タイプ Ft DBTYPE (インクルードファイル Aq Pa db.h で定義されています) であり、 DB_BTREE DB_HASH DB_RECNO を設定できます。

引数 Fa openinfo は、アクセス方式のマニュアルページに説明してあるように、アクセス方式に固有の構造を指すポインタです。 Fa openinfo が NULL の場合、各アクセス方式は、システムとアクセス方式に適切なデフォルトを使用します。

Fn dbopen は、処理が成功すると Ft DB 構造体を指すポインタを返し、エラーの場合にはヌルを返します。 Ft DB 構造体は、インクルードファイル Aq Pa 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;

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

type

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

close

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

del

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

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

R_CURSOR: カーソルが参照するレコードを削除します。カーソルは、あらかじめ初期化しておく必要があります。

delete ルーチンはエラー終了時には -1 を返し ( errno を設定)、正常終了時には 0 を返します。指定した Fa key がファイルの中になかった場合は 1 を返します。

fd

基本データベースのファイル記述表現を返すルーチンを指すポインタ。同じファイルを参照しているファイル記述子は、同じ Fa file 名で Fn dbopen を呼び出す全プロセスに返されます。このファイル記述子は、ロック関数 fcntl(2) と flock(2) への引数として安全に使用できます。ファイル記述子は、必ずしもアクセス方式が使用している基本ファイルに関連付けられている必要はありません。ファイル記述子はメモリデータベース内で利用できません。 fd ルーチンは、エラー終了時は -1 を返し ( errno を設定)、正常終了時にはファイル記述子を返します。

get

データベースからキーを使用して取り出すインタフェースであるルーチンを指すポインタ。指定の Fa key に関連付けられたデータのアドレスと長さが、 Fa data で参照される構造体内に返されます。 get ルーチンはエラー終了時には -1 を返し ( errno を設定)、正常終了時には 0 を返します。 Fa key がファイルの中になかった場合は 1 を返します。

put

キー / データの組をデータベース内に保存するルーチンを指すポインタ。

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

R_CURSOR: カーソルが参照するキー / データの組を置き換えます。カーソルは、あらかじめ初期化されている必要があります。
R_IAFTER: Fa key で参照されるデータの直後にデータを追加し、新しいキー / データの組を作成します。追加したキー / データの組のレコード番号が Fa key 構造体内に返されます ( DB_RECNO アクセス方式にだけ適用できます)。
R_IBEFORE: Fa key で参照されるデータの直前にデータを挿入し、新しいキー / データの組を作成します。追加したキー / データの組のレコード番号が Fa 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

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

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

Fa 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 ルーチンには何の効果もなく、処理は常に正常終了します。

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

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

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

索引

キー / データの組

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

typedef struct {
        void *data;
        size_t size;
} DBT;

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

data: バイトストリングを指すポインタ。
size: バイトストリングの長さ。

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

索引

エラー

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

Bq Er EFTYPE: ファイルのフォーマットが間違っています。
Bq Er 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 ルーチンは、メモリ内のデータベースでエラー終了すると、 Er ENOENT に errno をセットします。

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

索引