manual/GNU_gdbm/release/man3/gdbm.3

   1 .ds ve 1.8
   2 .TH GDBM 3 5/19/99
   3 .\" Japanese Version Copyright (c) 2000 Tsugikazu Shibata
   4 .\"         all rights reserved.
   5 .\" Translated Fri. August 29 23:32:00 JST 2000
   6 .\"         by Tsugikazu Shibata <ts@tsden.org>
   7 .SH 名前
   8 GDBM - GNUデータベース・マネージャ。\fBdbm\fR および \fBndbm\fR
   9 互換機能を含む。 (Version \*(ve.)
  10
  11 .SH 書式
  12 .B #include <gdbm.h>
  13 .PP
  14 .SM
  15 .B extern gdbm_error
  16 .br
  17 .B gdbm_errno
  18 .PP
  19 .B extern char
  20 .br
  21 .B *gdbm_version
  22 .PP
  23 .B GDBM_FILE
  24 .br
  25 .B gdbm_open (name, block_size, read_write, mode, fatal_func)
  26 .br
  27 .B char * name;
  28 .br
  29 .B int block_size, read_write, mode;
  30 .br
  31 .B void (*fatal_func) ();
  32 .PP
  33 .B void
  34 .br
  35 .B gdbm_close (dbf)
  36 .br
  37 .B GDBM_FILE dbf;
  38 .PP
  39 .B int
  40 .br
  41 .B gdbm_store (dbf, key, content, flag)
  42 .br
  43 .B GDBM_FILE dbf;
  44 .br
  45 .B datum key, content;
  46 .br
  47 .B int flag;
  48 .PP
  49 .B datum
  50 .br
  51 .B gdbm_fetch (dbf, key)
  52 .br
  53 .B GDBM_FILE dbf;
  54 .br
  55 .B datum key;
  56 .PP
  57 .B int
  58 .br
  59 .B gdbm_delete (dbf, key)
  60 .br
  61 .B GDBM_FILE dbf;
  62 .br
  63 .B datum key;
  64 .PP
  65 .B datum
  66 .br
  67 .B gdbm_firstkey (dbf)
  68 .br
  69 .B GDBM_FILE dbf;
  70 .PP
  71 .B datum
  72 .br
  73 .B gdbm_nextkey (dbf, key)
  74 .br
  75 .B GDBM_FILE dbf;
  76 .br
  77 .B datum key;
  78 .PP
  79 .B int
  80 .br
  81 .B gdbm_reorganize (dbf)
  82 .br
  83 .B GDBM_FILE dbf;
  84 .PP
  85 .B void
  86 .br
  87 .B gdbm_sync (dbf)
  88 .br
  89 .B GDBM_FILE dbf;
  90 .PP
  91 .B int
  92 .br
  93 .B gdbm_exists (dbf, key)
  94 .br
  95 .B GDBM_FILE dbf;
  96 .br
  97 .B datum key;
  98 .PP
  99 .B char *
 100 .br
 101 .B gdbm_strerror (errno)
 102 .br
 103 .B gdbm_error errno;
 104 .PP
 105 .B int
 106 .br
 107 .B gdbm_setopt (dbf, option, value, size)
 108 .br
 109 .B GDBM_FILE dbf;
 110 .br
 111 .B int option;
 112 .br
 113 .B int *value;
 114 .br
 115 .B int size;
 116 .PP
 117 .B int
 118 .br
 119 .B gdbm_fdesc (dbf)
 120 .br
 121 .B GDBM_FILE dbf;
 122 .PP
 123 .PP
 124 .B DBM Compatability routines:
 125 .PP
 126 .B #include <dbm.h>
 127 .PP
 128 .SM
 129 .B int
 130 .br
 131 .B dbminit (name)
 132 .br
 133 .B char *name;
 134 .PP
 135 .B int
 136 .br
 137 .B store (key, content)
 138 .br
 139 .B datum key, content;
 140 .PP
 141 .B datum
 142 .br
 143 .B fetch (key)
 144 .br
 145 .B datum key;
 146 .PP
 147 .B int
 148 .br
 149 .B delete (key)
 150 .br
 151 .B datum key;
 152 .PP
 153 .B datum
 154 .br
 155 .B firstkey ()
 156 .PP
 157 .B datum
 158 .br
 159 .B nextkey (key)
 160 .br
 161 .B datum key;
 162 .PP
 163 .B int
 164 .br
 165 .B dbmclose ()
 166 .PP
 167 .PP
 168 .B NDBM Compatability routines:
 169 .PP
 170 .B #include <ndbm.h>
 171 .PP
 172 .SM
 173 .B DBM
 174 .br
 175 .B *dbm_open (name, flags, mode)
 176 .br
 177 .B char *name;
 178 .br
 179 .B int flags, mode;
 180 .PP
 181 .B void
 182 .br
 183 .B dbm_close (file)
 184 .br
 185 .B DBM *file;
 186 .PP
 187 .B datum
 188 .br
 189 .B dbm_fetch (file, key)
 190 .br
 191 .B DBM *file;
 192 .br
 193 .B datum key;
 194 .PP
 195 .B int
 196 .br
 197 .B dbm_store (file, key, content, flags)
 198 .br
 199 .B DBM *file;
 200 .br
 201 .B datum key, content;
 202 .br
 203 .B int flags;
 204 .PP
 205 .B int
 206 .br
 207 .B dbm_delete (file, key)
 208 .br
 209 .B DBM *file;
 210 .br
 211 .B datum key;
 212 .PP
 213 .B datum
 214 .br
 215 .B dbm_firstkey (file)
 216 .br
 217 .B DBM *file;
 218 .PP
 219 .B datum
 220 .br
 221 .B dbm_nextkey (file)
 222 .br
 223 .B DBM *file;
 224 .PP
 225 .B int
 226 .br
 227 .B dbm_error (file)
 228 .br
 229 .B DBM *file;
 230 .PP
 231 .B int
 232 .br
 233 .B dbm_clearerr (file)
 234 .br
 235 .B DBM *file;
 236 .PP
 237 .B int
 238 .br
 239 .B dbm_pagfno (file)
 240 .br
 241 .B DBM *file;
 242 .PP
 243 .B int
 244 .br
 245 .B dbm_dirfno (file)
 246 .br
 247 .B DBM *file;
 248 .PP
 249 .B int
 250 .br
 251 .B dbm_rdonly (file)
 252 .br
 253 .B DBM *file;
 254
 255
 256 .SH 説明
 257 GNU dbm は、キーとデータのペアを含んだデータファイルを取り扱う
 258 ルーチン群のライブラリである。
 259 提供されるアクセスとしては、キーによる格納、キーによる取り出し、
 260 キーによる削除の他、すべてのキーに渡るソートされていない横断的な
 261 アクセスがある。
 262 一つのプロセスからは複数のデータファイルを同時に利用することができる。
 263
 264 gdbm ファイルをオープンするプロセスは、「リーダ」または「ライタ」
 265 と呼ばれる。
 266 1 つの gdbm ファイルをオープンできるライタは 1 つだけだが、
 267 リーダは複数が 1 つの gdbm ファイルをオープンすることができる。
 268
 269 リーダとライタは同時に同じファイルをオープンすることはできない。
 270 gdbm ファイルをオープンする手続きは：
 271
 272 　  GDBM_FILE dbf;
 273
 274    dbf = gdbm_open ( name, block_size, read_write, mode, fatal_func )
 275
 276 \fIname\fR はファイルの名前である。(完全な名前、gdbm はこの名前に
 277 文字列を付け加えるようなことはしない)
 278 \fIblock_size\fR はディスクからメモリへ 1 回に転送されるサイズである。
 279 このパラメータは、新しいファイルの場合以外は無視される。最小サイズ
 280 は 512 である。
 281 512 よりも小さい場合には, gdbm はファイルシステムに対する stat
 282 のブロックサイズを使用する。
 283 \fIread_write\fR には以下のいずれかの値を取る。
 284 .br
 285 .B GDBM_READER
 286 リーダ
 287 .br
 288 .B GDBM_WRITER
 289 ライタ
 290 .br
 291 .B GDBM_WRCREAT
 292 ライタ - データベースが存在しなければ作成する
 293 .br
 294 .B GDBM_NEWDB
 295 ライタ - すでに存在しても新しいデータベースを作成する
 296 .br
 297 最後の 3 つについては (データベースのライタ) \fIread_write\fR に対して
 298 以下をビットの OR により追加できる:
 299 .B GDBM_SYNC
 300 はすべてのデータベースの操作をディスクと同期する、また
 301 .B GDBM_NOLOCK
 302 はデータベースファイルに関するライブラリからのロック動作を行わない。
 303 オプション
 304 .B GDBM_FAST
 305 は gdbm の既定動作が no-sync モードになったためにもう使われなくなった。
 306 .br
 307 \fImode\fR はファイルのモードである (\fBchmod(2)\fR および \fBopen(2)\fR を
 308 参照)。\fI(*fatal_func) ()\fR は dbm が致命的エラーを検出した場合に呼び出す
 309 関数である。この関数への唯一のパラメータは文字列である。
 310 値 0 が指定されると、gdbm はデフォルトの関数を使用する。
 311
 312 返り値 \fIdbf\fR は、その gdbm ファイルにアクセスする他のすべてのルーチン
 313 に必要なポインタである。 NULL ポインタが返った場合、\fBgdbm_open\fR は
 314 成功しなかったことを示す。
 315 gdbm のエラーは  \fIgdbm_errno\fR に、システムのエラーは \fIerrno\fR
 316 に格納される。(エラーコードについては gdbmerrno.h を参照)
 317
 318 以下のすべてのコールにおいては、
 319 パラメータ \fIdbf\fR は \fBgdbm_open\fR から
 320 返ってきたポインタである。
 321 どんなファイルでもオープンしたものをクローズすることは重要である。
 322 クローズはファイルに対するリーダ数／ライタ数を更新する。
 323 これは以下のようにして行う。
 324
 325    gdbm_close (dbf);
 326
 327 データベースは 3 つの主なルーチンによって利用できる。最初はデータを
 328 データベースに格納するものである。
 329
 330
 331    ret = gdbm_store ( dbf, key, content, flag )
 332
 333
 334 \fIdbf\fR は \fBgdbm_open\fR から返ってきたポインタである。
 335 \fIkey\fR はキーデータで、\fIcontent\fR は \fIkey\fR に関連付けられた
 336 データである。
 337 \fIflag\fR は以下のいずれかの値を持つことができる。
 338 .br
 339 .B GDBM_INSERT
 340 挿入のみ。キーが存在すればエラーとなる。
 341 .br
 342 .B GDBM_REPLACE
 343 キーが存在すれば内容を更新する。
 344
 345 リーダが \fBgdbm_store\fR をコールした場合、返り値は -1 となる。
 346 GDBM_INSERT が指定された時にデータベースに \fIkey\fR が存在すると、
 347 返り値は 1 である。そうでなければ返り値は 0 である。
 348
 349 \fI注意: 既にデータベースに存在するキーを指定して格納する場合、
 350 GDBM_REPLACEで呼び出しているならば、gdbm は古いデータを
 351 新しいデータで置き換える。
 352 同じキーで 2 つのデータ・アイテムを得ることはできないし、
 353 また gdbm_store がエラーを返すこともない。
 354
 355 注意: gdbm のサイズは、dbm や ndbm と異なり制限されない。
 356 データは必要なだけ大きくすることができる。
 357 \fR
 358
 359 データを検索するには、以下のようにする:
 360
 361   content = gdbm_fetch ( dbf, key )
 362
 363 \fIdbf\fR は \fBgdbm_open\fR から返ってきたポインタである。
 364 \fIkey\fR はキーデータである。
 365
 366 返り値の \fIdptr\fR が NULL の場合、データは見つからなかった。
 367 見つかった場合はデータへのポインタが返る。
 368 \fIdptr\fR の記憶空間は \fBmalloc(3C)\fR により確保される。
 369 \fBgdbm\fI は自動的にこのデータを解放することはしない。
 370 必要の無くなった領域を解放するのはプログラマの責任である。\fR
 371
 372 データを参照せずに、検索だけする場合には：
 373
 374    ret = gdbm_exists ( dbf, key )
 375
 376 \fIdbf\fR は \fBgdbm_open\fR から返ってきたポインタである。
 377 \fIkey\fR は検索したいキーデータである。
 378
 379 データベース内に \fIkey\fR が見つかれば、返り値 \fIret\fR は true である。
 380 .\" If nothing appropiate is found, \fIret\fR will be false.
 381 何も対応するものが見つからなければ \fIret\fR は false である。
 382
 383 \fBgdbm_fetch\fR ではメモリ確保が行われるが、このルーチンはそれをしない
 384 ので、レコードの存在をチェックをする時に役に立つ。
 385
 386 データベースからあるデータを削除する場合は、以下のようにする:
 387
 388    ret = gdbm_delete ( dbf, key )
 389
 390 \fIdbf\fR は \fBgdbm_open\fR から返ってきたポインタである。\fIkey\fR は
 391 削除したいキーデータである。
 392
 393 アイテムが存在しなかったり、要求したのがリーダだった場合、
 394 返り値は -1 である。
 395 削除に成功すれば返り値は 0 である。
 396
 397 次の 2 つのルーチンは、データベース中のすべてのアイテムにアクセスできる。
 398 アクセスはキー順ではないが、データベース内ですべてのキーに各 1 回
 399 アクセスすることは保証されている。(アクセス順序はハッシュ値の順になる。)
 400
 401    key = gdbm_firstkey ( dbf )
 402
 403    nextkey = gdbm_nextkey ( dbf, key )
 404
 405 \fIdbf\fR は \fBgdbm_open\fR から返ってきたポインタである。\fIkey\fR は
 406 キーデータである。
 407
 408 返り値はどちらも \fBdatum\fR 型である。返り値の \fIdptr\fR 要素が NULL
 409 の場合、最初のキーまたは次のキーがなかったことを示す。
 410 返り値の \fIdptr\fR 要素が指しているのは \fBmalloc(3C)\fR
 411 により確保されたデータであり、\fBgdbm\fR は free してはくれないことに
 412 もう一度注意すること。
 413
 414 これらの関数はデータベースをリードオンリーで参照することを意図していた。
 415 たとえば、データベースの正当性を確認したりするような目的で。
 416
 417 ファイルへの「参照」は「ハッシュ・テーブル」に基づいている。
 418 \fIgdbm_delete\fR はハッシュ・テーブルを再構成して、「見つけられることのない」
 419 アイテムがテーブルの中で放置されないように、すべての競合を確認する。
 420 すべてのデータの実体に変更を加えなかったとしても、オリジナルのキーの
 421 順序は保証されない。
 422
 423 .\" It is possible that some key will not be visited if a loop like
 424 .\" the following is executed:
 425 以下のループが実行された場合、いくつかのキーが見つけられ
 426 ないことが起こり得る。
 427
 428
 429     key = gdbm_firstkey ( dbf );
 430     while ( key.dptr ) {
 431        nextkey = gdbm_nextkey ( dbf, key );
 432        if ( some condition ) {
 433           gdbm_delete ( dbf, key );
 434           free ( key.dptr );
 435        }
 436        key = nextkey;
 437     }
 438
 439
 440 以下のルーチンは繰り返し使われるべきではない。
 441
 442
 443    ret = gdbm_reorganize ( dbf )
 444
 445 もしあなたがたくさんの削除を行い、\fBgdbm\fR ファイルが使っている
 446 スペースを小さくしたいと思うならば、このルーチンはデータベースの再構成を行う。
 447 \fBgdbm\fR はこの再構成以外で \fBgdbm\fR が使っているファイルの大きさを
 448 小さくすることは無い。(削除されたスペースは再利用される)
 449
 450 データベースが GDBM_SYNC フラグ付きで open されない限り、gdbm は次の動作を
 451 継続する前に、write がディスクにフラッシュするのを待つようなことはしない。
 452 次のルーチンはデータベースを物理的にディスクに書き出すことを保証する。
 453
 454    gdbm_sync ( dbf )
 455
 456 これはメインメモリの状態をディスクの状態と同期させるまでは戻って来ない。
 457
 458 \fBgdbm\fR のエラーコードを英文のテキストに変換するには、次のルーチン
 459 を利用する。
 460
 461    ret = gdbm_strerror ( errno )
 462
 463
 464 ここで \fIerrno\fR は \fIgdbm_error\fR 型であり、通常はグローバル変数
 465 の \fIgdbm_errno\fR である。対応するフレーズが返ってくる。
 466
 467 \fBgdbm\fR は既に open されているファイルに対するオプションを設定できる
 468 機能をサポートしている。
 469
 470    ret = gdbm_setopt ( dbf, option, value, size )
 471
 472 ここで、\fIdbf\fR は直前の \fBgdbm_open\fR の返り値であり、
 473 \fIoption\fR は設定したいオプションを指定する。現在の正しいオプションは：
 474
 475 \fBGDBM_CACHESIZE\fR - 内部の bucket キャッシュのサイズを指定する。
 476 このオプションは \fIGDBM_FILE\fR のディスクリプタに一度だけ設定でき、
 477 データベースの最初のアクセス時に自動的に 100 が設定される。
 478
 479 \fBGDBM_FASTMODE\fR - \fBfast mode\fR の on, off を指定する。
 480 \fBfast mode\fR はすでにオープンされていて、アクティブなデータベースに
 481 対してトグル (on, off) できる。\fIvalue\fR (以下参照) は TRUE か FALSE
 482 が設定できる。このオプションはもう使われない。
 483
 484 \fBGDBM_SYNCMODE\fR - ファイルシステムの同期処理を on, off する。この
 485 設定のデフォルトは off である。\fIvalue\fR (以下参照) は TRUE か FALSE
 486 を指定する。
 487
 488 \fBGDBM_CENTFREE\fR - \fBcentral フリーブロックプール\fR を on, off する。
 489 デフォルトは off であり、これは以前のバージョンの \fBgdbm\fR のフリー
 490 ブロックの取り扱いと同じである。もし、設定されると、このオプションはそ
 491 の後はフリーブロックはグローバルプールにおかれ、(理論的には) より多くの
 492 ファイルスペースがより早く再利用されるようになる。
 493 \fIvalue\fR (以下参照) は TRUE か FALSE を設定すべきである。
 494 注意：この機能はまだ検討中である。
 495
 496 \fBGDBM_COALESCEBLKS\fR - フリーブロックマージングの on, off を設定
 497 する。デフォルトは off で前のバージョンの \fBgdbm\fR のフリーブロック
 498 の扱いと同じである。もし、設定されるとこのオプションは、付近にあるフリー
 499 ブロックをマージする。これは 特に\fBGDBM_CENTFREE\fR と一緒に使われた
 500 としても 時間と CPU のかかる処理になる。\fIvalue\fR (以下参照) は TRUE
 501 か FALSE を設定するべきである。
 502 注意：この機能はまだ検討中である。
 503
 504 \fIvalue\fR は \fIoption\fR に設定する値であり、integer へのポインタ
 505 である。 \fIsize\fR は \fIvalue\fR によってポイントされるデータの
 506 サイズである。返り値は 失敗した場合 -1 になり、成功したら 0 になる。
 507 失敗の場合、グローバル変数の \fIgdbm_errno\fR には値が設定される。
 508
 509 例えば、\fBgdbm_open\fR でオープンしたデータベースをアクセスする前に、
 510 キャッシュとして 10 を使うように設定する場合、以下のコードが利用できる：
 511
 512    int value = 10;
 513
 514    ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));
 515
 516
 517 もしデータベースが \fBGDBM_NOLOCK\fR フラグ付きでオープンされた場合、
 518 ユーザはデータベースに対して、例えば複数のライタ操作を同一のファイル
 519 に対して行うような、自分の独自のファイルロッキングを使うことができる、
 520
 521 これをサポートするため、\fIgdbm_fdesc\fR ルーチンが提供される。
 522
 523    ret = gdbm_fdesc ( dbf )
 524
 525 ここで  \fIdbf\fR は以前の \fBgdbm_open\fR の返り値である。
 526 返り値はデータベースのファイルディスクリプタである。
 527
 528
 529 以下の 2 つの外部変数は役に立つことだろう。
 530 \fIgdbm_errno\fR は gdbm のエラーに関するより詳しい情報を持つ。
 531 (gdbm.h はエラー値の定義と gdbm_errno を外部変数とする定義を持つ)
 532 .br
 533 \fIgdbm_version\fR はバージョン情報の文字列を持つ。
 534
 535
 536 もう少し興味深いことが幾つかある。まず \fBgdbm\fR は「隙間のある」
 537 ファイルでは無いということである。あなたはこのファイルを UNIX の
 538 \fBcp(1)\fR コマンドによってコピーすることが可能で、そのコピー処理の間
 539 にファイルサイズが拡張されるようなことはない。さらに、UNIX ですでに使
 540 われている \fBdbm\fR のコンパチブルモードが存在する。このコンパチブル
 541 モードでは、\fRgdbm\fR のファイルポインタはプログラマに取って必要では
 542 なく、一度には 1 つのファイルだけがオープンされる。コンパチブルモード
 543 全ての利用者はライタと見なされる。もし、\fBgdbm\fR ファイルがリード
 544 オンリーならば、ライタとしては失敗し、リーダとしてオープンし直しを
 545 試みる。datum 構造体のすべてのポインタは、\fBgdbm\fR が解放するであろう
 546 データを指す。これらは (標準的な UNIX　の \fBdbm\fR がするように)
 547 静的ポインタとして扱う必要がある。
 548
 549
 550
 551 .SH リンク
 552 このライブラリはコンパイル行の最後のパラメータとして \fI-lgdbm\fR を
 553 指定することで利用される。
 554
 555 .sp
 556         gcc -o prog prog.c -lgdbm
 557 .SH バグ
 558
 559
 560 .SH 関連項目
 561 dbm, ndbm
 562
 563 .SH 著者
 564
 565 by Philip A. Nelson and Jason Downs.
 566 Copyright (C) 1990 - 1999 Free Software Foundation, Inc.
 567
 568 GDBM is free software; you can redistribute it and/or modify
 569 it under the terms of the GNU General Public License as published by
 570 the Free Software Foundation; either version 1, or (at your option)
 571 any later version.
 572
 573 GDBM is distributed in the hope that it will be useful,
 574 but WITHOUT ANY WARRANTY; without even the implied warranty of
 575 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 576 GNU General Public License for more details.
 577
 578 You should have received a copy of the GNU General Public License
 579 along with GDBM; see the file COPYING.  If not, write to
 580 the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 581
 582 You may contact the original author by:
 583 .br
 584    e-mail:  phil@cs.wwu.edu
 585 .br
 586   us-mail:  Philip A. Nelson
 587 .br
 588 Computer Science Department
 589 .br
 590 Western Washington University
 591 .br
 592 Bellingham, WA 98226
 593
 594 You may contact the current maintainer by:
 595 .br
 596    e-mail:  downsj@downsj.com