manual/LDP_man-pages/release/man3/dbopen.3

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)dbopen.3    8.5 (Berkeley) 1/2/94
  33 .\"
  34 .\" Japanese Version Copyright (c) 1999 Shouichi Saito
  35 .\"     all rights reserved.
  36 .\" Translated Thu Jul 22 00:00:00 JST 1999
  37 .\"     by Shouichi Saito <ss236rx@ymg.urban.ne.jp>
  38 .\" Proofed Tue Aug 19 1999 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
  39 .\"
  40 .\"WORD:        descriptor      デスクリプタ
  41 .TH DBOPEN 3 1994-01-02 "" "Linux Programmer's Manual"
  42 .UC 7
  43 .SH 名前
  44 dbopen \- データベースアクセスメソッド
  45 .SH 書式
  46 .nf
  47 .B #include <sys/types.h>
  48 .B #include <limits.h>
  49 .B #include <db.h>
  50
  51 .BI "DB *dbopen(const char *" file ", int " flags ", int " mode \
  52 ", DBTYPE " type ,
  53 .BI "           const void *" openinfo );
  54 .fi
  55 .SH 説明
  56 .BR dbopen ()
  57 はデータベースファイルに対するライブラリインターフェースである。
  58 サポートされているファイルフォーマットは btree, hash,
  59 UNIX ファイルに指向したフォーマット, の 3 つである。
  60 btree フォーマットは、ソートされたバランスツリー構造である。
  61 hashed フォーマットは、拡張可能な動的 hash スキームである。
  62 フラットファイル (flat-file) フォーマットは、
  63 固定長/可変長のレコードからなるバイトストリームファイルである。
  64 それぞれのフォーマットと、ファイルフォーマットに特有の情報は
  65 それぞれ対応するマニュアルページ
  66 .BR btree (3),
  67 .BR hash (3),
  68 .BR recno (3)
  69 に詳細に記述されている。
  70 .PP
  71 .BR dbopen ()
  72 は
  73 .I file
  74 を読み込み (読み書き) するためにオープンする。
  75 .I file
  76 引き数を NULL にすれば、
  77 ディスク上に保存したくないファイルを作ることもできる。
  78 .PP
  79 .I flags
  80 と
  81 .I mode
  82 引き数は
  83 .BR open (2)
  84 ルーチンで指定するのと同様である。ただし
  85 意味を持つフラグは
  86 .BR O_CREAT ,
  87 .BR O_EXCL ,
  88 .BR O_EXLOCK ,
  89 .BR O_NONBLOCK ,
  90 .BR O_RDONLY ,
  91 .BR O_RDWR ,
  92 .BR O_SHLOCK ,
  93 .B O_TRUNC
  94 だけである。
  95 (注意:
  96 .B O_WRONLY
  97 でデータベースファイルを開く事は出来ない)
  98 .\"Three additional options may be specified by ORing
  99 .\"them into the
 100 .\".I flags
 101 .\"argument.
 102 .\".TP
 103 .\"DB_LOCK
 104 .\"Do the necessary locking in the database to support concurrent access.
 105 .\"If concurrent access isn't needed or the database is read-only this
 106 .\"flag should not be set, as it tends to have an associated performance
 107 .\"penalty.
 108 .\".TP
 109 .\"DB_SHMEM
 110 .\"Place the underlying memory pool used by the database in shared
 111 .\"memory.
 112 .\"Necessary for concurrent access.
 113 .\".TP
 114 .\"DB_TXN
 115 .\"Support transactions in the database.
 116 .\"The DB_LOCK and DB_SHMEM flags must be set as well.
 117 .PP
 118 .I type
 119 引き数は
 120 .I DBTYPE
 121 型である (インクルードファイル
 122 .I <db.h>
 123 で定義されている)。
 124 .BR DB_BTREE ,
 125 .BR DB_HASH ,
 126 .B DB_RECNO
 127 のいずれかをセットできる。
 128 .PP
 129 .I openinfo
 130 引き数はアクセスメソッドに固有な構造体へのポインタである。
 131 それぞれの構造体に関しては各アクセスメソッドの
 132 マニュアルページに記述されている。
 133 .I openinfo
 134 が NULL の場合、それぞれのアクセスメソッドとシステムとに適合した
 135 デフォルトが用いられる。
 136 .PP
 137 .BR dbopen ()
 138 は、成功した場合
 139 .I DB
 140 構造体へのポインタを、エラーの場合 NULL を返す。
 141 .I DB
 142 構造体は
 143 .I <db.h>
 144 インクルードファイルの中で定義されており、
 145 少なくとも以下のようなフィールドを持っている。
 146 .sp
 147 .in +4n
 148 .nf
 149 typedef struct {
 150     DBTYPE type;
 151     int (*close)(const DB *db);
 152     int (*del)(const DB *db, const DBT *key, unsigned int flags);
 153     int (*fd)(const DB *db);
 154     int (*get)(const DB *db, DBT *key, DBT *data,
 155                unsigned int flags);
 156     int (*put)(const DB *db, DBT *key, const DBT *data,
 157                unsigned int flags);
 158     int (*sync)(const DB *db, unsigned int flags);
 159     int (*seq)(const DB *db, DBT *key, DBT *data,
 160                unsigned int flags);
 161 } DB;
 162 .fi
 163 .in
 164 .PP
 165 各要素には、データベースのタイプと、
 166 様々な動作をする関数のセットが記述されている。
 167 これらの関数は
 168 .BR dbopen ()
 169 によって返される構造体へのポインタを引き数にとる。
 170 キー/データ構造体へのポインタやフラグ値を取るものもある。
 171 .TP
 172 .I type
 173 用いられているアクセスメソッド (とファイルフォーマット) の型。
 174 .TP
 175 .I close
 176 キャッシュされた情報をディスクに掃きだすためのルーチンへのポインタ。
 177 割り当てられたリソースを解放し、利用したファイル(群)をクローズする。
 178 キー/データ対がメモリにキャッシュされている場合、
 179 .I close
 180 や
 181 .I sync
 182 関数での同期に失敗すると、情報に矛盾が生じるか情報を失う可能性がある。
 183 .I close
 184 ルーチンはエラーの場合 \-1 を返し
 185 .RI ( errno
 186 をセットする)、成功すると 0 を返す。
 187 .TP
 188 .I del
 189 データベースからキー/データ対を削除するルーチンへのポインタ。
 190 .IP
 191 .I flag
 192 引き数は次の値がセットできる。
 193 .RS
 194 .TP
 195 .B R_CURSOR
 196 カーソル (cursor) が参照しているレコードを削除する。
 197 カーソルは前もって初期化されていなくてはならない。
 198 .RE
 199 .IP
 200 .I delete
 201 ルーチンはエラーの場合 \-1 を返し
 202 .RI ( errno
 203 をセットする)、成功すると 0 を返す。また指定の
 204 .I key
 205 がファイル中に無い場合 1 を返す。
 206 .TP
 207 .I fd
 208 用いているデータベースのファイルデスクリプタを返すルーチン
 209 へのポインタ。
 210 同じファイル名
 211 .I file
 212 で
 213 .BR dbopen ()
 214 を呼び出した全てのプロセスに対して、
 215 そのファイルを示す単一のファイルデスクリプタが返される。
 216 このファイルデスクリプタはロック関数
 217 .BR fcntl (2)
 218 と
 219 .BR flock (2)
 220 への引き数として安全に使用できる。
 221 このファイルデスクリプタは、必ずしもアクセスメソッドで
 222 用いられているファイルのいずれかに関連づけられていなくても良い。
 223 メモリ内のデータベースにはファイルデスクリプタは無い。
 224 .I fd
 225 ルーチンはエラーの場合 \-1 を返し
 226 .RI ( errno
 227 をセットする)、成功するとファイルデスクリプタを返す。
 228 .TP
 229 .I get
 230 データベースからキーを用いてデータを取り出すための
 231 ルーチンへのポインタ。
 232 指定した
 233 .I key
 234 に関連づけられたデータのアドレスと長さが
 235 .I data
 236 が参照する構造体に返される。
 237 .I get
 238 ルーチンはエラーの場合 \-1 を返し
 239 .RI ( errno
 240 をセットする)、成功すると 0 を返す。また
 241 .I key
 242 がファイル中に無い場合 1 を返す。
 243 .TP
 244 .I put
 245 キー/データ対をデータベースに納めるルーチンへのポインタ。
 246 .IP
 247 .I flag
 248 引き数には次の値のうちのどれか一つがセットできる。
 249 .RS
 250 .TP
 251 .B R_CURSOR
 252 カーソルが参照しているキー/データ対を置き換える。
 253 カーソルは前もって初期化されている必要がある。
 254 .TP
 255 .B R_IAFTER
 256 .I key
 257 で参照されるデータの直後に、
 258 新しいキー/データ対を作ってデータを追加する。
 259 追加されたキー/データ対のレコード番号は
 260 .I key
 261 構造体に返される。
 262 .RB ( DB_RECNO
 263 アクセス方法でのみ使える。)
 264 .TP
 265 .B R_IBEFORE
 266 .I key
 267 で参照されるデータの直前に、
 268 新しいキー/データ対を作ってデータを挿入する。
 269 追加されたキー/データ対のレコード番号は
 270 .I key
 271 構造体に返される。
 272 .RB ( DB_RECNO
 273 アクセスメソッドでのみ使える。)
 274 .TP
 275 .B R_NOOVERWRITE
 276 キーがあらかじめ存在しない場合に限り、新しいキー/データ対をいれる。
 277 .TP
 278 .B R_SETCURSOR
 279 キー/データ対を納め、それを指すようにカーソル位置をセットあるいは初期
 280 化する。
 281 .RB ( DB_BTREE
 282 と
 283 .B DB_RECNO
 284 アクセスメソッドでのみ使える。)
 285 .RE
 286 .IP
 287 .B R_SETCURSOR
 288 は
 289 .B DB_BTREE
 290 と
 291 .B DB_RECNO
 292 アクセスメソッドでしか利用できない。
 293 なぜなら
 294 .B R_SETCURSOR
 295 を用いるには、変更される事の無い固有の順序をキー
 296 が持っていなければならないからである。
 297 .IP
 298 .B R_IAFTER
 299 と
 300 .B R_IBEFORE
 301 は
 302 .B DB_RECNO
 303 アクセスメソッドでしか利用できない。
 304 これらを実現するには、アクセスメソッドが
 305 新しいキーを作れなければならないからである。
 306 これが成立するのは、例えば、順序づけらた独立なレコード番号が
 307 キーになっているような場合だけである。
 308 .IP
 309 .I put
 310 ルーチンのデフォルトの動作は、新しいキー/データ対を
 311 既に存在するキーを置き換える事て格納する動作である。
 312 .IP
 313 .I put
 314 ルーチンはエラーの場合 \-1 を返し
 315 .RI ( errno
 316 をセットする)、成功すると 0 を返す。また
 317 .I flag
 318 に
 319 .B R_NOOVERWRITE
 320 がセットされていてキーが既に存在する場合 1 を返す。
 321 .TP
 322 .I seq
 323 データベースからシーケンシャルにデータを取り出すための
 324 ルーチンへのポインタ。
 325 キーのアドレスと長さが
 326 .I key
 327 が参照する構造体に返される。データのアドレスと長さが
 328 .I data
 329 が参照する構造体に返される。
 330 .IP
 331 シーケンシャルなキー/データ対の取得はいつでも行える。また
 332 「カーソル」の位置は
 333 .IR del ,
 334 .IR get ,
 335 .IR put ,
 336 .I sync
 337 ルーチンの呼び出しには影響されない。
 338 シーケンシャルなスキャンの途中に行われたデータベースへの変更は
 339 スキャンに反映される。すなわち、カーソルの後ろに挿入されたレコードは
 340 返されないが、カーソルの前に挿入されたレコードは返される。
 341 .IP
 342 フラグ値には\fB必ず\fP以下に示すうちの
 343 どれか一つをセットしなければならない。
 344 .RS
 345 .TP
 346 .B R_CURSOR
 347 指定したキーに関連づけられたデータが返される。
 348 .I get
 349 ルーチンとの違いは、カーソルがキーの位置にセットあるいは
 350 初期化される点である。
 351 (注意:
 352 .B DB_BTREE
 353 アクセス方法では、返されたキーが
 354 必ずしも指定したキーに正しくマッチしないかもしれない。
 355 返されたキーは、指定されたキーに等しいかより大きいもののうち
 356 最小のものになる
 357 (部分キーマッチか範囲検索が許可されている場合)。)
 358 .TP
 359 .B R_FIRST
 360 データベースの最初のキー/データ対が返される。
 361 カーソルはそれを参照するようにセットまたは初期化される。
 362 .TP
 363 .B R_LAST
 364 データベースの最後のキー/データ対が返される。カーソルはそれを参照する
 365 ようにセットまたは初期化される。
 366 .RB ( DB_BTREE
 367 と
 368 .B DB_RECNO
 369 アクセスメソッドだけで使える。)
 370 .TP
 371 .B R_NEXT
 372 カーソル直後のキー/データ対を取得する。
 373 カーソルがセットされていない場合は
 374 .B R_FIRST
 375 フラグと同じ。
 376 .TP
 377 .B R_PREV
 378 カーソル直前のキー/データ対を取得する。
 379 カーソルがセットされていない場合は
 380 .B R_LAST
 381 フラグと同じ。
 382 .RB ( DB_BTREE
 383 と
 384 .B DB_RECNO
 385 アクセスメソッドだけで使える。)
 386 .RE
 387 .IP
 388 .B R_LAST
 389 と
 390 .B R_PREV
 391 は、
 392 .B DB_BTREE
 393 と
 394 .B DB_RECNO
 395 アクセス方法でしか使えない。
 396 なぜなら
 397 .B R_SETCURSOR
 398 を用いるには、変更される事の無い固有の順序をキーが持っていなければならないからである。
 399 .IP
 400 .I seq
 401 ルーチンはエラーの場合 \-1 を返し
 402 .RI ( errno
 403 をセットする)、
 404 成功の場合 0 を返す。
 405 指定したキーやカレントキーよりも大きい/小さいキー/データ対がない場合は
 406 1 を返す。
 407 .B DB_RECNO
 408 アクセスメソッドを使っていて、
 409 かつデータベースファイルが文字型のスペシャルファイルで、
 410 完成しているキー/データ対が無い場合には、
 411 .I seq
 412 ルーチンは 2 を返す。
 413 .TP
 414 .I sync
 415 キャッシュされた情報をディスクに掃き出すルーチンへのポインタ。
 416 データベースがメモリの中だけにある場合、
 417 .I sync
 418 ルーチンは何の効果もなく常に成功する。
 419 .IP
 420 flag には以下の値がセットできる。
 421 .RS
 422 .TP
 423 .B R_RECNOSYNC
 424 .B DB_RECNO
 425 アクセスメソッドを使っている場合に
 426 このフラグをセットすると、
 427 recno ファイルそのものにではなく、
 428 そのベースになっている btree ファイルに sync が行われる。
 429 (詳細は
 430 .BR recno (3)
 431 マニュアルページで
 432 .I bfname
 433 フィールドを説明している部分を参照のこと。)
 434 .RE
 435 .IP
 436 .I sync
 437 ルーチンはエラーの場合 \-1 を返し
 438 .RI ( errno
 439 をセットする)、成功すると 0 を返す。
 440 .SS キー/データ対
 441 全てのファイルタイプにおいて、
 442 キー/データ対をベースにしてアクセスが行われる。
 443 キーとデータのいずれも、次のデータ構造で記述される。
 444 .in +4n
 445 .nf
 446
 447 typedef struct {
 448     void  *data;
 449     size_t size;
 450 } DBT;
 451 .fi
 452 .in
 453 .I DBT
 454 構造体の各要素は次のように定義されている。
 455 .TP
 456 .I data
 457 バイト文字列へのポインタ。
 458 .TP
 459 .I size
 460 バイト文字列の長さ。
 461 .PP
 462 キーとデータのバイト文字列は、
 463 基本的には無制限の長さの文字列を参照できるが、
 464 しかしいずれも使用可能なメモリに収まっていなくてはならない。
 465 アクセスメソッドはバイト文字列のアラインメントについては
 466 何も保証していない事に注意すること。
 467 .SH エラー
 468 .BR dbopen ()
 469 ルーチンは失敗するとライブラリルーチン
 470 .BR open (2)
 471 と
 472 .BR malloc (3)
 473 で指定されているエラーに応じた
 474 .I errno
 475 をセットする。あるいは以下をセットする。
 476 .TP
 477 .B [EFTYPE]
 478 ファイルが正しくフォーマットされていない。
 479 .TP
 480 .B [EINVAL]
 481 指定したパラメータ(ハッシュ関数、バイト埋めなど)が現在のファイル仕様に
 482 合っていない、パラメータが関数にとって無意味
 483 (例えばあらかじめ初期化しないでカーソルを使うとか)、
 484 ファイルとソフトウェアのバージョンが合っていない。
 485 .PP
 486 .I close
 487 ルーチンは失敗するとライブラリルーチン
 488 .BR close (2),
 489 .BR read (2),
 490 .BR write (2),
 491 .BR free (3),
 492 .BR fsync (2)
 493 で指定されているエラーに応じた
 494 .I errno
 495 をセットする。
 496 .PP
 497 .IR del ,
 498 .IR get ,
 499 .I put
 500 と
 501 .I seq
 502 ルーチンは失敗するとライブラリルーチン
 503 .BR read (2),
 504 .BR write (2),
 505 .BR free (3),
 506 .BR malloc (3)
 507 で指定されているエラーに応じた
 508 .I errno
 509 をセットする。
 510 .PP
 511 .I fd
 512 ルーチンはメモリ内データベースに対し失敗すると
 513 .I errno
 514 に
 515 .B ENOENT
 516 をセットする。
 517 .PP
 518 .I sync
 519 ルーチンは失敗するとライブラリルーチン
 520 .BR fsync (2)
 521 で指定されているエラーに応じた
 522 .I errno
 523 をセットする。
 524 .SH バグ
 525 typedef
 526 .I DBT
 527 は ``data base thang''の略語であるが、これが使われているのは、
 528 まだ使われていない妥当な名前が思い付かなかったためである。
 529 .PP
 530 ファイルデスクリプタを使ったやりとりはひどい代物であり、
 531 将来のバージョンでは削除されるだろう。
 532 .PP
 533 どのアクセスメソッドも、同時アクセス、ロック、トランザクション
 534 の仕組みは備えていない。
 535 .SH 関連項目
 536 .BR btree (3),
 537 .BR hash (3),
 538 .BR mpool (3),
 539 .BR recno (3)
 540 .sp
 541 .IR "LIBTP: Portable, Modular Transactions for UNIX" ,
 542 Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.