総合手引 | セクション 3 | English | オプション |
#include <sys/types.h>
#include <limits.h>
#include <db.h>
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 を返します。
typedef struct { void *data; size_t size; } DBT;
DBT 構造体の要素は次のように定義されます。
data | |
バイトストリングを指すポインタ。 | |
size | |
バイトストリングの長さ。 | |
キーとデータバイトストリングは、同時に利用できるメモリにフィットする必要 はありますが、参照できる文字列の長さには本質的には制限がありません。 アクセス方式は、バイトストリングのバイトアラインについては 何の保証もしていないことに注意すべきです。
[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 をセットします。
USENIX proceedings, LIBTP: Portable, Modular Transactions for UNIX, Winter 1992.
, ,ファイル記述子インタフェースは構成が調和しておらず、 インタフェースの今後のバージョンでは削除される予定です。
どのアクセス方式も、並行アクセス、ロック、またはトランザクション は、どのような形式でも提供しません。
DBOPEN (3) | January 2, 1994 |
総合手引 | セクション 3 | English | オプション |
このマニュアルページサービスについてのご意見は Ben Bullock にお知らせください。 Privacy policy.