release/man3/dbopen.3

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     @(#)dbopen.3    8.5 (Berkeley) 1/2/94
  35 .\"
  36 .\"*******************************************************************
  37 .\"
  38 .\" This file was generated with po4a. Translate the source file.
  39 .\"
  40 .\"*******************************************************************
  41 .\"
  42 .\" Japanese Version Copyright (c) 1999 Shouichi Saito
  43 .\"     all rights reserved.
  44 .\" Translated Thu Jul 22 00:00:00 JST 1999
  45 .\"     by Shouichi Saito <ss236rx@ymg.urban.ne.jp>
  46 .\" Proofed Tue Aug 19 1999 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
  47 .\" Updated 2012-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  48 .\"
  49 .TH DBOPEN 3 2012\-05\-04 "" "Linux Programmer's Manual"
  50 .UC 7
  51 .SH 名前
  52 dbopen \- データベースアクセスメソッド
  53 .SH 書式
  54 .nf
  55 \fB#include <sys/types.h>\fP
  56 \fB#include <limits.h>\fP
  57 \fB#include <db.h>\fP
  58 \fB#include <fcntl.h>\fP
  59
  60 \fBDB *dbopen(const char *\fP\fIfile\fP\fB, int \fP\fIflags\fP\fB, int \fP\fImode\fP\fB, DBTYPE \fP\fItype\fP\fB,\fP
  61 \fB           const void *\fP\fIopeninfo\fP\fB);\fP
  62 .fi
  63 .SH 説明
  64 \fI大事な注意\fP:
  65 このページは、バージョン 2.1 までの glibc が提供するインターフェースに
  66 ついて説明している。バージョン 2.2 以降の glibc では、もはやこれらの
  67 インターフェースは提供されていない。おそらく、このページではなく、
  68 \fIlibdb\fP ライブラリが提供する API をお探しなのだろう。
  69
  70 \fBdbopen\fP()  はデータベースファイルに対するライブラリインターフェースである。 サポートされているファイルフォーマットは btree,
  71 hash, UNIX ファイルに指向したフォーマット, の 3 つである。 btree フォーマットは、ソートされたバランスツリー構造である。
  72 hashed フォーマットは、拡張可能な動的 hash スキームである。 フラットファイル (flat\-file) フォーマットは、
  73 固定長/可変長のレコードからなるバイトストリームファイルである。 それぞれのフォーマットと、ファイルフォーマットに特有の情報は
  74 それぞれ対応するマニュアルページ \fBbtree\fP(3), \fBhash\fP(3), \fBrecno\fP(3)  に詳細に記述されている。
  75 .PP
  76 \fBdbopen\fP()  は \fIfile\fP を読み込み (読み書き) するためにオープンする。 \fIfile\fP 引き数を NULL にすれば、
  77 ディスク上に保存したくないファイルを作ることもできる。
  78 .PP
  79 .\"Three additional options may be specified by ORing
  80 .\"them into the
  81 .\".I flags
  82 .\"argument.
  83 .\".TP
  84 .\"DB_LOCK
  85 .\"Do the necessary locking in the database to support concurrent access.
  86 .\"If concurrent access isn't needed or the database is read-only this
  87 .\"flag should not be set, as it tends to have an associated performance
  88 .\"penalty.
  89 .\".TP
  90 .\"DB_SHMEM
  91 .\"Place the underlying memory pool used by the database in shared
  92 .\"memory.
  93 .\"Necessary for concurrent access.
  94 .\".TP
  95 .\"DB_TXN
  96 .\"Support transactions in the database.
  97 .\"The DB_LOCK and DB_SHMEM flags must be set as well.
  98 \fIflags\fP と \fImode\fP 引き数は \fBopen\fP(2)  ルーチンで指定するのと同様である。ただし 意味を持つフラグは
  99 \fBO_CREAT\fP, \fBO_EXCL\fP, \fBO_EXLOCK\fP, \fBO_NONBLOCK\fP, \fBO_RDONLY\fP, \fBO_RDWR\fP,
 100 \fBO_SHLOCK\fP, \fBO_TRUNC\fP だけである。 (注意: \fBO_WRONLY\fP でデータベースファイルを開く事は出来ない)
 101 .PP
 102 \fItype\fP 引き数は \fIDBTYPE\fP 型である (インクルードファイル \fI<db.h>\fP で定義されている)。
 103 \fBDB_BTREE\fP, \fBDB_HASH\fP, \fBDB_RECNO\fP のいずれかをセットできる。
 104 .PP
 105 \fIopeninfo\fP 引き数はアクセスメソッドに固有な構造体へのポインタである。 それぞれの構造体に関しては各アクセスメソッドの
 106 マニュアルページに記述されている。 \fIopeninfo\fP が NULL の場合、それぞれのアクセスメソッドとシステムとに適合した
 107 デフォルトが用いられる。
 108 .PP
 109 \fBdbopen\fP()  は、成功した場合 \fIDB\fP 構造体へのポインタを、エラーの場合 NULL を返す。 \fIDB\fP 構造体は
 110 \fI<db.h>\fP インクルードファイルの中で定義されており、 少なくとも以下のようなフィールドを持っている。
 111 .sp
 112 .in +4n
 113 .nf
 114 typedef struct {
 115     DBTYPE type;
 116     int (*close)(const DB *db);
 117     int (*del)(const DB *db, const DBT *key, unsigned int flags);
 118     int (*fd)(const DB *db);
 119     int (*get)(const DB *db, DBT *key, DBT *data,
 120                unsigned int flags);
 121     int (*put)(const DB *db, DBT *key, const DBT *data,
 122                unsigned int flags);
 123     int (*sync)(const DB *db, unsigned int flags);
 124     int (*seq)(const DB *db, DBT *key, DBT *data,
 125                unsigned int flags);
 126 } DB;
 127 .fi
 128 .in
 129 .PP
 130 各要素には、データベースのタイプと、 様々な動作をする関数のセットが記述されている。 これらの関数は \fBdbopen\fP()
 131 によって返される構造体へのポインタを引き数にとる。 キー/データ構造体へのポインタやフラグ値を取るものもある。
 132 .TP
 133 \fItype\fP
 134 用いられているアクセスメソッド (とファイルフォーマット) の型。
 135 .TP
 136 \fIclose\fP
 137 キャッシュされた情報をディスクに掃きだすためのルーチンへのポインタ。 割り当てられたリソースを解放し、利用したファイル(群)をクローズする。
 138 キー/データ対がメモリにキャッシュされている場合、 \fIclose\fP や \fIsync\fP
 139 関数での同期に失敗すると、情報に矛盾が生じるか情報を失う可能性がある。 \fIclose\fP ルーチンはエラーの場合 \-1 を返し (\fIerrno\fP
 140 をセットする)、成功すると 0 を返す。
 141 .TP
 142 \fIdel\fP
 143 データベースからキー/データ対を削除するルーチンへのポインタ。
 144 .IP
 145 \fIflag\fP 引き数は次の値がセットできる。
 146 .RS
 147 .TP
 148 \fBR_CURSOR\fP
 149 カーソル (cursor) が参照しているレコードを削除する。 カーソルは前もって初期化されていなくてはならない。
 150 .RE
 151 .IP
 152 \fIdelete\fP ルーチンはエラーの場合 \-1 を返し (\fIerrno\fP をセットする)、成功すると 0 を返す。また指定の \fIkey\fP
 153 がファイル中に無い場合 1 を返す。
 154 .TP
 155 \fIfd\fP
 156 用いているデータベースのファイルデスクリプタを返すルーチン へのポインタ。 同じファイル名 \fIfile\fP で \fBdbopen\fP()
 157 を呼び出した全てのプロセスに対して、 そのファイルを示す単一のファイルデスクリプタが返される。 このファイルデスクリプタはロック関数
 158 \fBfcntl\fP(2)  と \fBflock\fP(2)  への引き数として安全に使用できる。 このファイルデスクリプタは、必ずしもアクセスメソッドで
 159 用いられているファイルのいずれかに関連づけられていなくても良い。 メモリ内のデータベースにはファイルデスクリプタは無い。 \fIfd\fP
 160 ルーチンはエラーの場合 \-1 を返し (\fIerrno\fP をセットする)、成功するとファイルデスクリプタを返す。
 161 .TP
 162 \fIget\fP
 163 データベースからキーを用いてデータを取り出すための ルーチンへのポインタ。 指定した \fIkey\fP に関連づけられたデータのアドレスと長さが
 164 \fIdata\fP が参照する構造体に返される。 \fIget\fP ルーチンはエラーの場合 \-1 を返し (\fIerrno\fP をセットする)、成功すると 0
 165 を返す。また \fIkey\fP がファイル中に無い場合 1 を返す。
 166 .TP
 167 \fIput\fP
 168 キー/データ対をデータベースに納めるルーチンへのポインタ。
 169 .IP
 170 \fIflag\fP 引き数には次の値のうちのどれか一つがセットできる。
 171 .RS
 172 .TP
 173 \fBR_CURSOR\fP
 174 カーソルが参照しているキー/データ対を置き換える。 カーソルは前もって初期化されている必要がある。
 175 .TP
 176 \fBR_IAFTER\fP
 177 \fIkey\fP で参照されるデータの直後に、 新しいキー/データ対を作ってデータを追加する。 追加されたキー/データ対のレコード番号は \fIkey\fP
 178 構造体に返される。 (\fBDB_RECNO\fP アクセス方法でのみ使える。)
 179 .TP
 180 \fBR_IBEFORE\fP
 181 \fIkey\fP で参照されるデータの直前に、 新しいキー/データ対を作ってデータを挿入する。 追加されたキー/データ対のレコード番号は \fIkey\fP
 182 構造体に返される。 (\fBDB_RECNO\fP アクセスメソッドでのみ使える。)
 183 .TP
 184 \fBR_NOOVERWRITE\fP
 185 キーがあらかじめ存在しない場合に限り、新しいキー/データ対をいれる。
 186 .TP
 187 \fBR_SETCURSOR\fP
 188 キー/データ対を納め、それを指すようにカーソル位置をセットあるいは初期 化する。 (\fBDB_BTREE\fP と \fBDB_RECNO\fP
 189 アクセスメソッドでのみ使える。)
 190 .RE
 191 .IP
 192 \fBR_SETCURSOR\fP は \fBDB_BTREE\fP と \fBDB_RECNO\fP アクセスメソッドでしか利用できない。 なぜなら
 193 \fBR_SETCURSOR\fP を用いるには、変更される事の無い固有の順序をキー が持っていなければならないからである。
 194 .IP
 195 \fBR_IAFTER\fP と \fBR_IBEFORE\fP は \fBDB_RECNO\fP アクセスメソッドでしか利用できない。
 196 これらを実現するには、アクセスメソッドが 新しいキーを作れなければならないからである。 これが成立するのは、例えば、順序づけらた独立なレコード番号が
 197 キーになっているような場合だけである。
 198 .IP
 199 \fIput\fP ルーチンのデフォルトの動作は、新しいキー/データ対を 既に存在するキーを置き換える事て格納する動作である。
 200 .IP
 201 \fIput\fP ルーチンはエラーの場合 \-1 を返し (\fIerrno\fP をセットする)、成功すると 0 を返す。また \fIflag\fP に
 202 \fBR_NOOVERWRITE\fP がセットされていてキーが既に存在する場合 1 を返す。
 203 .TP
 204 \fIseq\fP
 205 データベースからシーケンシャルにデータを取り出すための ルーチンへのポインタ。 キーのアドレスと長さが \fIkey\fP
 206 が参照する構造体に返される。データのアドレスと長さが \fIdata\fP が参照する構造体に返される。
 207 .IP
 208 シーケンシャルなキー/データ対の取得はいつでも行える。また 「カーソル」の位置は \fIdel\fP, \fIget\fP, \fIput\fP, \fIsync\fP
 209 ルーチンの呼び出しには影響されない。 シーケンシャルなスキャンの途中に行われたデータベースへの変更は
 210 スキャンに反映される。すなわち、カーソルの後ろに挿入されたレコードは 返されないが、カーソルの前に挿入されたレコードは返される。
 211 .IP
 212 フラグ値には\fB必ず\fP以下に示すうちの どれか一つをセットしなければならない。
 213 .RS
 214 .TP
 215 \fBR_CURSOR\fP
 216 指定したキーに関連づけられたデータが返される。 \fIget\fP ルーチンとの違いは、カーソルがキーの位置にセットあるいは 初期化される点である。 (注意:
 217 \fBDB_BTREE\fP アクセス方法では、返されたキーが 必ずしも指定したキーに正しくマッチしないかもしれない。
 218 返されたキーは、指定されたキーに等しいかより大きいもののうち 最小のものになる (部分キーマッチか範囲検索が許可されている場合)。)
 219 .TP
 220 \fBR_FIRST\fP
 221 データベースの最初のキー/データ対が返される。 カーソルはそれを参照するようにセットまたは初期化される。
 222 .TP
 223 \fBR_LAST\fP
 224 データベースの最後のキー/データ対が返される。カーソルはそれを参照する ようにセットまたは初期化される。 (\fBDB_BTREE\fP と
 225 \fBDB_RECNO\fP アクセスメソッドだけで使える。)
 226 .TP
 227 \fBR_NEXT\fP
 228 カーソル直後のキー/データ対を取得する。 カーソルがセットされていない場合は \fBR_FIRST\fP フラグと同じ。
 229 .TP
 230 \fBR_PREV\fP
 231 カーソル直前のキー/データ対を取得する。 カーソルがセットされていない場合は \fBR_LAST\fP フラグと同じ。 (\fBDB_BTREE\fP と
 232 \fBDB_RECNO\fP アクセスメソッドだけで使える。)
 233 .RE
 234 .IP
 235 \fBR_LAST\fP と \fBR_PREV\fP は、 \fBDB_BTREE\fP と \fBDB_RECNO\fP アクセス方法でしか使えない。 なぜなら
 236 \fBR_SETCURSOR\fP を用いるには、変更される事の無い固有の順序をキーが持っていなければならないからである。
 237 .IP
 238 \fIseq\fP ルーチンはエラーの場合 \-1 を返し (\fIerrno\fP をセットする)、 成功の場合 0 を返す。
 239 指定したキーやカレントキーよりも大きい/小さいキー/データ対がない場合は 1 を返す。 \fBDB_RECNO\fP アクセスメソッドを使っていて、
 240 かつデータベースファイルが文字型のスペシャルファイルで、 完成しているキー/データ対が無い場合には、 \fIseq\fP ルーチンは 2 を返す。
 241 .TP
 242 \fIsync\fP
 243 キャッシュされた情報をディスクに掃き出すルーチンへのポインタ。 データベースがメモリの中だけにある場合、 \fIsync\fP
 244 ルーチンは何の効果もなく常に成功する。
 245 .IP
 246 flag には以下の値がセットできる。
 247 .RS
 248 .TP
 249 \fBR_RECNOSYNC\fP
 250 \fBDB_RECNO\fP アクセスメソッドを使っている場合に このフラグをセットすると、 recno ファイルそのものにではなく、 そのベースになっている
 251 btree ファイルに sync が行われる。 (詳細は \fBrecno\fP(3)  マニュアルページで \fIbfname\fP
 252 フィールドを説明している部分を参照のこと。)
 253 .RE
 254 .IP
 255 \fIsync\fP ルーチンはエラーの場合 \-1 を返し (\fIerrno\fP をセットする)、成功すると 0 を返す。
 256 .SS キー/データ対
 257 全てのファイルタイプにおいて、 キー/データ対をベースにしてアクセスが行われる。 キーとデータのいずれも、次のデータ構造で記述される。
 258 .in +4n
 259 .nf
 260
 261 typedef struct {
 262     void  *data;
 263     size_t size;
 264 } DBT;
 265 .fi
 266 .in
 267 .PP
 268 \fIDBT\fP 構造体の各要素は次のように定義されている。
 269 .TP
 270 \fIdata\fP
 271 バイト文字列へのポインタ。
 272 .TP
 273 \fIsize\fP
 274 バイト文字列の長さ。
 275 .PP
 276 キーとデータのバイト文字列は、 基本的には無制限の長さの文字列を参照できるが、 しかしいずれも使用可能なメモリに収まっていなくてはならない。
 277 アクセスメソッドはバイト文字列のアラインメントについては 何も保証していない事に注意すること。
 278 .SH エラー
 279 \fBdbopen\fP()  ルーチンは失敗するとライブラリルーチン \fBopen\fP(2)  と \fBmalloc\fP(3)  で指定されているエラーに応じた
 280 \fIerrno\fP をセットする。あるいは以下をセットする。
 281 .TP
 282 \fB[EFTYPE]\fP
 283 ファイルが正しくフォーマットされていない。
 284 .TP
 285 \fBEINVAL\fP
 286 指定したパラメータ (ハッシュ関数、バイト埋めなど) が現在のファイル仕様
 287 に合っていない、パラメータが関数にとって無意味 (例えば、あらかじめ初期
 288 化しないでカーソルを使うとか)、ファイルとソフトウェアのバージョンが
 289 合っていない。
 290 .PP
 291 \fIclose\fP ルーチンは失敗するとライブラリルーチン \fBclose\fP(2), \fBread\fP(2), \fBwrite\fP(2),
 292 \fBfree\fP(3), \fBfsync\fP(2)  で指定されているエラーに応じた \fIerrno\fP をセットする。
 293 .PP
 294 \fIdel\fP, \fIget\fP, \fIput\fP, \fIseq\fP ルーチンは失敗するとライブラリルーチン \fBread\fP(2), \fBwrite\fP(2),
 295 \fBfree\fP(3), \fBmalloc\fP(3)  で指定されているエラーに応じた \fIerrno\fP をセットする。
 296 .PP
 297 \fIfd\fP ルーチンはメモリ内データベースに対し失敗すると \fIerrno\fP に \fBENOENT\fP をセットする。
 298 .PP
 299 \fIsync\fP ルーチンは失敗するとライブラリルーチン \fBfsync\fP(2)  で指定されているエラーに応じた \fIerrno\fP をセットする。
 300 .SH バグ
 301 typedef \fIDBT\fP は \*(lqdata base thang\*(rqの略語であるが、これが使われているのは、
 302 まだ使われていない妥当な名前が思い付かなかったためである。
 303 .PP
 304 ファイルデスクリプタを使ったやりとりはひどい代物であり、 将来のバージョンでは削除されるだろう。
 305 .PP
 306 どのアクセスメソッドも、同時アクセス、ロック、トランザクション の仕組みは備えていない。
 307 .SH 関連項目
 308 \fBbtree\fP(3), \fBhash\fP(3), \fBmpool\fP(3), \fBrecno\fP(3)
 309
 310 \fILIBTP: Portable, Modular Transactions for UNIX\fP, Margo Seltzer, Michael
 311 Olson, USENIX proceedings, Winter 1992.
 312 .SH この文書について
 313 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.67 の一部
 314 である。プロジェクトの説明とバグ報告に関する情報は
 315 http://www.kernel.org/doc/man\-pages/ に書かれている。