DBOPEN(3) | FreeBSD Library Functions Manual | DBOPEN(3) |
名称
dbopen — データベースアクセス方式書式
#include < sys/types.h>#include < db.h>
#include < fcntl.h>
#include < limits.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 をオープンします。ディスク上に保持する必要のないファイルは、 file 引数を NULL に設定することで作成できます。
flags 引数と mode 引数は、 open(2) ルーチンで明記されています。しかし、 O_CREAT, O_EXCL, O_EXLOCK, O_NOFOLLOW, O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK, O_SYNC と O_TRUNC の各フラグだけに意味があります (データベースファイルは O_WRONLY ではオープンできないことに注意してください)。
type 引数は、タイプ DBTYPE ( < db.h> インクルードファイルで定義されています) であり、 DB_BTREE, DB_HASH, DB_RECNO を設定できます。
openinfo 引数は、アクセス方式のマニュアルページに説明してあるように、アクセス方式に固有の構造を指すポインタです。 openinfo が NULL の場合、各アクセス方式は、システムとアクセス方式に適切なデフォルトを使用します。
dbopen() 関数は、処理が成功すると DB 構造体を指すポインタを返し、エラーの場合には NULL を返します。 DB 構造体は、 < db.h> インクルードファイルに定義されており、少なくとも次のフィールドが含まれています。
typedef struct { DBTYPE type; int (*close)(DB *db); int (*del)(const DB *db, const DBT *key, u_int flags); int (*fd)(const DB *db); int (*get)(const DB *db, const 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
- キャッシュされた情報をディスクにフラッシュし、割り振られたリソースを解放し、基になっているファイルを閉じるルーチンを指すポインタ。キー/データの組はメモリにキャッシュされるので、ファイルを 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
- バイトストリングの長さ。
キーとデータバイトストリングは、同時に利用できるメモリに 2 つともフィットする必要はありますが、参照できる文字列の長さには本質的には制限がありません。アクセス方式は、バイトストリングの整列については何の保証もしていないことに注意すべきです。
エラー
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 ルーチンは、メモリデータベースでエラー終了すると、 errno を ENOENT にセットします。
sync ルーチンがエラー終了すると、ライブラリルーチン fsync(2) に明記されているエラーを errno にセットします。
関連項目
btree(3), hash(3), mpool(3), recno(3) Margo Seltzer and Michael Olson, LIBTP: Portable, Modular Transactions for UNIX, USENIX proceedings, Winter 1992.バグ
typedef DBT は、“data base thang”の略称で、まだ使用されていない合理的な名前を誰も思いつかなかったために使われることになりました。ファイル記述子インタフェースは適当(kluge)で今後のインタフェースのバージョンでは削除される予定です。
並行アクセス、ロック、またはトランザクション形式のアクセス方式は提供していません。
September 10, 2010 | FreeBSD |