Provided by: manpages-ja-dev_0.5.0.0.20210215+dfsg-1_all bug

名前

       dbopen - データベースアクセスメソッド

書式

       #include <sys/types.h>
       #include <limits.h>
       #include <db.h>
       #include <fcntl.h>

       DB *dbopen(const char *file, int flags, int mode, DBTYPE type,
                  const void *openinfo);

説明

       大事な注意:  このページは、バージョン 2.1 までの glibc が提供するインターフェースに ついて
       説明している。バージョン 2.2 以降の glibc では、もはやこれらの  インターフェースは提供され
       ていない。おそらく、このページではなく、  libdb  ライブラリが提供する API をお探しなのだろ
       う。

       dbopen()  はデータベースファイルに対するライブラリインターフェースである。  サポートされて
       いるファイルフォーマットは  btree,  hash, UNIX ファイルに指向したフォーマット, の 3 つであ
       る。  btree  フォーマットは、ソートされたバランスツリー構造である。  hashed   フォーマット
       は、拡張可能な動的  hash スキームである。 フラットファイル (flat-file) フォーマットは、 固
       定長/可変長のレコードからなるバイトストリームファイルである。       それぞれのフォーマット
       と、ファイルフォーマットに特有の情報は それぞれ対応するマニュアルページ btree(3), hash(3),
       recno(3)  に詳細に記述されている。

       dbopen()  は file を読み込み (読み書き) するためにオープンする。 file 引き数を NULL にすれ
       ば、 ディスク上に保存したくないファイルを作ることもできる。

       flagsmode 引き数は 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 構造体へのポインターを、エラーの場合 NULL を返す。 DB 構造体
       は  <db.h>  インクルードファイルの中で定義されており、  少なくとも以下のようなフィールドを
       持っている。

           typedef struct {
               DBTYPE type;
               int (*close)(const DB *db);
               int (*del)(const DB *db, const DBT *key, unsigned int flags);
               int (*fd)(const DB *db);
               int (*get)(const DB *db, DBT *key, DBT *data,
                          unsigned int flags);
               int (*put)(const DB *db, DBT *key, const DBT *data,
                          unsigned int flags);
               int (*sync)(const DB *db, unsigned int flags);
               int (*seq)(const DB *db, DBT *key, DBT *data,
                          unsigned int flags);
           } DB;

       各要素には、データベースのタイプと、 様々な動作をする関数のセットが記述されている。 これら
       の関数は dbopen() によって返される構造体へのポインターを引き数にとる。 キー/データ構造体へ
       のポインターやフラグ値を取るものもある。

       type   用いられているアクセスメソッド (とファイルフォーマット) の型。

       close  キャッシュされた情報をディスクに掃きだすためのルーチンへのポインター。 割り当てられ
              たリソースを解放し、利用したファイル(群)をクローズする。  キー/データ対がメモリーに
              キャッシュされている場合、 closesync 関数での同期に失敗すると、情報に矛盾が生じ
              るか情報を失う可能性がある。 close ルーチンはエラーの場合 -1 を返し (errno をセット
              する)、成功すると 0 を返す。

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

              flag 引き数は次の値がセットできる。

              R_CURSOR
                     カーソル (cursor) が参照しているレコードを削除する。  カーソルは前もって初期
                     化されていなくてはならない。

              delete  ルーチンはエラーの場合  -1  を返し  (errno をセットする)、成功すると 0 を返
              す。また指定の key がファイル中に無い場合 1 を返す。

       fd     用いているデータベースのファイルディスクリプターを返すルーチン へのポインター。  同
              じファイル名 filedbopen() を呼び出した全てのプロセスに対して、 そのファイルを示
              す単一のファイルディスクリプターが返される。 このファイルディスクリプターはロック関
              数 fcntl(2)  と flock(2)  への引き数として安全に使用できる。 このファイルディスクリ
              プターは、必ずしもアクセスメソッドで 用いられているファイルのいずれかに関連づけられ
              ていなくても良い。  メモリー内のデータベースにはファイルディスクリプターは無い。 fd
              ルーチンはエラーの場合 -1 を返し (errno をセットする)、成功するとファイルディスクリ
              プターを返す。

       get    データベースからキーを用いてデータを取り出すための  ルーチンへのポインター。 指定し
              た key に関連づけられたデータのアドレスと長さが  data  が参照する構造体に返される。
              get  ルーチンはエラーの場合 -1 を返し (errno をセットする)、成功すると 0 を返す。ま
              た key がファイル中に無い場合 1 を返す。

       put    キー/データ対をデータベースに納めるルーチンへのポインター。

              flag 引き数には次の値のうちのどれか一つがセットできる。

              R_CURSOR
                     カーソルが参照しているキー/データ対を置き換える。 カーソルは前もって初期化さ
                     れている必要がある。

              R_IAFTER
                     key  で参照されるデータの直後に、  新しいキー/データ対を作ってデータを追加す
                     る。    追加されたキー/データ対のレコード番号は    key    構造体に返される。
                     (DB_RECNO アクセス方法でのみ使える。)

              R_IBEFORE
                     key  で参照されるデータの直前に、  新しいキー/データ対を作ってデータを挿入す
                     る。    追加されたキー/データ対のレコード番号は    key    構造体に返される。
                     (DB_RECNO アクセスメソッドでのみ使える。)

              R_NOOVERWRITE
                     キーがあらかじめ存在しない場合に限り、新しいキー/データ対をいれる。

              R_SETCURSOR
                     キー/データ対を納め、それを指すようにカーソル位置をセットあるいは初期   化す
                     る。 (DB_BTREEDB_RECNO アクセスメソッドでのみ使える。)

              R_SETCURSORDB_BTREEDB_RECNO  アクセスメソッドでしか利用できない。  なぜなら
              R_SETCURSOR を用いるには、変更される事の無い固有の順序をキー が持っていなければなら
              ないからである。

              R_IAFTERR_IBEFOREDB_RECNO アクセスメソッドでしか利用できない。 これらを実現
              するには、アクセスメソッドが  新しいキーを作れなければならないからである。 これが成
              立するのは、例えば、順序づけらた独立なレコード番号が キーになっているような場合だけ
              である。

              put  ルーチンのデフォルトの動作は、新しいキー/データ対を 既に存在するキーを置き換え
              る事て格納する動作である。

              put ルーチンはエラーの場合 -1 を返し (errno をセットする)、成功すると 0  を返す。ま
              た flagR_NOOVERWRITE がセットされていてキーが既に存在する場合 1 を返す。

       seq    データベースからシーケンシャルにデータを取り出すための     ルーチンへのポインター。
              キーのアドレスと長さが   key   が参照する構造体に返される。データのアドレスと長さが
              data が参照する構造体に返される。

              シーケンシャルなキー/データ対の取得はいつでも行える。また 「カーソル」の位置は del,
              get, put, sync ルーチンの呼び出しには影響されない。  シーケンシャルなスキャンの途中
              に行われたデータベースへの変更は スキャンに反映される。すなわち、カーソルの後ろに挿
              入されたレコードは 返されないが、カーソルの前に挿入されたレコードは返される。

              フラグ値には必ず以下に示すうちの どれか一つをセットしなければならない。

              R_CURSOR
                     指定したキーに関連づけられたデータが返される。 get  ルーチンとの違いは、カー
                     ソルがキーの位置にセットあるいは 初期化される点である。 (注意: DB_BTREE アク
                     セス方法では、返されたキーが  必ずしも指定したキーに正しくマッチしないかもし
                     れない。 返されたキーは、指定されたキーに等しいかより大きいもののうち 最小の
                     ものになる (部分キーマッチか範囲検索が許可されている場合)。)

              R_FIRST
                     データベースの最初のキー/データ対が返される。 カーソルはそれを参照するように
                     セットまたは初期化される。

              R_LAST データベースの最後のキー/データ対が返される。カーソルはそれを参照する ように
                     セットまたは初期化される。 (DB_BTREEDB_RECNO  アクセスメソッドだけで使え
                     る。)

              R_NEXT カーソル直後のキー/データ対を取得する。   カーソルがセットされていない場合は
                     R_FIRST フラグと同じ。

              R_PREV カーソル直前のキー/データ対を取得する。   カーソルがセットされていない場合は
                     R_LAST フラグと同じ。 (DB_BTREEDB_RECNO アクセスメソッドだけで使える。)

              R_LASTR_PREV  は、 DB_BTREEDB_RECNO アクセス方法でしか使えない。 なぜなら
              R_SETCURSOR  を用いるには、変更される事の無い固有の順序をキーが持っていなければなら
              ないからである。

              seq  ルーチンはエラーの場合  -1 を返し (errno をセットする)、 成功の場合 0 を返す。
              指定したキーやカレントキーよりも大きい/小さいキー/データ対がない場合は  1  を返す。
              DB_RECNO  アクセスメソッドを使っていて、 かつデータベースファイルが文字型のスペシャ
              ルファイルで、 完成しているキー/データ対が無い場合には、 seq ルーチンは 2 を返す。

       sync   キャッシュされた情報をディスクに掃き出すルーチンへのポインター。 データベースがメモ
              リーの中だけにある場合、 sync ルーチンは何の効果もなく常に成功する。

              flag には以下の値がセットできる。

              R_RECNOSYNC
                     DB_RECNO アクセスメソッドを使っている場合に このフラグをセットすると、 recno
                     ファイルそのものにではなく、 そのベースになっている btree ファイルに sync が
                     行われる。  (詳細は 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 ルーチンはメモリー内データベースに対し失敗すると errnoENOENT をセットする。

       sync ルーチンは失敗するとライブラリルーチン fsync(2)  で指定されているエラーに応じた errno
       をセットする。

バグ

       typedef  DBT は “data base thang”の略語であるが、これが使われているのは、 まだ使われていな
       い妥当な名前が思い付かなかったためである。

       ファイルディスクリプターを使ったやりとりはひどい代物であり、  将来のバージョンでは削除され
       るだろう。

       どのアクセスメソッドも、同時アクセス、ロック、トランザクション の仕組みは備えていない。

関連項目

       btree(3), hash(3), mpool(3), recno(3)

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

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部  である。プロジェクト
       の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。