リナックスコマンド

gdbmのヘルプ・マニュアル

日本語 英語

• help
• man

gdbm --help

man gdbm

GDBM(3) GDBM(3) 名前 GDBM - GNU データベース・マネージャ。dbm および ndbm 互換機能を含む。 (Version 1.8.) 書式 #include extern gdbm_error gdbm_errno extern char *gdbm_version GDBM_FILE gdbm_open (name, block_size, read_write, mode, fatal_func) char * name; int block_size, read_write, mode; void (*fatal_func) (); void gdbm_close (dbf) GDBM_FILE dbf; int gdbm_store (dbf, key, content, flag) GDBM_FILE dbf; datum key, content; int flag; datum gdbm_fetch (dbf, key) GDBM_FILE dbf; datum key; int gdbm_delete (dbf, key) GDBM_FILE dbf; datum key; datum gdbm_firstkey (dbf) GDBM_FILE dbf; datum gdbm_nextkey (dbf, key) GDBM_FILE dbf; datum key; int gdbm_reorganize (dbf) GDBM_FILE dbf; void gdbm_sync (dbf) GDBM_FILE dbf; int gdbm_exists (dbf, key) GDBM_FILE dbf; datum key; char * gdbm_strerror (errno) gdbm_error errno; int gdbm_setopt (dbf, option, value, size) GDBM_FILE dbf; int option; int *value; int size; int gdbm_fdesc (dbf) GDBM_FILE dbf; DBM Compatability routines: #include int dbminit (name) char *name; int store (key, content) datum key, content; datum fetch (key) datum key; int delete (key) datum key; datum firstkey () datum nextkey (key) datum key; int dbmclose () NDBM Compatability routines: #include DBM *dbm_open (name, flags, mode) char *name; int flags, mode; void dbm_close (file) DBM *file; datum dbm_fetch (file, key) DBM *file; datum key; int dbm_store (file, key, content, flags) DBM *file; datum key, content; int flags; int dbm_delete (file, key) DBM *file; datum key; datum dbm_firstkey (file) DBM *file; datum dbm_nextkey (file) DBM *file; int dbm_error (file) DBM *file; int dbm_clearerr (file) DBM *file; int dbm_pagfno (file) DBM *file; int dbm_dirfno (file) DBM *file; int dbm_rdonly (file) DBM *file; 説明 GNU dbm は、キーとデータのペアを含んだデータファイルを取り扱うルーチ ン 群 のライブラリである。提供されるアクセスとしては、キーによる格納、キー による取り出し、キーによる削除の他、すべてのキーに渡るソートされてい な い 横断的なアクセスがある。一つのプロセスからは複数のデータファイルを同 時に利用することができる。 gdbm ファイルをオープンするプロセスは、「リーダ」または「ライタ」と呼ば れ る。 1 つの gdbm ファイルをオープンできるライタは 1 つだけだが、リー ダは複数が 1 つの gdbm ファイルをオープンすることができる。 リーダとライタは同時に同じファイルをオープンすることはできない 。 gdbm ファイルをオープンする手続きは： GDBM_FILE dbf; dbf = gdbm_open ( name, block_size, read_write, mode, fatal_func ) name はファイルの名前である。(完全な名前、gdbm はこの名前に文字列を付け 加えるようなことはしない) block_size はディスクからメモリへ 1 回に転 送 さ れるサイズである。このパラメータは、新しいファイルの場合以外は無視さ れる。最小サイズは 512 である。 512 よりも小さい場合には, gdbm はファイ ル システムに対する stat のブロックサイズを使用する。 read_write には以 下のいずれかの値を取る。 GDBM_READER リーダ GDBM_WRITER ライタ GDBM_WRCREAT ライタ - データベースが存在しなければ作成する GDBM_NEWDB ライタ - すでに存在しても新しいデータベースを作成する 最後の 3 つについては (データベースのライタ) read_write に対して以下 を ビ ットの OR により追加できる: GDBM_SYNC はすべてのデータベースの操作を ディスクと同期する、また GDBM_NOLOCK はデータベースファイルに関するライ ブラリからのロック動作を行わない。オプション GDBM_FAST は gdbm の既定動 作が no-sync モードになったためにもう使われなくなった。 mode はファイルのモードである (chmod(2) お よ び open(2) を 参 照) 。(*fatal_func) () は dbm が致命的エラーを検出した場合に呼び出す関数で ある。この関数への唯一のパラメータは文字列である。値 0 が指定され る と 、gdbm はデフォルトの関数を使用する。 返り値 dbf は、その gdbm ファイルにアクセスする他のすべてのルーチンに必 要なポインタである。 NULL ポインタが返った場合、gdbm_open は成功しな か っ た こ と を示す。 gdbm のエラーは gdbm_errno に、システムのエラーは errno に格納される。(エラーコードについては gdbmerrno.h を参照) 以下のすべてのコールにおいては、パラメータ dbf は gdbm_open から返っ て き たポインタである。どんなファイルでもオープンしたものをクローズするこ とは重要である。クローズはファイルに対するリーダ数／ライタ数を更新す る 。これは以下のようにして行う。 gdbm_close (dbf); データベースは 3 つの主なルーチンによって利用できる。最初はデータをデー タベースに格納するものである。 ret = gdbm_store ( dbf, key, content, flag ) dbf は gdbm_open から返ってきたポインタである。 key はキ ー デ ー タ で 、content は key に関連付けられたデータである。 flag は以下のいずれかの 値を持つことができる。 GDBM_INSERT 挿入のみ。キーが存在すればエラーとなる。 GDBM_REPLACE キーが存在すれば内容を更新する。 リーダが gdbm_store をコールした場合、返り値は -1 となる。 GDBM_INSERT が 指定された時にデータベースに key が存在すると、返り値は 1 である。そ うでなければ返り値は 0 である。 注意: 既にデータベースに存在するキーを 指 定 し て 格 納 す る 場 合 、 GDBM_REPLACEで呼び出しているならば、gdbm は古いデータを新しいデータで置 き換える。同じキーで 2 つのデータ・アイテムを得ることはできないし、また gdbm_store がエラーを返すこともない。 注意: gdbm のサイズは、dbm や ndbm と異なり制限されない。データは必要な だけ大きくすることができる。 データを検索するには、以下のようにする: content = gdbm_fetch ( dbf, key ) dbf は gdbm_open から返ってきたポインタである。 key はキーデータであ る 。 返 り値の dptr が NULL の場合、データは見つからなかった。見つかった場合 はデータへのポインタが返る。 dptr の記憶空間は malloc(3C) により確保 さ れ る。 gdbm は自動的にこのデータを解放することはしない。必要の無くなっ た領域を解放するのはプログラマの責任である。 データを参照せずに、検索だけする場合には： ret = gdbm_exists ( dbf, key ) dbf は gdbm_open から返ってきたポインタである。 key は検索したいキー デ ータである。 デ ータベース内に key が見つかれば、返り値 ret は true である。何も対応 するものが見つからなければ ret は false である。 gdbm_fetch ではメモリ確保が行われるが、このルーチンはそれをしないので、 レコードの存在をチェックをする時に役に立つ。 データベースからあるデータを削除する場合は、以下のようにする: ret = gdbm_delete ( dbf, key ) dbf は gdbm_open から返ってきたポインタである。key は削除したいキーデー タである。 アイテムが存在しなかったり、要求したのがリーダだった場合、返り値 は -1 である。削除に成功すれば返り値は 0 である。 次の 2 つのルーチンは、データベース中のすべてのアイテムにアクセスできる 。アクセスはキー順ではないが、データベース内ですべてのキーに各 1 回アク セスすることは保証されている。(アクセス順序はハッシュ値の順になる。) key = gdbm_firstkey ( dbf ) nextkey = gdbm_nextkey ( dbf, key ) dbf は gdbm_open から返ってきたポインタである。key はキーデータである。 返り値はどちらも datum 型である。返り値の dptr 要素が NULL の場合、最初 の キーまたは次のキーがなかったことを示す。返り値の dptr 要素が指してい るのは malloc(3C) により確保されたデータであり、gdbm は free してはくれ ないことにもう一度注意すること。 こ れらの関数はデータベースをリードオンリーで参照することを意図していた 。たとえば、データベースの正当性を確認したりするような目的で。 ファイルへの「参照」は「ハッシュ・テー ブ ル 」 に 基 づ い て い る 。 gdbm_delete はハッシュ・テーブルを再構成して、「見つけられることのない 」アイテムがテーブルの中で放置されないように、すべての競合を確認する 。 す べてのデータの実体に変更を加えなかったとしても、オリジナルのキーの順 序は保証されない。 以下のループが実行された場合、いくつかのキーが見つけられないことが起 こ り得る。 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 ) もしあなたがたくさんの削除を行い、gdbm ファイルが使っているスペースを小 さくしたいと思うならば、このルーチンはデータベースの再構成を行う。 gdbm は この再構成以外で gdbm が使っているファイルの大きさを小さくすることは 無い。(削除されたスペースは再利用される) データベースが GDBM_SYNC フラグ付きで open されない限り、gdbm は次の 動 作 を継続する前に、write がディスクにフラッシュするのを待つようなことは しない。次のルーチンはデータベースを物理的にディスクに書き出すことを 保 証する。 gdbm_sync ( dbf ) こ れはメインメモリの状態をディスクの状態と同期させるまでは戻って来ない 。 gdbm のエラーコードを英文のテキストに変換するには、次のルーチンを利用す る。 ret = gdbm_strerror ( errno ) こ こで errno は gdbm_error 型であり、通常はグローバル変数の gdbm_errno である。対応するフレーズが返ってくる。 gdbm は既に open されているファイルに対するオプションを設定できる機能を サポートしている。 ret = gdbm_setopt ( dbf, option, value, size ) ここで、dbf は直前の gdbm_open の返り値であり、 option は設定したいオプ ションを指定する。現在の正しいオプションは： GDBM_CACHESIZE - 内部の bucket キャッシュのサイズを指定する。このオプシ ョンは GDBM_FILE のディスクリプタに一度だけ設定でき、データベースの最初 のアクセス時に自動的に 100 が設定される。 GDBM_FASTMODE - fast mode の on, off を指定する。 fast mode はすでに オ ープンされていて、アクティブなデータベースに対してトグル (on, off) でき る。value (以下参照) は TRUE か FALSE が設定できる。このオプションは も う使われない。 GDBM_SYNCMODE - ファイルシステムの同期処理を on, off する。この設定のデ フォルトは off である。value (以下参照) は TRUE か FALSE を指定する。 GDBM_CENTFREE - central フリーブロックプール を on, off する。デフォ ル トは off であり、これは以前のバージョンの gdbm のフリーブロックの取り扱 いと同じである。もし、設定されると、このオプションはその後はフリーブ ロ ックはグローバルプールにおかれ、(理論的には) より多くのファイルスペース がより早く再利用されるようになる。 value (以下参照) は TRUE か FALSE を 設定すべきである。注意：この機能はまだ検討中である。 GDBM_COALESCEBLKS - フリーブロックマージングの on, off を設定する。デフ ォルトは off で前のバージョンの gdbm のフリーブロックの扱いと同じである 。 もし、設定されるとこのオプションは、付近にあるフリーブロックをマージ する。これは 特にGDBM_CENTFREE と一緒に使われたとしても 時間と CPU のか か る処理になる。value (以下参照) は TRUE か FALSE を設定するべきである 。注意：この機能はまだ検討中である。 value は option に設定する値であり、integer へのポインタである 。 size は value によってポイントされるデータのサイズである。返り値は 失敗した 場合 -1 になり、成功したら 0 になる。失敗の場合、グロ ー バ ル 変 数 の gdbm_errno には値が設定される。 例 えば、gdbm_open でオープンしたデータベースをアクセスする前に、キャッ シュとして 10 を使うように設定する場合、以下のコードが利用できる： int value = 10; ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int)); もしデータベースが GDBM_NOLOCK フラグ付きでオープンされた場合、ユーザは デ ータベースに対して、例えば複数のライタ操作を同一のファイルに対して行 うような、自分の独自のファイルロッキングを使うことができる、 これをサポートするため、gdbm_fdesc ルーチンが提供される。 ret = gdbm_fdesc ( dbf ) ここで dbf は以前の gdbm_open の返り値である。返り値はデータベースのフ ァイルディスクリプタである。 以下の 2 つの外部変数は役に立つことだろう。 gdbm_errno は gdbm のエラー に関するより詳しい情報を持つ。 (gdbm.h はエラー値の定義と gdbm_errno を 外部変数とする定義を持つ) gdbm_version はバージョン情報の文字列を持つ。 も う少し興味深いことが幾つかある。まず gdbm は「隙間のある」ファイルで は無いということである。あなたはこのファイルを UNIX の cp(1) コマンドに よ ってコピーすることが可能で、そのコピー処理の間にファイルサイズが拡張 されるようなことはない。さらに、UNIX ですでに使われている dbm のコン パ チブルモードが存在する。このコンパチブルモードでは、gdbm のファイルポイ ンタはプログラマに取って必要ではなく、一度には 1 つのファイルだけがオー プ ン さ れる。コンパチブルモード全ての利用者はライタと見なされる。もし 、gdbm ファイルがリードオンリーならば、ライタとしては失敗し、リーダとし てオープンし直しを試みる。datum 構造体のすべてのポインタは、gdbm が解放 するであろうデータを指す。これらは (標準的な UNIX の dbm がするように) 静的ポインタとして扱う必要がある。 リンク こ のライブラリはコンパイル行の最後のパラメータとして -lgdbm を指定する ことで利用される。 gcc -o prog prog.c -lgdbm バグ 関連項目 dbm, ndbm 著者 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 FIT- NESS 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: e-mail: phil@cs.wwu.edu us-mail: Philip A. Nelson Computer Science Department Western Washington University Bellingham, WA 98226 You may contact the current maintainer by: e-mail: downsj@downsj.com 5/19/99 GDBM(3)