日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
DBOPEN(3) FreeBSD ライブラリ関数マニュアル DBOPEN(3)
名称
dbopen -- データベースアクセス方法
書式
#include <sys/types.h>
#include <db.h>
#include <fcntl.h>
#include <limits.h>
DB *
dbopen(const char *file, int flags, int mode, DBTYPE type,
const void *openinfo);
解説
dbopen() 関数は、データベースファイルへのライブラリインタフェースです。サ
ポートされるファイル形式は、btree で、ハッシュされ、そして UNIX ファイル
指向です。btree 形式は、ソートされ、バランスがとられたツリー構造の表現で
す。ハッシュされた形式は、拡張可能で、動的なハッシュスキームです。フラッ
トファイル (flat-file) 形式は、固定された長さか、または可変の長さのレコー
ドがあるバイトストリームのファイルです。形式とファイル形式特有の情報は、
それらの個別のマニュアルページ btree(3), hash(3) と recno(3) で詳細に説明
されています。
dbopen() 関数は、読み込みおよび書き込みのために file をオープンします。決
してディスクに保存することを目的としていないファイルは、file 引数を NULL
に設定することによって作成できます。
flags と mode 引数は、open(2) ルーチンに、明記されている通りですが、しか
しながら、O_CREAT, O_EXCL, O_EXLOCK, O_NOFOLLOW, O_NONBLOCK, O_RDONLY,
O_RDWR, O_SHLOCK, O_SYNC と O_TRUNC フラグだけに意味があります。(データ
ベースファイルを O_WRONLY でオープンすることはできないことに注意してくだ
さい)。
type 引数は、(<db.h> インクルードファイルで定義されるような) タイプ
DBTYPE であり、DB_BTREE, DB_HASH または DB_RECNO に設定されます。
openinfo 引数は、アクセス方式のマニュアルページで説明されるアクセス方式特
有の構造体へのポインタです。openinfo が NULL であるなら、各アクセス方式
は、システムとアクセス方式のために適切なデフォルトを使用します。
dbopen() 関数は、成功すると、DB 構造体へのポインタを返し、エラーになると
NULL を返します。DB 構造体は、<db.h> インクルードファイルで定義され、少な
くとも次のフィールドを含んでいます:
typedef struct {
DBTYPE type;
int (*close)(DB *db);
int (*del)(const DB *db, const DBT *key, u_int flags);
int (*fd)(const DB *db);
int (*get)(const DB *db, const DBT *key, DBT *data, u_int flags);
int (*put)(const DB *db, DBT *key, const DBT *data,
u_int flags);
int (*sync)(const DB *db, u_int flags);
int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
} DB;
これらの要素は、データベースのタイプと様々なアクションを実行する関数の
セットを記述しています。これらの関数は、dbopen() によって返される構造体へ
のポインタと時々キー/データ構造体とフラグ値への 1 つ以上のポインタを取り
ます。
type 基本的なアクセス方式のタイプ (とファイル形式)。
close あらゆるキャッシュされた情報をディスクにフラッシュし、あらゆる割
り付けられたリソースを解放し、基本的な (複数の) ファイルをクロー
ズするルーチンへのポインタ。キー/データのペアは、メモリにキャッ
シュされるので、close または sync 関数でファイルを sync すること
に失敗することは、情報の一貫性がないか、または情報が失われる結果
となります。close ルーチンは、エラーになると (errno を設定して)
-1 を返し、成功すると 0 を返します。
del データベースからキー/データのペアを削除するルーチンへのポインタ。
flags 引数は、次の値に設定されます:
R_CURSOR
カーソルによって参照されるレコードを削除します。カーソル
は、以前に初期化されていなければなりません。
delete ルーチンは、エラーになると (errno を設定して) -1 を返し、
成功すると 0 を返し、指定された key がファイルになかったなら、1
を返します。
fd 基本的なデータベースを代表するファイル記述子を返す、ルーチンへの
ポインタ。同じファイルを参照しているファイル記述子は、同じ file
名で dbopen() を呼び出す、すべてのプロセスに返されます。このファ
イル記述子は、fcntl(2) と flock(2) ロック関数への引数として安全に
使用されます。ファイル記述子は、必ずしもアクセス方式によって使用
される基本的なファイルのいずれとも関連しません。ファイル記述子
は、メモリ内のデータベースで利用可能ではありません。fd ルーチン
は、エラーになると (errno を設定して) -1 を返し、成功すれば、ファ
イル記述子を返します。
get データベースからキーのある検索して取り出されるインタフェースであ
る、ルーチンへのポインタ。指定された key と関連するデータのアドレ
スと長さは、data によって参照される構造体に返されます。get ルーチ
ンは、エラーになると (errno を設定して) -1 を返し、key がファイル
になかったなら、1 を返します。
put キー/データのペアをデータベースに格納するルーチンへのポインタ。
flags 引数は、次の値の 1 つに設定されます:
R_CURSOR
カーソルによって参照されるキー/データのペアを置き換えま
す。カーソルは、以前に初期化されていなければなりません。
R_IAFTER
新しいキー/データのペアを作成して、key によって参照される
データの直後にデータを追加します。追加されたキー/データの
ペアのレコード番号は、key 構造体に返されます。(DB_RECNO
アクセス方式にのみ適用可能です。)
R_IBEFORE
新しいキー/データのペアを作成して、key によって参照された
データの直前にデータを挿入します。挿入されたキー/データの
ペアのレコード番号は、key 構造体に返されます。(DB_RECNO
アクセス方式にのみ適用可能です。)
R_NOOVERWRITE
キーが以前に存在しない場合のみ新しいキー/データのペアを入
力します。
R_SETCURSOR
キー/データのペアを参照するカーソルの位置を設定するか、ま
たは初期化して、それを格納します。(DB_BTREE と DB_RECNO
アクセス方式にのみ適用可能です。)
キーが変更されない固有の順序があることを意味しているので、
R_SETCURSOR は、DB_BTREE と DB_RECNO アクセス方式のためだけに利用
可能です。
それらが、それぞれアクセス方式が新しいキーを作成することができる
ことを意味しているので、R_IAFTER と R_IBEFORE は、DB_RECNO アクセ
ス方式だけに利用可能です。これは、キーが、例えば、レコード番号の
ように、順序付けられ、独立である場合のみ、真です。
put ルーチンのデフォルトの振る舞いは、以前に存在しているあらゆる
キーを置き換えて、新しいキー/データのペアに入力することです。
put ルーチンは、エラーになると (errno を設定して) -1 を返し、
R_NOOVERWRITE フラグが設定され、まだキーがファイルに存在するな
ら、1 を返します。
seq データベースからシーケンシャルの検索して取り出すためのインタ
フェースであるルーチンへのポインタ。キーのアドレスと長さは、key
によって参照される構造体に返され、データのアドレスと長さは、data
によって参照される構造体に返されます。
シーケンシャルなキー/データのペアの検索して取り出すことは、いつで
も始まり、``cursor'' の位置は、del, get, put または sync ルーチン
への呼び出しによって影響されません。シーケンシャルなスキャンの間
のデータベースの修正は、スキャンに反映されます、すなわち、カーソ
ルの後ろに挿入されたレコードは、返されませんが、一方、カーソルの
前に挿入されたレコードは、返されます。
flags 引数は、次の値の 1 つに設定されなければなりません:
R_CURSOR
指定されたキーと関連するデータが、返されます。これは、同
様にキーの位置にカーソルを設定するか、または初期化すると
いう点で、get ルーチンと異なます。(注、DB_BTREE アクセス
方式について、返されたキーは、必ずしも、指定されたキーと
正確に一致する必要がありません。返されるキーは、部分的な
キーの一致と範囲検索を許可して、指定されたキーより大きい
か等しい最小のキーです。)
R_FIRST
データベースの最初のキー/データのペアが、返され、カーソル
は、それを参照するように設定されるか、または初期化されま
す。
R_LAST データベースの最後のキー/データのペアが、返され、カーソル
は、それを参照するように設定されるか、または初期化されま
す。(DB_BTREE と DB_RECNO アクセス方式にのみ適用可能で
す。)
R_NEXT カーソルの直後でキー/データのペアを検索して取り出します。
カーソルがまだ設定されていないなら、これは、R_FIRST フラ
グと同じです。
R_PREV カーソルの直前でキー/データのペアを検索して取り出します。
カーソルがまだ設定されていないなら、これは、R_LAST フラグ
と同じです。(DB_BTREE と DB_RECNO アクセス方式にのみ適用
可能です。)
それらは、それぞれ、キーが変更されない固有の順序があることを意味
しているので、R_LAST と R_PREV は、DB_BTREE と DB_RECNO アクセス
方式のためだけで利用可能です。
seq ルーチンは、エラーになると (errno を設定して) -1 を返し、成功
すると 0 を返し、指定されるか、または現在のキーより小さいか、また
は大きいキー/データのペアがないなら、1 を返します。DB_RECNO アク
セス方式が使用されているなら、そして、データベースファイルがキャ
ラクタ特殊ファイルであり、完全なキー/データのペアが、現在、利用可
能ではないなら、seq ルーチンは、2 を返します。
sync あらゆるキャッシュされた情報をディスクにフラッシュするルーチンへ
のポインタ。データベースがメモリ内のみにあるなら、sync ルーチンに
は、効果がなく、常に成功します。
flags 引数は、次の値に設定されます:
R_RECNOSYNC
DB_RECNO アクセス方式が使用されているなら、このフラグに
よって、sync ルーチンは、recno ファイル自体ではなく、
recno ファイルの根底にある btree ファイルに適用します。
(詳細については、recno(3) マニュアルページの bfname
フィールドを参照してください。)
sync ルーチンは、エラーになると (errno を設定して) -1 を返し、成
功すると 0 を返します。
キー/データのペア
すべてのファイルのタイプへのアクセスは、キー/データのペアに基づいていま
す。キーとデータの両方は、次のデータ構造によって表されます:
typedef struct {
void *data;
size_t size;
} DBT;
DBT 構造体の要素は、次のように定義されています:
data バイト列へのポインタ。
size バイト列の長さ。
キーとデータバイト文字列は、それらのうちのいずれか 2 つは、同時に利用可能
なメモリに適合しなければなりませんが、本質的に無限の長さの文字列を参照し
ます。アクセス方式は、バイト列の整列に関して保証を提供しないことに注意す
るべきです。
エラー
dbopen() ルーチンは、失敗して、ライブラリルーチン open(2) と malloc(3) ま
たは次で明記されたエラーのいずれかを errno に設定します:
[EFTYPE] ファイルが、間違って書式化されています。
[EINVAL] (ハッシュ関数、パッドバイトなど) 引数が指定されまし
た、すなわち、現在のファイル指定と互換性がないか、また
は (例えば、事前の初期化なしのカーソルの使用) 関数のた
めに意味のない、またはファイルのバージョン番号とソフト
ウェアの間に不一致があります。
close ルーチンは、失敗して、ライブラリルーチン close(2), read(2),
write(2), free(3) または fsync(2) で明記されたエラーのいずれかを errno に
設定します:
del, get, put と seq ルーチンは、失敗して、ライブラリルーチン read(2),
write(2), free(3) または malloc(3) で明記されたエラーのいずれかを errno
に設定します。
fd ルーチンは、失敗して、errno をメモリデータベースのために ENOENT に設定
します。
sync ルーチンは、失敗して、ライブラリルーチン fsync(2) で明記されたエラー
のいずれかを errno に設定します。
関連項目
btree(3), hash(3), mpool(3), recno(3)
Margo Seltzer and Michael Olson, LIBTP: Portable, Modular Transactions
for UNIX, USENIX proceedings, Winter 1992.
バグ
The typedef DBT は、``data base thang'' のためのニーモニックであり、まだ
使用されていなかった妥当な名前について誰も考えつくことができなかったの
で、使用されました。
ファイル記述子インタフェースは、kludge であり、インタフェースの将来のバー
ジョンで削除されるかもしれません。訳注: kludge (クラッジ): 便宜的にトリッ
クを使って問題を一時的に解決すること。
アクセス方式のいずれも、並列アクセス、ロックまたはトランザクションのあら
ゆる形式を提供していません。
FreeBSD 11.2 September 10, 2010 FreeBSD 11.2