.ds ve 1.8.3
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 2000 Tsugikazu Shibata
.\"         all rights reserved.
.\" Translated 2000-08-29, Tsugikazu Shibata <ts@tsden.org>
.\" Updated 2012-06-02, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH GDBM 3 10/15/2002  
.SH 名前
GDBM \- GNUデータベース・マネージャ。\fBdbm\fP および \fBndbm\fP 互換機能を含む。 (Version \*(ve.)
.SH 書式
\fB#include <gdbm.h>\fP
.PP
.SM
\fBextern gdbm_error\fP
.br
\fBgdbm_errno\fP
.PP
\fBextern char\fP
.br
\fB*gdbm_version\fP
.PP
\fBGDBM_FILE\fP
.br
\fBgdbm_open (name, block_size, read_write, mode, fatal_func)\fP
.br
\fBchar * name;\fP
.br
\fBint block_size, read_write, mode;\fP
.br
\fBvoid (*fatal_func) ();\fP
.PP
\fBvoid\fP
.br
\fBgdbm_close (dbf)\fP
.br
\fBGDBM_FILE dbf;\fP
.PP
\fBint\fP
.br
\fBgdbm_store (dbf, key, content, flag)\fP
.br
\fBGDBM_FILE dbf;\fP
.br
\fBdatum key, content;\fP
.br
\fBint flag;\fP
.PP
\fBdatum\fP
.br
\fBgdbm_fetch (dbf, key)\fP
.br
\fBGDBM_FILE dbf;\fP
.br
\fBdatum key;\fP
.PP
\fBint\fP
.br
\fBgdbm_delete (dbf, key)\fP
.br
\fBGDBM_FILE dbf;\fP
.br
\fBdatum key;\fP
.PP
\fBdatum\fP
.br
\fBgdbm_firstkey (dbf)\fP
.br
\fBGDBM_FILE dbf;\fP
.PP
\fBdatum\fP
.br
\fBgdbm_nextkey (dbf, key)\fP
.br
\fBGDBM_FILE dbf;\fP
.br
\fBdatum key;\fP
.PP
\fBint\fP
.br
\fBgdbm_reorganize (dbf)\fP
.br
\fBGDBM_FILE dbf;\fP
.PP
\fBvoid\fP
.br
\fBgdbm_sync (dbf)\fP
.br
\fBGDBM_FILE dbf;\fP
.PP
\fBint\fP
.br
\fBgdbm_exists (dbf, key)\fP
.br
\fBGDBM_FILE dbf;\fP
.br
\fBdatum key;\fP
.PP
\fBchar *\fP
.br
\fBgdbm_strerror (errno)\fP
.br
\fBgdbm_error errno;\fP
.PP
\fBint\fP
.br
\fBgdbm_setopt (dbf, option, value, size)\fP
.br
\fBGDBM_FILE dbf;\fP
.br
\fBint option;\fP
.br
\fBint *value;\fP
.br
\fBint size;\fP
.PP
\fBint\fP
.br
\fBgdbm_fdesc (dbf)\fP
.br
\fBGDBM_FILE dbf;\fP
.PP
.PP
\fBDBM Compatability routines:\fP
.PP
\fB#include <dbm.h>\fP
.PP
.SM
\fBint\fP
.br
\fBdbminit (name)\fP
.br
\fBchar *name;\fP
.PP
\fBint\fP
.br
\fBstore (key, content)\fP
.br
\fBdatum key, content;\fP
.PP
\fBdatum\fP
.br
\fBfetch (key)\fP
.br
\fBdatum key;\fP
.PP
\fBint\fP
.br
\fBdelete (key)\fP
.br
\fBdatum key;\fP
.PP
\fBdatum\fP
.br
\fBfirstkey ()\fP
.PP
\fBdatum\fP
.br
\fBnextkey (key)\fP
.br
\fBdatum key;\fP
.PP
\fBint\fP
.br
\fBdbmclose ()\fP
.PP
.PP
\fBNDBM Compatability routines:\fP
.PP
\fB#include <ndbm.h>\fP
.PP
.SM
\fBDBM\fP
.br
\fB*dbm_open (name, flags, mode)\fP
.br
\fBchar *name;\fP
.br
\fBint flags, mode;\fP
.PP
\fBvoid\fP
.br
\fBdbm_close (file)\fP
.br
\fBDBM *file;\fP
.PP
\fBdatum\fP
.br
\fBdbm_fetch (file, key)\fP
.br
\fBDBM *file;\fP
.br
\fBdatum key;\fP
.PP
\fBint\fP
.br
\fBdbm_store (file, key, content, flags)\fP
.br
\fBDBM *file;\fP
.br
\fBdatum key, content;\fP
.br
\fBint flags;\fP
.PP
\fBint\fP
.br
\fBdbm_delete (file, key)\fP
.br
\fBDBM *file;\fP
.br
\fBdatum key;\fP
.PP
\fBdatum\fP
.br
\fBdbm_firstkey (file)\fP
.br
\fBDBM *file;\fP
.PP
\fBdatum\fP
.br
\fBdbm_nextkey (file)\fP
.br
\fBDBM *file;\fP
.PP
\fBint\fP
.br
\fBdbm_error (file)\fP
.br
\fBDBM *file;\fP
.PP
\fBint\fP
.br
\fBdbm_clearerr (file)\fP
.br
\fBDBM *file;\fP
.PP
\fBint\fP
.br
\fBdbm_pagfno (file)\fP
.br
\fBDBM *file;\fP
.PP
\fBint\fP
.br
\fBdbm_dirfno (file)\fP
.br
\fBDBM *file;\fP
.PP
\fBint\fP
.br
\fBdbm_rdonly (file)\fP
.br
\fBDBM *file;\fP


.SH 説明
GNU dbm は、キーとデータのペアを含んだデータファイルを取り扱う ルーチン群のライブラリである。
提供されるアクセスとしては、キーによる格納、キーによる取り出し、 キーによる削除の他、すべてのキーに渡るソートされていない横断的な アクセスがある。
一つのプロセスからは複数のデータファイルを同時に利用することができる。

gdbm ファイルをオープンするプロセスは、「リーダ」または「ライタ」 と呼ばれる。 1 つの gdbm ファイルをオープンできるライタは 1
つだけだが、 リーダは複数が 1 つの gdbm ファイルをオープンすることができる。 リーダとライタは同時に同じファイルをオープンすることはできない。
gdbm ファイルをオープンする手続きは次の通りである。

  GDBM_FILE dbf;

  dbf = gdbm_open ( name, block_size, read_write, mode, fatal_func )

\fIname\fP はファイルの名前である。(完全な名前、gdbm はこの名前に 文字列を付け加えるようなことはしない)  \fIblock_size\fP
はディスクからメモリへ 1 回に転送されるサイズである。 このパラメータは、新しいファイルの場合以外は無視される。最小サイズ は 512 である。
512 よりも小さい場合には, gdbm はファイルシステムに対する stat のブロックサイズを使用する。 \fIread_write\fP
には以下のいずれかの値を取る。
.br
\fBGDBM_READER\fP リーダ
.br
\fBGDBM_WRITER\fP ライタ
.br
\fBGDBM_WRCREAT\fP ライタ \- データベースが存在しなければ作成する
.br
\fBGDBM_NEWDB\fP ライタ \- すでに存在しても新しいデータベースを作成する
.br
最後の 3 つについては (データベースのライタ) \fIread_write\fP に対して 以下をビットの OR により追加できる:
\fBGDBM_SYNC\fP はすべてのデータベースの操作をディスクと同期する、また \fBGDBM_NOLOCK\fP
はデータベースファイルに関するライブラリからのロック動作を行わない。 オプション \fBGDBM_FAST\fP は gdbm の既定動作が no\-sync
モードになったためにもう使われなくなった。
.br
\fImode\fP はファイルのモードである (\fBchmod(2)\fP および \fBopen(2)\fP を 参照)。\fI(*fatal_func) ()\fP は
dbm が致命的エラーを検出した場合に呼び出す 関数である。この関数への唯一のパラメータは文字列である。 値 0 が指定されると、gdbm
はデフォルトの関数を使用する。

返り値 \fIdbf\fP は、その gdbm ファイルにアクセスする他のすべてのルーチン に必要なポインタである。 NULL
ポインタが返った場合、\fBgdbm_open\fP は 成功しなかったことを示す。 gdbm のエラーは \fIgdbm_errno\fP に、システムのエラーは
\fIerrno\fP に格納される (エラーコードについては gdbmerrno.h を参照)。

以下のすべてのコールにおいては、 パラメータ \fIdbf\fP は \fBgdbm_open\fP から 返ってきたポインタである。

どんなファイルでもオープンしたものをクローズすることは重要である。 クローズはファイルに対するリーダ数／ライタ数を更新する。
これは以下のようにして行う。

  gdbm_close (dbf);


データベースは 3 つの主なルーチンによって利用できる。最初はデータを データベースに格納するものである。

  ret = gdbm_store ( dbf, key, content, flag )

\fIdbf\fP は \fBgdbm_open\fP から返ってきたポインタである。 \fIkey\fP はキーデータで、\fIcontent\fP は \fIkey\fP
に関連付けられた データである。 \fIflag\fP は以下のいずれかの値を持つことができる。
.br
\fBGDBM_INSERT\fP 挿入のみ。キーが存在すればエラーとなる。
.br
\fBGDBM_REPLACE\fP キーが存在すれば内容を更新する。

リーダが \fBgdbm_store\fP をコールした場合、返り値は \-1 となる。 GDBM_INSERT が指定された時にデータベースに \fIkey\fP
が存在すると、 返り値は 1 である。そうでなければ返り値は 0 である。

\fI注意: 既にデータベースに存在するキーを指定して格納する場合、 GDBM_REPLACE で呼び出しているならば、gdbm は古いデータを
新しいデータで置き換える。 同じキーで 2 つのデータ・アイテムを得ることはできないし、 また gdbm_store がエラーを返すこともない。\fP

\fI注意: gdbm のサイズは、dbm や ndbm と異なり制限されない。 データは必要なだけ大きくすることができる。\fP


データを検索するには、以下のようにする:

  content = gdbm_fetch ( dbf, key )

\fIdbf\fP は \fBgdbm_open\fP から返ってきたポインタである。 \fIkey\fP はキーデータである。


返り値の \fIdptr\fP が NULL の場合、データは見つからなかった。 見つかった場合はデータへのポインタが返る。 \fIdptr\fP の記憶空間は
\fBmalloc(3C)\fP により確保される。 \fBgdbm\fP \fIは自動的にこのデータを解放することはしない。
必要の無くなった領域を解放するのはプログラマの責任である。\fP


データを参照せずに、検索だけする場合には：

  ret = gdbm_exists ( dbf, key )

\fIdbf\fP は \fBgdbm_open\fP から返ってきたポインタである。 \fIkey\fP は検索したいキーデータである。

データベース内に \fIkey\fP が見つかれば、返り値 \fIret\fP は true である。 何も対応するものが見つからなければ \fIret\fP は
false である。 \fBgdbm_fetch\fP ではメモリ確保が行われるが、このルーチンはそれをしない
ので、レコードの存在をチェックをする時に役に立つ。


データベースからあるデータを削除する場合は、以下のようにする:

   ret = gdbm_delete ( dbf, key )

\fIdbf\fP は \fBgdbm_open\fP から返ってきたポインタである。 \fIkey\fP はキーデータである。

アイテムが存在しなかったり、要求したのがリーダだった場合、 返り値は \-1 である。 削除に成功すれば返り値は 0 である。


次の 2 つのルーチンは、データベース中のすべてのアイテムにアクセスできる。 アクセスはキー順ではないが、データベース内ですべてのキーに各 1 回
アクセスすることは保証されている。(アクセス順序はハッシュ値の順になる。)

  key = gdbm_firstkey ( dbf )

  nextkey = gdbm_nextkey ( dbf, key )

\fIdbf\fP は \fBgdbm_open\fP から返ってきたポインタである。\fIkey\fP は キーデータである。

返り値はどちらも \fBdatum\fP 型である。返り値の \fIdptr\fP 要素が NULL の場合、最初のキーまたは次のキーがなかったことを示す。
返り値の \fIdptr\fP 要素が指しているのは \fBmalloc(3C)\fP により確保されたデータであり、\fBgdbm\fP は free
してはくれないことに もう一度注意すること。

これらの関数はデータベースをリードオンリーで参照することを意図していた。 たとえば、データベースの正当性を確認したりするような目的で。

ファイルへの「参照」は「ハッシュ・テーブル」に基づいている。 \fIgdbm_delete\fP はハッシュ・テーブルを再構成して、「見つけられることのない」
アイテムがテーブルの中で放置されないように、すべての競合を確認する。 すべてのデータの実体に変更を加えなかったとしても、オリジナルのキーの
順序は保証されない。以下のループが実行された場合、いくつかのキーが見つけられないことが起こり得る。

   key = gdbm_firstkey ( dbf );
   while ( key.dptr ) {
      nextkey = gdbm_nextkey ( dbf, key );
      if ( some condition ) {
         gdbm_delete ( dbf, key );
         free ( key.dptr );
      }
      key = nextkey;
   }


以下のルーチンは繰り返し使われるべきではない。
  
  ret = gdbm_reorganize ( dbf )

もしあなたがたくさんの削除を行い、\fBgdbm\fP ファイルが使っている スペースを小さくしたいと思うならば、このルーチンはデータベースの再構成を行う。
\fBgdbm\fP はこの再構成以外で \fBgdbm\fP が使っているファイルの大きさを 小さくすることは無い。(削除されたスペースは再利用される)


データベースが GDBM_SYNC フラグ付きで open されない限り、gdbm は次の動作を 継続する前に、write
がディスクにフラッシュするのを待つようなことはしない。 次のルーチンはデータベースを物理的にディスクに書き出すことを保証する。

  gdbm_sync ( dbf )

これはメインメモリの状態をディスクの状態と同期させるまでは戻って来ない。


\fBgdbm\fP のエラーコードを英文のテキストに変換するには、次のルーチン を利用する。

  ret = gdbm_strerror ( errno )

ここで \fIerrno\fP は \fIgdbm_error\fP 型であり、通常はグローバル変数 の \fIgdbm_errno\fP
である。対応するフレーズが返ってくる。


\fBgdbm\fP は既に open されているファイルに対するオプションを設定できる 機能をサポートしている。

  ret = gdbm_setopt ( dbf, option, value, size )

ここで、\fIdbf\fP は直前の \fBgdbm_open\fP の返り値であり、 \fIoption\fP
は設定したいオプションを指定する。現在の正しいオプションは：

\fBGDBM_CACHESIZE\fP \- 内部の bucket キャッシュのサイズを指定する。
このオプションは \fIGDBM_FILE\fP のディスクリプタに一度だけ設定でき、
データベースの最初のアクセス時に自動的に 100 が設定される。

\fBGDBM_FASTMODE\fP \- \fBfast mode\fP の on, off を指定する。 \fBfast mode\fP は
すでにオープンされていて、アクティブなデータベースに 対してトグル (on,
off) できる。\fIvalue\fP (以下参照) は TRUE か FALSE が設定できる。
\fIこのオプションはもう使われない。\fP

\fBGDBM_SYNCMODE\fP \- ファイルシステムの同期処理を on, off する。
この設定のデフォルトは off である。
\fIvalue\fP (以下参照) は TRUE か FALSE を指定する。

\fBGDBM_CENTFREE\fP \- \fBcentral フリーブロックプール\fP を on, off する。
デフォルトは off であり、これは以前のバージョンの \fBgdbm\fP のフリー
ブロックの取り扱いと同じである。もし、設定されると、このオプションは
その後はフリーブロックはグローバルプールにおかれ、(理論的には) より
多くのファイルスペースがより早く再利用されるようになる。
\fIvalue\fP (以下参照) は TRUE か FALSE を設定すべきである。
\fI注意：この機能はまだ検討中である。\fP

\fBGDBM_COALESCEBLKS\fP \- \fBフリーブロックマージング\fPの on, off を設定する。
デフォルトは off で前のバージョンの \fBgdbm\fP のフリーブロック の扱いと
同じである。もし、設定されるとこのオプションは、付近にあるフリーブロック
をマージする。これは 特に\fBGDBM_CENTFREE\fP と一緒に使われたとしても
時間と CPU のかかる処理になる。\fIvalue\fP (以下参照) は TRUE か FALSE を
設定するべきである。 \fI注意：この機能はまだ検討中である。\fP

\fIvalue\fP は \fIoption\fP に設定する値であり、integer へのポインタ である。 \fIsize\fP は \fIvalue\fP
によってポイントされるデータの サイズである。返り値は 失敗した場合 \-1 になり、成功したら 0 になる。 失敗の場合、グローバル変数の
\fIgdbm_errno\fP には値が設定される。

例えば、\fBgdbm_open\fP でオープンしたデータベースをアクセスする前に、 キャッシュとして 10
を使うように設定する場合、以下のコードが利用できる：

  int value = 10;
  
  ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));


