.ds ve 1.8 .TH GDBM 3 5/19/99 .\" Japanese Version Copyright (c) 2000 Tsugikazu Shibata .\" all rights reserved. .\" Translated Fri. August 29 23:32:00 JST 2000 .\" by Tsugikazu Shibata .SH 名前 GDBM - GNUデータベース・マネージャ。\fBdbm\fR および \fBndbm\fR 互換機能を含む。 (Version \*(ve.) .SH 書式 .B #include .PP .SM .B extern gdbm_error .br .B gdbm_errno .PP .B extern char .br .B *gdbm_version .PP .B GDBM_FILE .br .B gdbm_open (name, block_size, read_write, mode, fatal_func) .br .B char * name; .br .B int block_size, read_write, mode; .br .B void (*fatal_func) (); .PP .B void .br .B gdbm_close (dbf) .br .B GDBM_FILE dbf; .PP .B int .br .B gdbm_store (dbf, key, content, flag) .br .B GDBM_FILE dbf; .br .B datum key, content; .br .B int flag; .PP .B datum .br .B gdbm_fetch (dbf, key) .br .B GDBM_FILE dbf; .br .B datum key; .PP .B int .br .B gdbm_delete (dbf, key) .br .B GDBM_FILE dbf; .br .B datum key; .PP .B datum .br .B gdbm_firstkey (dbf) .br .B GDBM_FILE dbf; .PP .B datum .br .B gdbm_nextkey (dbf, key) .br .B GDBM_FILE dbf; .br .B datum key; .PP .B int .br .B gdbm_reorganize (dbf) .br .B GDBM_FILE dbf; .PP .B void .br .B gdbm_sync (dbf) .br .B GDBM_FILE dbf; .PP .B int .br .B gdbm_exists (dbf, key) .br .B GDBM_FILE dbf; .br .B datum key; .PP .B char * .br .B gdbm_strerror (errno) .br .B gdbm_error errno; .PP .B int .br .B gdbm_setopt (dbf, option, value, size) .br .B GDBM_FILE dbf; .br .B int option; .br .B int *value; .br .B int size; .PP .B int .br .B gdbm_fdesc (dbf) .br .B GDBM_FILE dbf; .PP .PP .B DBM Compatability routines: .PP .B #include .PP .SM .B int .br .B dbminit (name) .br .B char *name; .PP .B int .br .B store (key, content) .br .B datum key, content; .PP .B datum .br .B fetch (key) .br .B datum key; .PP .B int .br .B delete (key) .br .B datum key; .PP .B datum .br .B firstkey () .PP .B datum .br .B nextkey (key) .br .B datum key; .PP .B int .br .B dbmclose () .PP .PP .B NDBM Compatability routines: .PP .B #include .PP .SM .B DBM .br .B *dbm_open (name, flags, mode) .br .B char *name; .br .B int flags, mode; .PP .B void .br .B dbm_close (file) .br .B DBM *file; .PP .B datum .br .B dbm_fetch (file, key) .br .B DBM *file; .br .B datum key; .PP .B int .br .B dbm_store (file, key, content, flags) .br .B DBM *file; .br .B datum key, content; .br .B int flags; .PP .B int .br .B dbm_delete (file, key) .br .B DBM *file; .br .B datum key; .PP .B datum .br .B dbm_firstkey (file) .br .B DBM *file; .PP .B datum .br .B dbm_nextkey (file) .br .B DBM *file; .PP .B int .br .B dbm_error (file) .br .B DBM *file; .PP .B int .br .B dbm_clearerr (file) .br .B DBM *file; .PP .B int .br .B dbm_pagfno (file) .br .B DBM *file; .PP .B int .br .B dbm_dirfno (file) .br .B DBM *file; .PP .B int .br .B dbm_rdonly (file) .br .B DBM *file; .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\fR はファイルの名前である。(完全な名前、gdbm はこの名前に 文字列を付け加えるようなことはしない) \fIblock_size\fR はディスクからメモリへ 1 回に転送されるサイズである。 このパラメータは、新しいファイルの場合以外は無視される。最小サイズ は 512 である。 512 よりも小さい場合には, gdbm はファイルシステムに対する stat のブロックサイズを使用する。 \fIread_write\fR には以下のいずれかの値を取る。 .br .B GDBM_READER リーダ .br .B GDBM_WRITER ライタ .br .B GDBM_WRCREAT ライタ - データベースが存在しなければ作成する .br .B GDBM_NEWDB ライタ - すでに存在しても新しいデータベースを作成する .br 最後の 3 つについては (データベースのライタ) \fIread_write\fR に対して 以下をビットの OR により追加できる: .B GDBM_SYNC はすべてのデータベースの操作をディスクと同期する、また .B GDBM_NOLOCK はデータベースファイルに関するライブラリからのロック動作を行わない。 オプション .B GDBM_FAST は gdbm の既定動作が no-sync モードになったためにもう使われなくなった。 .br \fImode\fR はファイルのモードである (\fBchmod(2)\fR および \fBopen(2)\fR を 参照)。\fI(*fatal_func) ()\fR は dbm が致命的エラーを検出した場合に呼び出す 関数である。この関数への唯一のパラメータは文字列である。 値 0 が指定されると、gdbm はデフォルトの関数を使用する。 返り値 \fIdbf\fR は、その gdbm ファイルにアクセスする他のすべてのルーチン に必要なポインタである。 NULL ポインタが返った場合、\fBgdbm_open\fR は 成功しなかったことを示す。 gdbm のエラーは \fIgdbm_errno\fR に、システムのエラーは \fIerrno\fR に格納される。(エラーコードについては gdbmerrno.h を参照) 以下のすべてのコールにおいては、 パラメータ \fIdbf\fR は \fBgdbm_open\fR から 返ってきたポインタである。 どんなファイルでもオープンしたものをクローズすることは重要である。 クローズはファイルに対するリーダ数／ライタ数を更新する。 これは以下のようにして行う。 gdbm_close (dbf); データベースは 3 つの主なルーチンによって利用できる。最初はデータを データベースに格納するものである。 ret = gdbm_store ( dbf, key, content, flag ) \fIdbf\fR は \fBgdbm_open\fR から返ってきたポインタである。 \fIkey\fR はキーデータで、\fIcontent\fR は \fIkey\fR に関連付けられた データである。 \fIflag\fR は以下のいずれかの値を持つことができる。 .br .B GDBM_INSERT 挿入のみ。キーが存在すればエラーとなる。 .br .B GDBM_REPLACE キーが存在すれば内容を更新する。 リーダが \fBgdbm_store\fR をコールした場合、返り値は -1 となる。 GDBM_INSERT が指定された時にデータベースに \fIkey\fR が存在すると、 返り値は 1 である。そうでなければ返り値は 0 である。 \fI注意: 既にデータベースに存在するキーを指定して格納する場合、 GDBM_REPLACEで呼び出しているならば、gdbm は古いデータを 新しいデータで置き換える。 同じキーで 2 つのデータ・アイテムを得ることはできないし、 また gdbm_store がエラーを返すこともない。 注意: gdbm のサイズは、dbm や ndbm と異なり制限されない。 データは必要なだけ大きくすることができる。 \fR データを検索するには、以下のようにする: content = gdbm_fetch ( dbf, key ) \fIdbf\fR は \fBgdbm_open\fR から返ってきたポインタである。 \fIkey\fR はキーデータである。 返り値の \fIdptr\fR が NULL の場合、データは見つからなかった。 見つかった場合はデータへのポインタが返る。 \fIdptr\fR の記憶空間は \fBmalloc(3C)\fR により確保される。 \fBgdbm\fI は自動的にこのデータを解放することはしない。 必要の無くなった領域を解放するのはプログラマの責任である。\fR データを参照せずに、検索だけする場合には： ret = gdbm_exists ( dbf, key ) \fIdbf\fR は \fBgdbm_open\fR から返ってきたポインタである。 \fIkey\fR は検索したいキーデータである。 データベース内に \fIkey\fR が見つかれば、返り値 \fIret\fR は true である。 .\" If nothing appropiate is found, \fIret\fR will be false. 何も対応するものが見つからなければ \fIret\fR は false である。 \fBgdbm_fetch\fR ではメモリ確保が行われるが、このルーチンはそれをしない ので、レコードの存在をチェックをする時に役に立つ。 データベースからあるデータを削除する場合は、以下のようにする: ret = gdbm_delete ( dbf, key ) \fIdbf\fR は \fBgdbm_open\fR から返ってきたポインタである。\fIkey\fR は 削除したいキーデータである。 アイテムが存在しなかったり、要求したのがリーダだった場合、 返り値は -1 である。 削除に成功すれば返り値は 0 である。 次の 2 つのルーチンは、データベース中のすべてのアイテムにアクセスできる。 アクセスはキー順ではないが、データベース内ですべてのキーに各 1 回 アクセスすることは保証されている。(アクセス順序はハッシュ値の順になる。) key = gdbm_firstkey ( dbf ) nextkey = gdbm_nextkey ( dbf, key ) \fIdbf\fR は \fBgdbm_open\fR から返ってきたポインタである。\fIkey\fR は キーデータである。 返り値はどちらも \fBdatum\fR 型である。返り値の \fIdptr\fR 要素が NULL の場合、最初のキーまたは次のキーがなかったことを示す。 返り値の \fIdptr\fR 要素が指しているのは \fBmalloc(3C)\fR により確保されたデータであり、\fBgdbm\fR は free してはくれないことに もう一度注意すること。 これらの関数はデータベースをリードオンリーで参照することを意図していた。 たとえば、データベースの正当性を確認したりするような目的で。 ファイルへの「参照」は「ハッシュ・テーブル」に基づいている。 \fIgdbm_delete\fR はハッシュ・テーブルを再構成して、「見つけられることのない」 アイテムがテーブルの中で放置されないように、すべての競合を確認する。 すべてのデータの実体に変更を加えなかったとしても、オリジナルのキーの 順序は保証されない。 .\" It is possible that some key will not be visited if a loop like .\" the following is executed: 以下のループが実行された場合、いくつかのキーが見つけられ ないことが起こり得る。 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\fR ファイルが使っている スペースを小さくしたいと思うならば、このルーチンはデータベースの再構成を行う。 \fBgdbm\fR はこの再構成以外で \fBgdbm\fR が使っているファイルの大きさを 小さくすることは無い。(削除されたスペースは再利用される) データベースが GDBM_SYNC フラグ付きで open されない限り、gdbm は次の動作を 継続する前に、write がディスクにフラッシュするのを待つようなことはしない。 次のルーチンはデータベースを物理的にディスクに書き出すことを保証する。 gdbm_sync ( dbf ) これはメインメモリの状態をディスクの状態と同期させるまでは戻って来ない。 \fBgdbm\fR のエラーコードを英文のテキストに変換するには、次のルーチン を利用する。 ret = gdbm_strerror ( errno ) ここで \fIerrno\fR は \fIgdbm_error\fR 型であり、通常はグローバル変数 の \fIgdbm_errno\fR である。対応するフレーズが返ってくる。 \fBgdbm\fR は既に open されているファイルに対するオプションを設定できる 機能をサポートしている。 ret = gdbm_setopt ( dbf, option, value, size ) ここで、\fIdbf\fR は直前の \fBgdbm_open\fR の返り値であり、 \fIoption\fR は設定したいオプションを指定する。現在の正しいオプションは： \fBGDBM_CACHESIZE\fR - 内部の bucket キャッシュのサイズを指定する。 このオプションは \fIGDBM_FILE\fR のディスクリプタに一度だけ設定でき、 データベースの最初のアクセス時に自動的に 100 が設定される。 \fBGDBM_FASTMODE\fR - \fBfast mode\fR の on, off を指定する。 \fBfast mode\fR はすでにオープンされていて、アクティブなデータベースに 対してトグル (on, off) できる。\fIvalue\fR (以下参照) は TRUE か FALSE が設定できる。このオプションはもう使われない。 \fBGDBM_SYNCMODE\fR - ファイルシステムの同期処理を on, off する。この 設定のデフォルトは off である。\fIvalue\fR (以下参照) は TRUE か FALSE を指定する。 \fBGDBM_CENTFREE\fR - \fBcentral フリーブロックプール\fR を on, off する。 デフォルトは off であり、これは以前のバージョンの \fBgdbm\fR のフリー ブロックの取り扱いと同じである。もし、設定されると、このオプションはそ の後はフリーブロックはグローバルプールにおかれ、(理論的には) より多くの ファイルスペースがより早く再利用されるようになる。 \fIvalue\fR (以下参照) は TRUE か FALSE を設定すべきである。 注意：この機能はまだ検討中である。 \fBGDBM_COALESCEBLKS\fR - フリーブロックマージングの on, off を設定 する。デフォルトは off で前のバージョンの \fBgdbm\fR のフリーブロック の扱いと同じである。もし、設定されるとこのオプションは、付近にあるフリー ブロックをマージする。これは 特に\fBGDBM_CENTFREE\fR と一緒に使われた としても 時間と CPU のかかる処理になる。\fIvalue\fR (以下参照) は TRUE か FALSE を設定するべきである。 注意：この機能はまだ検討中である。 \fIvalue\fR は \fIoption\fR に設定する値であり、integer へのポインタ である。 \fIsize\fR は \fIvalue\fR によってポイントされるデータの サイズである。返り値は 失敗した場合 -1 になり、成功したら 0 になる。 失敗の場合、グローバル変数の \fIgdbm_errno\fR には値が設定される。 例えば、\fBgdbm_open\fR でオープンしたデータベースをアクセスする前に、 キャッシュとして 10 を使うように設定する場合、以下のコードが利用できる： int value = 10; ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int)); もしデータベースが \fBGDBM_NOLOCK\fR フラグ付きでオープンされた場合、 ユーザはデータベースに対して、例えば複数のライタ操作を同一のファイル に対して行うような、自分の独自のファイルロッキングを使うことができる、 これをサポートするため、\fIgdbm_fdesc\fR ルーチンが提供される。 ret = gdbm_fdesc ( dbf ) ここで \fIdbf\fR は以前の \fBgdbm_open\fR の返り値である。 返り値はデータベースのファイルディスクリプタである。 以下の 2 つの外部変数は役に立つことだろう。 \fIgdbm_errno\fR は gdbm のエラーに関するより詳しい情報を持つ。 (gdbm.h はエラー値の定義と gdbm_errno を外部変数とする定義を持つ) .br \fIgdbm_version\fR はバージョン情報の文字列を持つ。 もう少し興味深いことが幾つかある。まず \fBgdbm\fR は「隙間のある」 ファイルでは無いということである。あなたはこのファイルを UNIX の \fBcp(1)\fR コマンドによってコピーすることが可能で、そのコピー処理の間 にファイルサイズが拡張されるようなことはない。さらに、UNIX ですでに使 われている \fBdbm\fR のコンパチブルモードが存在する。このコンパチブル モードでは、\fRgdbm\fR のファイルポインタはプログラマに取って必要では なく、一度には 1 つのファイルだけがオープンされる。コンパチブルモード 全ての利用者はライタと見なされる。もし、\fBgdbm\fR ファイルがリード オンリーならば、ライタとしては失敗し、リーダとしてオープンし直しを 試みる。datum 構造体のすべてのポインタは、\fBgdbm\fR が解放するであろう データを指す。これらは (標準的な UNIX　の \fBdbm\fR がするように) 静的ポインタとして扱う必要がある。 .SH リンク このライブラリはコンパイル行の最後のパラメータとして \fI-lgdbm\fR を 指定することで利用される。 .sp gcc -o prog prog.c -lgdbm .SH バグ .SH 関連項目 dbm, ndbm .SH 著者 by Philip A. Nelson and 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