もしデータベースが \fBGDBM_NOLOCK\fP フラグ付きでオープンされた場合、 ユーザはデータベースに対して、例えば複数のライタ操作を同一のファイル
に対して行うような、自分の独自のファイルロッキングを使うことができる、

これをサポートするため、\fIgdbm_fdesc\fP ルーチンが提供される。

  ret = gdbm_fdesc ( dbf )

ここで \fIdbf\fP は以前の \fBgdbm_open\fP の返り値である。 返り値はデータベースのファイルディスクリプタである。

以下の 2 つの外部変数は役に立つことだろう。

\fIgdbm_errno\fP は gdbm のエラーに関するより詳しい情報を持つ (gdbm.h はエラー値の定義と gdbm_errno
を外部変数とする定義を持つ)。
.br
\fIgdbm_version\fP はバージョン情報の文字列を持つ。


もう少し興味深いことが幾つかある。まず \fBgdbm\fP は「隙間のある」 ファイルでは無いということである。あなたはこのファイルを UNIX の
\fBcp(1)\fP コマンドによってコピーすることが可能で、そのコピー処理の間 にファイルサイズが拡張されるようなことはない。さらに、UNIX ですでに使
われている \fBdbm\fP のコンパチブルモードが存在する。このコンパチブル モードでは、gdbm のファイルポインタはプログラマに取って必要では
なく、一度には 1 つのファイルだけがオープンされる。コンパチブルモード 全ての利用者はライタと見なされる。もし、\fBgdbm\fP ファイルがリード
オンリーならば、ライタとしては失敗し、リーダとしてオープンし直しを 試みる。datum 構造体のすべてのポインタは、\fBgdbm\fP が解放するであろう
データを指す。これらは (標準的な UNIX　の \fBdbm\fP がするように)  静的ポインタとして扱う必要がある。


.SH リンク
このライブラリはコンパイル行の最後のパラメータとして \fI\-lgdbm\fP を 指定することで利用される。
.sp
  gcc \-o prog prog.c \-lgdbm

\fBdbm\fP や \fBndbm\fP との互換性ルーチンを使いたい場合は、
\fIgdbm_compat\fP ライブラリもリンクしなければならない。
例えば、以下のようにする。
.sp
  gcc \-o prog proc.c \-lgdbm \-lgdbm_compat

.SH バグ

.SH 関連項目
dbm, ndbm

.SH 著者
Philip A. Nelson と Jason Downs.  Copyright (C) 1990 \- 1999 Free Software
Foundation, Inc.

GDBM is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 1, or (at your option)  any later version.

GDBM is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public License along with
GDBM; see the file COPYING.  If not, write to the Free Software Foundation,
675 Mass Ave, Cambridge, MA 02139, USA.

You may contact the original author by:
.br
   e\-mail:  phil@cs.wwu.edu
.br
  us\-mail:  Philip A. Nelson
.br
Computer Science Department
.br
Western Washington University
.br
Bellingham, WA 98226

You may contact the current maintainer by:
.br
   e\-mail:  downsj@downsj.com